Skip to content

Commit

Permalink
appender: clarify file appender docs (#2689)
Browse files Browse the repository at this point in the history
## 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.
  • Loading branch information
CLEckhardt authored and davidbarsky committed Sep 27, 2023
1 parent facea54 commit e0a8f32
Show file tree
Hide file tree
Showing 2 changed files with 25 additions and 11 deletions.
26 changes: 20 additions & 6 deletions tracing-appender/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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
//!
Expand Down
10 changes: 5 additions & 5 deletions tracing-appender/src/rolling.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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
///
Expand Down

0 comments on commit e0a8f32

Please sign in to comment.