itsscb/tracing
1
0
Fork 0
mirror of https://github.com/tokio-rs/tracing.git synced 2025-10-02 07:20:35 +00:00
Code Issues Packages Projects Releases Wiki Activity

appender: clarify file appender docs (#2689)

Browse Source 
## Motivation

There are a few errors in the file appender docs - this fixes them.

It also wasn't clear/apparent to me that you can create a non-rolling
file appender with the `rolling` module - this calls that out more
clearly.

## Solution

Updates to docs.
This commit is contained in:
C L Eckhardt 2023-09-05 12:20:06 -05:00 committed by Eliza Weisman
parent 70107bfad7
commit a814b87d10
2 changed files with 25 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
tracing-appender/src/lib.rs
View File

@ -26,20 +26,34 @@
//! - Using a combination of [`NonBlocking`][non_blocking] and [`RollingFileAppender`][rolling_struct] to allow writes to a log file
//! without blocking.
//!
//! ## Rolling File Appender
//! ## File Appender
//!
//! The [`rolling` module][rolling] provides functions to create rolling and non-rolling file
//! appenders.
//!
//! Rolling file appender rotation options are [`Rotation::MINUTELY`](rolling::Rotation::MINUTELY),
//! [`Rotation::HOURLY`](rolling::Rotation::HOURLY), and
//! [`Rotation::DAILY`](rolling::Rotation::DAILY).
//!
//! To create a non-rolling file appender, use
//! [`tracing_appender::rolling::never(/*...*/)`](rolling::never) or
//! [`Rotation::NEVER`](rolling::Rotation::NEVER).
//!
//! The following example creates an hourly rotating file appender that writes to
//! `/some/directory/prefix.log.YYYY-MM-DD-HH`:
//!
//! ```rust
//! # fn docs() {
//! let file_appender = tracing_appender::rolling::hourly("/some/directory", "prefix.log");
//! # }
//! ```
//! This creates an hourly rotating file appender that writes to `/some/directory/prefix.log.YYYY-MM-DD-HH`.
//! [`Rotation::DAILY`](rolling::Rotation::DAILY) and [`Rotation::NEVER`](rolling::Rotation::NEVER) are the other available options.
//!
//! The file appender implements [`std::io::Write`][write]. To be used with [`tracing_subscriber::FmtSubscriber`][fmt_subscriber],
//! it must be combined with a [`MakeWriter`][make_writer] implementation to be able to record tracing spans/event.
//! The file appender implements [`std::io::Write`][write]. To be used with
//! [`tracing_subscriber::FmtSubscriber`][fmt_subscriber], it must be combined with a
//! [`MakeWriter`][make_writer] implementation to be able to record tracing spans/event.
//!
//! The [`rolling` module][rolling]'s documentation provides more detail on how to use this file appender.
//! See the [`rolling` module][rolling]'s documentation for more detail on how to use this file
//! appender.
//!
//! ## Non-Blocking Writer
//!

10
tracing-appender/src/rolling.rs
View File

@ -264,7 +264,7 @@ impl fmt::Debug for RollingFileAppender {
}
}
/// Creates a minutely, rolling file appender. This will rotate the log file once per minute.
/// Creates a minutely-rotating file appender. This will rotate the log file once per minute.
///
/// The appender returned by `rolling::minutely` can be used with `non_blocking` to create
/// a non-blocking, minutely file appender.
@ -299,7 +299,7 @@ pub fn minutely(
RollingFileAppender::new(Rotation::MINUTELY, directory, file_name_prefix)
}
/// Creates an hourly, rolling file appender.
/// Creates an hourly-rotating file appender.
///
/// The appender returned by `rolling::hourly` can be used with `non_blocking` to create
/// a non-blocking, hourly file appender.
@ -334,7 +334,7 @@ pub fn hourly(
RollingFileAppender::new(Rotation::HOURLY, directory, file_name_prefix)
}
/// Creates a file appender that rotates daily.
/// Creates a daily-rotating file appender.
///
/// The appender returned by `rolling::daily` can be used with `non_blocking` to create
/// a non-blocking, daily file appender.
@ -370,13 +370,13 @@ pub fn daily(
RollingFileAppender::new(Rotation::DAILY, directory, file_name_prefix)
}
/// Creates a non-rolling, file appender
/// Creates a non-rolling file appender.
///
/// The appender returned by `rolling::never` can be used with `non_blocking` to create
/// a non-blocking, non-rotating appender.
///
/// The location of the log file will be specified the `directory` passed in.
/// `file_name` specifies the prefix of the log file. No date or time is appended.
/// `file_name` specifies the complete name of the log file (no date or time is appended).
///
/// # Examples
///