• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1![Tracing — Structured, application-level diagnostics][splash]
2
3[splash]: https://raw.githubusercontent.com/tokio-rs/tracing/master/assets/splash.svg
4
5# tracing-appender
6
7Writers for logging events and spans
8
9[![Crates.io][crates-badge]][crates-url]
10[![Documentation][docs-badge]][docs-url]
11[![Documentation (master)][docs-master-badge]][docs-master-url]
12[![MIT licensed][mit-badge]][mit-url]
13[![Build Status][actions-badge]][actions-url]
14[![Discord chat][discord-badge]][discord-url]
15
16[Documentation][docs-url] | [Chat][discord-url]
17
18[crates-badge]: https://img.shields.io/crates/v/tracing-appender.svg
19[crates-url]: https://crates.io/crates/tracing-appender/0.2.2
20[docs-badge]: https://docs.rs/tracing-appender/badge.svg
21[docs-url]: https://docs.rs/tracing-appender/0.2.2
22[docs-master-badge]: https://img.shields.io/badge/docs-master-blue
23[docs-master-url]: https://tracing.rs/tracing-appender
24[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg
25[mit-url]: ../LICENSE
26[actions-badge]: https://github.com/tokio-rs/tracing/workflows/CI/badge.svg
27[actions-url]:https://github.com/tokio-rs/tracing/actions?query=workflow%3ACI
28[discord-badge]: https://img.shields.io/discord/500028886025895936?logo=discord&label=discord&logoColor=white
29[discord-url]: https://discord.gg/EeF3cQw
30
31## Overview
32
33[`tracing`][tracing] is a framework for instrumenting Rust programs to
34collect structured, event-based diagnostic information. `tracing-appender`
35allows events and spans to be recorded in a non-blocking manner through a
36dedicated logging thread. It also provides a [`RollingFileAppender`][file_appender]
37that can be used with _or_ without the non-blocking writer.
38
39*Compiler support: [requires `rustc` 1.53+][msrv]*
40
41[msrv]: #supported-rust-versions
42
43## Usage
44
45Add the following to your `Cargo.toml`:
46```toml
47tracing-appender = "0.2"
48```
49
50This crate can be used in a few ways to record spans/events:
51 - Using a [`RollingFileAppender`][file_appender] to write to a log file.
52 This is a blocking operation.
53 - Using *any* type implementing [`std::io::Write`][write] in a
54 non-blocking fashion.
55 - Using [`NonBlocking`][non_blocking] and [`RollingFileAppender`][file_appender]
56 together to write to log files in a non-blocking fashion.
57
58## Rolling File Appender
59
60```rust
61fn main(){
62    let file_appender = tracing_appender::rolling::hourly("/some/directory", "prefix.log");
63}
64```
65This creates an hourly rotating file appender that writes to
66`/some/directory/prefix.log.YYYY-MM-DD-HH`. [`Rotation::DAILY`] and
67[`Rotation::NEVER`] are the other available options.
68
69The file appender implements [`std::io::Write`][write]. To be used with
70[`tracing_subscriber::FmtSubscriber`][fmt_subscriber], it must be combined
71with a [`MakeWriter`][make_writer] implementation to be able to record
72tracing spans/event.
73
74The [rolling] module's documentation provides more detail on how to use
75this file appender.
76
77## Non-Blocking Writer
78The example below demonstrates the construction of a `non_blocking` writer
79with an implementation of [`std::io::Writer`][write].
80
81```rust
82use std::io::Error;
83
84struct TestWriter;
85
86impl std::io::Write for TestWriter {
87    fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
88        let buf_len = buf.len();
89
90        println!("{:?}", buf);
91        Ok(buf_len)
92    }
93
94    fn flush(&mut self) -> std::io::Result<()> {
95        Ok(())
96    }
97}
98
99fn main() {
100    let (non_blocking, _guard) = tracing_appender::non_blocking(TestWriter);
101    tracing_subscriber::fmt().with_writer(non_blocking).init();
102}
103```
104**Note:** `_guard` is a [`WorkerGuard`][guard] which is returned by
105`tracing_appender::non_blocking` to ensure buffered logs are flushed to
106their output in the case of abrupt terminations of a process. See
107[`WorkerGuard`][guard] module for more details.
108
109The example below demonstrates the construction of a
110[`tracing_appender::non_blocking`][non_blocking] writer constructed with
111a [`std::io::Write`][write]:
112
113```rust
114fn main() {
115    let (non_blocking, _guard) = tracing_appender::non_blocking(std::io::stdout());
116    tracing_subscriber::fmt()
117        .with_writer(non_blocking)
118        .init();
119}
120```
121
122The [non_blocking] module's documentation provides more detail on how to
123use `non_blocking`.
124
125## Non-Blocking Rolling File Appender
126
127```rust
128fn main() {
129    let file_appender = tracing_appender::rolling::hourly("/some/directory", "prefix.log");
130    let (non_blocking, _guard) = tracing_appender::non_blocking(file_appender);
131   tracing_subscriber::fmt()
132       .with_writer(non_blocking)
133       .init();
134}
135```
136
137[tracing]: https://docs.rs/tracing/latest/tracing/
138[make_writer]: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/fmt/trait.MakeWriter.html
139[write]: https://doc.rust-lang.org/std/io/trait.Write.html
140[non_blocking]: https://docs.rs/tracing-appender/latest/tracing_appender/non_blocking/index.html
141[rolling]: https://docs.rs/tracing-appender/latest/tracing_appender/rolling/index.html
142[guard]: https://docs.rs/tracing-appender/latest/tracing_appender/non_blocking/struct.WorkerGuard.html
143[file_appender]: https://docs.rs/tracing-appender/latest/tracing_appender/rolling/struct.RollingFileAppender.html
144[fmt_subscriber]: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/fmt/struct.Subscriber.html
145
146## Supported Rust Versions
147
148`tracing-appender` is built against the latest stable release. The minimum supported
149version is 1.53. The current `tracing-appender` version is not guaranteed to build on
150Rust versions earlier than the minimum supported version.
151
152Tracing follows the same compiler support policies as the rest of the Tokio
153project. The current stable Rust compiler and the three most recent minor
154versions before it will always be supported. For example, if the current
155stable compiler version is 1.45, the minimum supported version will not be
156increased past 1.42, three minor versions prior. Increasing the minimum
157supported compiler version is not considered a semver breaking change as
158long as doing so complies with this policy.
159
160## License
161
162This project is licensed under the [MIT license](../LICENSE).
163
164### Contribution
165
166Unless you explicitly state otherwise, any contribution intentionally submitted
167for inclusion in Tokio by you, shall be licensed as MIT, without any additional
168terms or conditions.
169