[−][src]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
andRollingFileAppender
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
,
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. |