Struct RollingFileAppender

pub struct RollingFileAppender { /* private fields */ }

A file appender with the ability to rotate log files at a fixed schedule.

RollingFileAppender implements the std:io::Write trait and will block on write operations. It may be used with NonBlocking to perform writes without blocking the current thread.

Additionally, RollingFileAppender also implements the MakeWriter trait from tracing-subscriber, so it may also be used directly, without NonBlocking.

Examples

Rolling a log file once every hour:

let file_appender = tracing_appender::rolling::hourly("/some/directory", "prefix");

Combining a RollingFileAppender with another MakeWriter implementation:

use tracing_subscriber::fmt::writer::MakeWriterExt;

// Log all events to a rolling log file.
let logfile = tracing_appender::rolling::hourly("/logs", "myapp-logs");

// Log `INFO` and above to stdout.
let stdout = std::io::stdout.with_max_level(tracing::Level::INFO);

tracing_subscriber::fmt()
    // Combine the stdout and log file `MakeWriter`s into one
    // `MakeWriter` that writes to both
    .with_writer(stdout.and(logfile))
    .init();

Implementations

impl RollingFileAppender

pub fn new( rotation: Rotation, directory: impl AsRef<Path>, filename_prefix: impl AsRef<Path>, ) -> RollingFileAppender

Creates a new RollingFileAppender.

A RollingFileAppender will have a fixed rotation whose frequency is defined by Rotation. The directory and file_name_prefix arguments determine the location and file name’s prefix of the log file. RollingFileAppender will automatically append the current date and hour (UTC format) to the file name.

Alternatively, a RollingFileAppender can be constructed using one of the following helpers:

• Rotation::minutely(),
• Rotation::hourly(),
• Rotation::daily(),
• Rotation::never()

Additional parameters can be configured using RollingFileAppender::builder.

Examples

use tracing_appender::rolling::{RollingFileAppender, Rotation};
let file_appender = RollingFileAppender::new(Rotation::HOURLY, "/some/directory", "prefix.log");

pub fn builder() -> Builder

Returns a new Builder for configuring a RollingFileAppender.

The builder interface can be used to set additional configuration parameters when constructing a new appender.

Unlike RollingFileAppender::new, the Builder::build method returns a Result rather than panicking when the appender cannot be initialized. Therefore, the builder interface can also be used when appender initialization errors should be handled gracefully.

Examples

use tracing_appender::rolling::{RollingFileAppender, Rotation};

let file_appender = RollingFileAppender::builder()
    .rotation(Rotation::HOURLY) // rotate log files once every hour
    .filename_prefix("myapp") // log file names will be prefixed with `myapp.`
    .filename_suffix("log") // log file names will be suffixed with `.log`
    .build("/var/log") // try to build an appender that stores log files in `/var/log`
    .expect("initializing rolling file appender failed");

Trait Implementations

impl Debug for RollingFileAppender

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a> MakeWriter<'a> for RollingFileAppender

type Writer = RollingWriter<'a>

The concrete io::Write implementation returned by make_writer.

fn make_writer(&'a self) -> Self::Writer

Returns an instance of Writer.

fn make_writer_for(&'a self, meta: &Metadata<'_>) -> Self::Writer

Returns a Writer for writing data from the span or event described by the provided Metadata.

impl Write for RollingFileAppender

fn write(&mut self, buf: &[u8]) -> Result<usize>

Writes a buffer into this writer, returning how many bytes were written.

fn flush(&mut self) -> Result<()>

Flushes this output stream, ensuring that all intermediately buffered contents reach their destination.

fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize, Error>

Like write, except that it writes from a slice of buffers.

fn is_write_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector #69941)

Determines if this Writer has an efficient write_vectored implementation.

fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>

Attempts to write an entire buffer into this writer.

fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>

🔬This is a nightly-only experimental API. (write_all_vectored #70436)

Attempts to write multiple buffers into this writer.

fn write_fmt(&mut self, fmt: Arguments<'_>) -> Result<(), Error>

Writes a formatted string into this writer, returning any error encountered.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adapter for this instance of Write.