Crate tracing_appender

Writers for logging events and spans

Overview

tracing is a framework for structured, event-based diagnostic information. tracing-appender allows events and spans to be recorded in a non-blocking manner through a dedicated logging thread. It also provides a RollingFileAppender that can be used with or without the non-blocking writer.

Usage

Add the following to your Cargo.toml:

tracing-appender = "0.1"

This crate can be used in a few ways to record spans/events:

• Using a RollingFileAppender to perform writes to a log file. This will block on writes.
• Using any type implementing std::io::Write in a non-blocking fashion.
• Using a combination of NonBlocking and RollingFileAppender to allow writes to a log file without blocking.

Rolling File Appender

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] and [Rotation::NEVER] are the other available options.

The file appender implements std::io::Write. To be used with [tracing_subscriber::FmtSubscriber][fmt_subscrier], it must be combined with a MakeWriter implementation to be able to record tracing spans/event.

The rolling module's documentation provides more detail on how to use this file appender.

Non-Blocking Writer

The example below demonstrates the construction of a non_blocking writer with std::io::stdout(), which implements MakeWriter.

let (non_blocking, _guard) = tracing_appender::non_blocking(std::io::stdout());
tracing_subscriber::fmt()
    .with_writer(non_blocking)
    .init();

Note: _guard is a WorkerGuard which is returned by tracing_appender::non_blocking to ensure buffered logs are flushed to their output in the case of abrupt terminations of a process. See WorkerGuard module for more details.

The example below demonstrates the construction of a tracing_appender::non_blocking writer constructed with a std::io::Write:

use std::io::Error;

struct TestWriter;

impl std::io::Write for TestWriter {
    fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
        let buf_len = buf.len();
        println!("{:?}", buf);
        Ok(buf_len)
    }

    fn flush(&mut self) -> std::io::Result<()> {
        Ok(())
    }
}

let (non_blocking, _guard) = tracing_appender::non_blocking(TestWriter);
tracing_subscriber::fmt()
    .with_writer(non_blocking)
    .init();

The non_blocking module's documentation provides more detail on how to use non_blocking.

Non-Blocking Rolling File Appender

let file_appender = tracing_appender::rolling::hourly("/some/directory", "prefix.log");
let (non_blocking, _guard) = tracing_appender::non_blocking(file_appender);
tracing_subscriber::fmt()
    .with_writer(non_blocking)
    .init();

Modules

non_blocking	A non-blocking, off-thread writer.
rolling	A rolling file appender.

Functions

non_blocking

Convenience function for creating a non-blocking, off-thread writer.