Writers for logging events and spans
tracing is a framework for instrumenting Rust programs to
collect 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.
Add the following to your Cargo.toml:
toml
tracing-appender = "0.1"
This crate can be used in a few ways to record spans/events:
- Using a RollingFileAppender to write to a log file.
This is a blocking operation.
- Using any type implementing std::io::Write in a
non-blocking fashion.
- Using NonBlocking and RollingFileAppender
together to write to write to log files in a non-blocking fashion.
rust
fn main(){
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.
The example below demonstrates the construction of a non_blocking writer
with an implementation of std::io::Writer.
```rust use std::io::Error;
struct TestWriter;
impl std::io::Write for TestWriter {
fn write(&mut self, buf: &[u8]) -> std::io::Result
println!("{:?}", buf);
Ok(buf_len)
}
fn flush(&mut self) -> std::io::Result<()> {
Ok(())
}
}
fn main() {
let (nonblocking, _guard) = tracingappender::nonblocking(TestWriter);
tracingsubscriber::fmt().withwriter(nonblocking).init();
}
``
**Note:**guardis a [WorkerGuard][guard] which is returned by
tracingappender::non_blockingto ensure buffered logs are flushed to
their output in the case of abrupt terminations of a process. See
[WorkerGuard`][guard] module for more details.
The example below demonstrates the construction of a
tracing_appender::non_blocking writer constructed with
a std::io::Write:
rust
fn main() {
let (non_blocking, _guard) = tracing_appender::non_blocking(std::io::Stdout);
tracing_subscriber::fmt()
.with_writer(non_blocking)
.init();
}
The [non_blocking] module's documentation provides more detail on how to
use non_blocking.
rust
fn main() {
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();
}
This project is licensed under the MIT license.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in Tokio by you, shall be licensed as MIT, without any additional terms or conditions.