1//! A scoped, structured logging and diagnostics system.
2//!
3//! # Overview
4//!
5//! `tracing` is a framework for instrumenting Rust programs to collect
6//! structured, event-based diagnostic information.
7//!
8//! In asynchronous systems like Tokio, interpreting traditional log messages can
9//! often be quite challenging. Since individual tasks are multiplexed on the same
10//! thread, associated events and log lines are intermixed making it difficult to
11//! trace the logic flow. `tracing` expands upon logging-style diagnostics by
12//! allowing libraries and applications to record structured events with additional
13//! information about *temporality* and *causality* — unlike a log message, a span
14//! in `tracing` has a beginning and end time, may be entered and exited by the
15//! flow of execution, and may exist within a nested tree of similar spans. In
16//! addition, `tracing` spans are *structured*, with the ability to record typed
17//! data as well as textual messages.
18//!
19//! The `tracing` crate provides the APIs necessary for instrumenting libraries
20//! and applications to emit trace data.
21//!
22//! *Compiler support: [requires `rustc` 1.56+][msrv]*
23//!
24//! [msrv]: #supported-rust-versions
25//! # Core Concepts
26//!
27//! The core of `tracing`'s API is composed of _spans_, _events_ and
28//! _subscribers_. We'll cover these in turn.
29//!
30//! ## Spans
31//!
32//! To record the flow of execution through a program, `tracing` introduces the
33//! concept of [spans]. Unlike a log line that represents a _moment in
34//! time_, a span represents a _period of time_ with a beginning and an end. When a
35//! program begins executing in a context or performing a unit of work, it
36//! _enters_ that context's span, and when it stops executing in that context,
37//! it _exits_ the span. The span in which a thread is currently executing is
38//! referred to as that thread's _current_ span.
39//!
40//! For example:
41//! ```
42//! use tracing::{span, Level};
43//! # fn main() {
44//! let span = span!(Level::TRACE, "my_span");
45//! // `enter` returns a RAII guard which, when dropped, exits the span. this
46//! // indicates that we are in the span for the current lexical scope.
47//! let _enter = span.enter();
48//! // perform some work in the context of `my_span`...
49//! # }
50//!```
51//!
52//! The [`span` module][span]'s documentation provides further details on how to
53//! use spans.
54//!
55//! <div class="example-wrap" style="display:inline-block"><pre class="compile_fail" style="white-space:normal;font:inherit;">
56//!
57//! **Warning**: In asynchronous code that uses async/await syntax,
58//! `Span::enter` may produce incorrect traces if the returned drop
59//! guard is held across an await point. See
60//! [the method documentation][Span#in-asynchronous-code] for details.
61//!
62//! </pre></div>
63//!
64//! ## Events
65//!
66//! An [`Event`] represents a _moment_ in time. It signifies something that
67//! happened while a trace was being recorded. `Event`s are comparable to the log
68//! records emitted by unstructured logging code, but unlike a typical log line,
69//! an `Event` may occur within the context of a span.
70//!
71//! For example:
72//! ```
73//! use tracing::{event, span, Level};
74//!
75//! # fn main() {
76//! // records an event outside of any span context:
77//! event!(Level::INFO, "something happened");
78//!
79//! let span = span!(Level::INFO, "my_span");
80//! let _guard = span.enter();
81//!
82//! // records an event within "my_span".
83//! event!(Level::DEBUG, "something happened inside my_span");
84//! # }
85//!```
86//!
87//! In general, events should be used to represent points in time _within_ a
88//! span — a request returned with a given status code, _n_ new items were
89//! taken from a queue, and so on.
90//!
91//! The [`Event` struct][`Event`] documentation provides further details on using
92//! events.
93//!
94//! ## Subscribers
95//!
96//! As `Span`s and `Event`s occur, they are recorded or aggregated by
97//! implementations of the [`Subscriber`] trait. `Subscriber`s are notified
98//! when an `Event` takes place and when a `Span` is entered or exited. These
99//! notifications are represented by the following `Subscriber` trait methods:
100//!
101//! + [`event`][Subscriber::event], called when an `Event` takes place,
102//! + [`enter`], called when execution enters a `Span`,
103//! + [`exit`], called when execution exits a `Span`
104//!
105//! In addition, subscribers may implement the [`enabled`] function to _filter_
106//! the notifications they receive based on [metadata] describing each `Span`
107//! or `Event`. If a call to `Subscriber::enabled` returns `false` for a given
108//! set of metadata, that `Subscriber` will *not* be notified about the
109//! corresponding `Span` or `Event`. For performance reasons, if no currently
110//! active subscribers express interest in a given set of metadata by returning
111//! `true`, then the corresponding `Span` or `Event` will never be constructed.
112//!
113//! # Usage
114//!
115//! First, add this to your `Cargo.toml`:
116//!
117//! ```toml
118//! [dependencies]
119//! tracing = "0.1"
120//! ```
121//!
122//! ## Recording Spans and Events
123//!
124//! Spans and events are recorded using macros.
125//!
126//! ### Spans
127//!
128//! The [`span!`] macro expands to a [`Span` struct][`Span`] which is used to
129//! record a span. The [`Span::enter`] method on that struct records that the
130//! span has been entered, and returns a [RAII] guard object, which will exit
131//! the span when dropped.
132//!
133//! For example:
134//!
135//! ```rust
136//! use tracing::{span, Level};
137//! # fn main() {
138//! // Construct a new span named "my span" with trace log level.
139//! let span = span!(Level::TRACE, "my span");
140//!
141//! // Enter the span, returning a guard object.
142//! let _enter = span.enter();
143//!
144//! // Any trace events that occur before the guard is dropped will occur
145//! // within the span.
146//!
147//! // Dropping the guard will exit the span.
148//! # }
149//! ```
150//!
151//! The [`#[instrument]`][instrument] attribute provides an easy way to
152//! add `tracing` spans to functions. A function annotated with `#[instrument]`
153//! will create and enter a span with that function's name every time the
154//! function is called, with arguments to that function will be recorded as
155//! fields using `fmt::Debug`.
156//!
157//! For example:
158//! ```ignore
159//! # // this doctest is ignored because we don't have a way to say
160//! # // that it should only be run with cfg(feature = "attributes")
161//! use tracing::{Level, event, instrument};
162//!
163//! #[instrument]
164//! pub fn my_function(my_arg: usize) {
165//! // This event will be recorded inside a span named `my_function` with the
166//! // field `my_arg`.
167//! event!(Level::INFO, "inside my_function!");
168//! // ...
169//! }
170//! # fn main() {}
171//! ```
172//!
173//! For functions which don't have built-in tracing support and can't have
174//! the `#[instrument]` attribute applied (such as from an external crate),
175//! the [`Span` struct][`Span`] has a [`in_scope()` method][`in_scope`]
176//! which can be used to easily wrap synchonous code in a span.
177//!
178//! For example:
179//! ```rust
180//! use tracing::info_span;
181//!
182//! # fn doc() -> Result<(), ()> {
183//! # mod serde_json {
184//! # pub(crate) fn from_slice(buf: &[u8]) -> Result<(), ()> { Ok(()) }
185//! # }
186//! # let buf: [u8; 0] = [];
187//! let json = info_span!("json.parse").in_scope(|| serde_json::from_slice(&buf))?;
188//! # let _ = json; // suppress unused variable warning
189//! # Ok(())
190//! # }
191//! ```
192//!
193//! You can find more examples showing how to use this crate [here][examples].
194//!
195//! [RAII]: https://github.com/rust-unofficial/patterns/blob/main/src/patterns/behavioural/RAII.md
196//! [examples]: https://github.com/tokio-rs/tracing/tree/master/examples
197//!
198//! ### Events
199//!
200//! [`Event`]s are recorded using the [`event!`] macro:
201//!
202//! ```rust
203//! # fn main() {
204//! use tracing::{event, Level};
205//! event!(Level::INFO, "something has happened!");
206//! # }
207//! ```
208//!
209//! ## Using the Macros
210//!
211//! The [`span!`] and [`event!`] macros as well as the `#[instrument]` attribute
212//! use fairly similar syntax, with some exceptions.
213//!
214//! ### Configuring Attributes
215//!
216//! Both macros require a [`Level`] specifying the verbosity of the span or
217//! event. Optionally, the, [target] and [parent span] may be overridden. If the
218//! target and parent span are not overridden, they will default to the
219//! module path where the macro was invoked and the current span (as determined
220//! by the subscriber), respectively.
221//!
222//! For example:
223//!
224//! ```
225//! # use tracing::{span, event, Level};
226//! # fn main() {
227//! span!(target: "app_spans", Level::TRACE, "my span");
228//! event!(target: "app_events", Level::INFO, "something has happened!");
229//! # }
230//! ```
231//! ```
232//! # use tracing::{span, event, Level};
233//! # fn main() {
234//! let span = span!(Level::TRACE, "my span");
235//! event!(parent: &span, Level::INFO, "something has happened!");
236//! # }
237//! ```
238//!
239//! The span macros also take a string literal after the level, to set the name
240//! of the span (as above). In the case of the event macros, the name of the event can
241//! be overridden (the default is `event file:line`) using the `name:` specifier.
242//!
243//! ```
244//! # use tracing::{span, event, Level};
245//! # fn main() {
246//! span!(Level::TRACE, "my span");
247//! event!(name: "some_info", Level::INFO, "something has happened!");
248//! # }
249//! ```
250//!
251//! ### Recording Fields
252//!
253//! Structured fields on spans and events are specified using the syntax
254//! `field_name = field_value`. Fields are separated by commas.
255//!
256//! ```
257//! # use tracing::{event, Level};
258//! # fn main() {
259//! // records an event with two fields:
260//! // - "answer", with the value 42
261//! // - "question", with the value "life, the universe and everything"
262//! event!(Level::INFO, answer = 42, question = "life, the universe, and everything");
263//! # }
264//! ```
265//!
266//! As shorthand, local variables may be used as field values without an
267//! assignment, similar to [struct initializers]. For example:
268//!
269//! ```
270//! # use tracing::{span, Level};
271//! # fn main() {
272//! let user = "ferris";
273//!
274//! span!(Level::TRACE, "login", user);
275//! // is equivalent to:
276//! span!(Level::TRACE, "login", user = user);
277//! # }
278//!```
279//!
280//! Field names can include dots, but should not be terminated by them:
281//! ```
282//! # use tracing::{span, Level};
283//! # fn main() {
284//! let user = "ferris";
285//! let email = "ferris@rust-lang.org";
286//! span!(Level::TRACE, "login", user, user.email = email);
287//! # }
288//!```
289//!
290//! Since field names can include dots, fields on local structs can be used
291//! using the local variable shorthand:
292//! ```
293//! # use tracing::{span, Level};
294//! # fn main() {
295//! # struct User {
296//! # name: &'static str,
297//! # email: &'static str,
298//! # }
299//! let user = User {
300//! name: "ferris",
301//! email: "ferris@rust-lang.org",
302//! };
303//! // the span will have the fields `user.name = "ferris"` and
304//! // `user.email = "ferris@rust-lang.org"`.
305//! span!(Level::TRACE, "login", user.name, user.email);
306//! # }
307//!```
308//!
309//! Fields with names that are not Rust identifiers, or with names that are Rust reserved words,
310//! may be created using quoted string literals. However, this may not be used with the local
311//! variable shorthand.
312//! ```
313//! # use tracing::{span, Level};
314//! # fn main() {
315//! // records an event with fields whose names are not Rust identifiers
316//! // - "guid:x-request-id", containing a `:`, with the value "abcdef"
317//! // - "type", which is a reserved word, with the value "request"
318//! span!(Level::TRACE, "api", "guid:x-request-id" = "abcdef", "type" = "request");
319//! # }
320//!```
321//!
322//! Constant expressions can also be used as field names. Constants
323//! must be enclosed in curly braces (`{}`) to indicate that the *value*
324//! of the constant is to be used as the field name, rather than the
325//! constant's name. For example:
326//! ```
327//! # use tracing::{span, Level};
328//! # fn main() {
329//! const RESOURCE_NAME: &str = "foo";
330//! // this span will have the field `foo = "some_id"`
331//! span!(Level::TRACE, "get", { RESOURCE_NAME } = "some_id");
332//! # }
333//!```
334//!
335//! The `?` sigil is shorthand that specifies a field should be recorded using
336//! its [`fmt::Debug`] implementation:
337//! ```
338//! # use tracing::{event, Level};
339//! # fn main() {
340//! #[derive(Debug)]
341//! struct MyStruct {
342//! field: &'static str,
343//! }
344//!
345//! let my_struct = MyStruct {
346//! field: "Hello world!"
347//! };
348//!
349//! // `my_struct` will be recorded using its `fmt::Debug` implementation.
350//! event!(Level::TRACE, greeting = ?my_struct);
351//! // is equivalent to:
352//! event!(Level::TRACE, greeting = tracing::field::debug(&my_struct));
353//! # }
354//! ```
355//!
356//! The `%` sigil operates similarly, but indicates that the value should be
357//! recorded using its [`fmt::Display`] implementation:
358//! ```
359//! # use tracing::{event, Level};
360//! # fn main() {
361//! # #[derive(Debug)]
362//! # struct MyStruct {
363//! # field: &'static str,
364//! # }
365//! #
366//! # let my_struct = MyStruct {
367//! # field: "Hello world!"
368//! # };
369//! // `my_struct.field` will be recorded using its `fmt::Display` implementation.
370//! event!(Level::TRACE, greeting = %my_struct.field);
371//! // is equivalent to:
372//! event!(Level::TRACE, greeting = tracing::field::display(&my_struct.field));
373//! # }
374//! ```
375//!
376//! The `%` and `?` sigils may also be used with local variable shorthand:
377//!
378//! ```
379//! # use tracing::{event, Level};
380//! # fn main() {
381//! # #[derive(Debug)]
382//! # struct MyStruct {
383//! # field: &'static str,
384//! # }
385//! #
386//! # let my_struct = MyStruct {
387//! # field: "Hello world!"
388//! # };
389//! // `my_struct.field` will be recorded using its `fmt::Display` implementation.
390//! event!(Level::TRACE, %my_struct.field);
391//! # }
392//! ```
393//!
394//! Additionally, a span may declare fields with the special value [`Empty`],
395//! which indicates that that the value for that field does not currently exist
396//! but may be recorded later. For example:
397//!
398//! ```
399//! use tracing::{trace_span, field};
400//!
401//! // Create a span with two fields: `greeting`, with the value "hello world", and
402//! // `parting`, without a value.
403//! let span = trace_span!("my_span", greeting = "hello world", parting = field::Empty);
404//!
405//! // ...
406//!
407//! // Now, record a value for parting as well.
408//! span.record("parting", &"goodbye world!");
409//! ```
410//!
411//! Finally, events may also include human-readable messages, in the form of a
412//! [format string][fmt] and (optional) arguments, **after** the event's
413//! key-value fields. If a format string and arguments are provided,
414//! they will implicitly create a new field named `message` whose value is the
415//! provided set of format arguments.
416//!
417//! For example:
418//!
419//! ```
420//! # use tracing::{event, Level};
421//! # fn main() {
422//! let question = "the ultimate question of life, the universe, and everything";
423//! let answer = 42;
424//! // records an event with the following fields:
425//! // - `question.answer` with the value 42,
426//! // - `question.tricky` with the value `true`,
427//! // - "message", with the value "the answer to the ultimate question of life, the
428//! // universe, and everything is 42."
429//! event!(
430//! Level::DEBUG,
431//! question.answer = answer,
432//! question.tricky = true,
433//! "the answer to {} is {}.", question, answer
434//! );
435//! # }
436//! ```
437//!
438//! Specifying a formatted message in this manner does not allocate by default.
439//!
440//! [struct initializers]: https://doc.rust-lang.org/book/ch05-01-defining-structs.html#using-the-field-init-shorthand-when-variables-and-fields-have-the-same-name
441//! [target]: Metadata::target
442//! [parent span]: span::Attributes::parent
443//! [determined contextually]: span::Attributes::is_contextual
444//! [`fmt::Debug`]: std::fmt::Debug
445//! [`fmt::Display`]: std::fmt::Display
446//! [fmt]: std::fmt#usage
447//! [`Empty`]: field::Empty
448//!
449//! ### Shorthand Macros
450//!
451//! `tracing` also offers a number of macros with preset verbosity levels.
452//! The [`trace!`], [`debug!`], [`info!`], [`warn!`], and [`error!`] behave
453//! similarly to the [`event!`] macro, but with the [`Level`] argument already
454//! specified, while the corresponding [`trace_span!`], [`debug_span!`],
455//! [`info_span!`], [`warn_span!`], and [`error_span!`] macros are the same,
456//! but for the [`span!`] macro.
457//!
458//! These are intended both as a shorthand, and for compatibility with the [`log`]
459//! crate (see the next section).
460//!
461//! [`span!`]: span!
462//! [`event!`]: event!
463//! [`trace!`]: trace!
464//! [`debug!`]: debug!
465//! [`info!`]: info!
466//! [`warn!`]: warn!
467//! [`error!`]: error!
468//! [`trace_span!`]: trace_span!
469//! [`debug_span!`]: debug_span!
470//! [`info_span!`]: info_span!
471//! [`warn_span!`]: warn_span!
472//! [`error_span!`]: error_span!
473//!
474//! ### For `log` Users
475//!
476//! Users of the [`log`] crate should note that `tracing` exposes a set of
477//! macros for creating `Event`s (`trace!`, `debug!`, `info!`, `warn!`, and
478//! `error!`) which may be invoked with the same syntax as the similarly-named
479//! macros from the `log` crate. Often, the process of converting a project to
480//! use `tracing` can begin with a simple drop-in replacement.
481//!
482//! Let's consider the `log` crate's yak-shaving example:
483//!
484//! ```rust,ignore
485//! use std::{error::Error, io};
486//! use tracing::{debug, error, info, span, warn, Level};
487//!
488//! // the `#[tracing::instrument]` attribute creates and enters a span
489//! // every time the instrumented function is called. The span is named after the
490//! // the function or method. Parameters passed to the function are recorded as fields.
491//! #[tracing::instrument]
492//! pub fn shave(yak: usize) -> Result<(), Box<dyn Error + 'static>> {
493//! // this creates an event at the DEBUG level with two fields:
494//! // - `excitement`, with the key "excitement" and the value "yay!"
495//! // - `message`, with the key "message" and the value "hello! I'm gonna shave a yak."
496//! //
497//! // unlike other fields, `message`'s shorthand initialization is just the string itself.
498//! debug!(excitement = "yay!", "hello! I'm gonna shave a yak.");
499//! if yak == 3 {
500//! warn!("could not locate yak!");
501//! // note that this is intended to demonstrate `tracing`'s features, not idiomatic
502//! // error handling! in a library or application, you should consider returning
503//! // a dedicated `YakError`. libraries like snafu or thiserror make this easy.
504//! return Err(io::Error::new(io::ErrorKind::Other, "shaving yak failed!").into());
505//! } else {
506//! debug!("yak shaved successfully");
507//! }
508//! Ok(())
509//! }
510//!
511//! pub fn shave_all(yaks: usize) -> usize {
512//! // Constructs a new span named "shaving_yaks" at the TRACE level,
513//! // and a field whose key is "yaks". This is equivalent to writing:
514//! //
515//! // let span = span!(Level::TRACE, "shaving_yaks", yaks = yaks);
516//! //
517//! // local variables (`yaks`) can be used as field values
518//! // without an assignment, similar to struct initializers.
519//! let _span = span!(Level::TRACE, "shaving_yaks", yaks).entered();
520//!
521//! info!("shaving yaks");
522//!
523//! let mut yaks_shaved = 0;
524//! for yak in 1..=yaks {
525//! let res = shave(yak);
526//! debug!(yak, shaved = res.is_ok());
527//!
528//! if let Err(ref error) = res {
529//! // Like spans, events can also use the field initialization shorthand.
530//! // In this instance, `yak` is the field being initalized.
531//! error!(yak, error = error.as_ref(), "failed to shave yak!");
532//! } else {
533//! yaks_shaved += 1;
534//! }
535//! debug!(yaks_shaved);
536//! }
537//!
538//! yaks_shaved
539//! }
540//! ```
541//!
542//! ## In libraries
543//!
544//! Libraries should link only to the `tracing` crate, and use the provided
545//! macros to record whatever information will be useful to downstream
546//! consumers.
547//!
548//! ## In executables
549//!
550//! In order to record trace events, executables have to use a `Subscriber`
551//! implementation compatible with `tracing`. A `Subscriber` implements a
552//! way of collecting trace data, such as by logging it to standard output.
553//!
554//! This library does not contain any `Subscriber` implementations; these are
555//! provided by [other crates](#related-crates).
556//!
557//! The simplest way to use a subscriber is to call the [`set_global_default`]
558//! function:
559//!
560//! ```
561//! extern crate tracing;
562//! # pub struct FooSubscriber;
563//! # use tracing::{span::{Id, Attributes, Record}, Metadata};
564//! # impl tracing::Subscriber for FooSubscriber {
565//! # fn new_span(&self, _: &Attributes) -> Id { Id::from_u64(0) }
566//! # fn record(&self, _: &Id, _: &Record) {}
567//! # fn event(&self, _: &tracing::Event) {}
568//! # fn record_follows_from(&self, _: &Id, _: &Id) {}
569//! # fn enabled(&self, _: &Metadata) -> bool { false }
570//! # fn enter(&self, _: &Id) {}
571//! # fn exit(&self, _: &Id) {}
572//! # }
573//! # impl FooSubscriber {
574//! # fn new() -> Self { FooSubscriber }
575//! # }
576//! # fn main() {
577//!
578//! let my_subscriber = FooSubscriber::new();
579//! tracing::subscriber::set_global_default(my_subscriber)
580//! .expect("setting tracing default failed");
581//! # }
582//! ```
583//!
584//! <pre class="compile_fail" style="white-space:normal;font:inherit;">
585//! <strong>Warning</strong>: In general, libraries should <em>not</em> call
586//! <code>set_global_default()</code>! Doing so will cause conflicts when
587//! executables that depend on the library try to set the default later.
588//! </pre>
589//!
590//! This subscriber will be used as the default in all threads for the
591//! remainder of the duration of the program, similar to setting the logger
592//! in the `log` crate.
593//!
594//! In addition, the default subscriber can be set through using the
595//! [`with_default`] function. This follows the `tokio` pattern of using
596//! closures to represent executing code in a context that is exited at the end
597//! of the closure. For example:
598//!
599//! ```rust
600//! # pub struct FooSubscriber;
601//! # use tracing::{span::{Id, Attributes, Record}, Metadata};
602//! # impl tracing::Subscriber for FooSubscriber {
603//! # fn new_span(&self, _: &Attributes) -> Id { Id::from_u64(0) }
604//! # fn record(&self, _: &Id, _: &Record) {}
605//! # fn event(&self, _: &tracing::Event) {}
606//! # fn record_follows_from(&self, _: &Id, _: &Id) {}
607//! # fn enabled(&self, _: &Metadata) -> bool { false }
608//! # fn enter(&self, _: &Id) {}
609//! # fn exit(&self, _: &Id) {}
610//! # }
611//! # impl FooSubscriber {
612//! # fn new() -> Self { FooSubscriber }
613//! # }
614//! # fn main() {
615//!
616//! let my_subscriber = FooSubscriber::new();
617//! # #[cfg(feature = "std")]
618//! tracing::subscriber::with_default(my_subscriber, || {
619//! // Any trace events generated in this closure or by functions it calls
620//! // will be collected by `my_subscriber`.
621//! })
622//! # }
623//! ```
624//!
625//! This approach allows trace data to be collected by multiple subscribers
626//! within different contexts in the program. Note that the override only applies to the
627//! currently executing thread; other threads will not see the change from with_default.
628//!
629//! Any trace events generated outside the context of a subscriber will not be collected.
630//!
631//! Once a subscriber has been set, instrumentation points may be added to the
632//! executable using the `tracing` crate's macros.
633//!
634//! ## `log` Compatibility
635//!
636//! The [`log`] crate provides a simple, lightweight logging facade for Rust.
637//! While `tracing` builds upon `log`'s foundation with richer structured
638//! diagnostic data, `log`'s simplicity and ubiquity make it the "lowest common
639//! denominator" for text-based logging in Rust — a vast majority of Rust
640//! libraries and applications either emit or consume `log` records. Therefore,
641//! `tracing` provides multiple forms of interoperability with `log`: `tracing`
642//! instrumentation can emit `log` records, and a compatibility layer enables
643//! `tracing` [`Subscriber`]s to consume `log` records as `tracing` [`Event`]s.
644//!
645//! ### Emitting `log` Records
646//!
647//! This crate provides two feature flags, "log" and "log-always", which will
648//! cause [spans] and [events] to emit `log` records. When the "log" feature is
649//! enabled, if no `tracing` `Subscriber` is active, invoking an event macro or
650//! creating a span with fields will emit a `log` record. This is intended
651//! primarily for use in libraries which wish to emit diagnostics that can be
652//! consumed by applications using `tracing` *or* `log`, without paying the
653//! additional overhead of emitting both forms of diagnostics when `tracing` is
654//! in use.
655//!
656//! Enabling the "log-always" feature will cause `log` records to be emitted
657//! even if a `tracing` `Subscriber` _is_ set. This is intended to be used in
658//! applications where a `log` `Logger` is being used to record a textual log,
659//! and `tracing` is used only to record other forms of diagnostics (such as
660//! metrics, profiling, or distributed tracing data). Unlike the "log" feature,
661//! libraries generally should **not** enable the "log-always" feature, as doing
662//! so will prevent applications from being able to opt out of the `log` records.
663//!
664//! See [here][flags] for more details on this crate's feature flags.
665//!
666//! The generated `log` records' messages will be a string representation of the
667//! span or event's fields, and all additional information recorded by `log`
668//! (target, verbosity level, module path, file, and line number) will also be
669//! populated. Additionally, `log` records are also generated when spans are
670//! entered, exited, and closed. Since these additional span lifecycle logs have
671//! the potential to be very verbose, and don't include additional fields, they
672//! will always be emitted at the `Trace` level, rather than inheriting the
673//! level of the span that generated them. Furthermore, they are are categorized
674//! under a separate `log` target, "tracing::span" (and its sub-target,
675//! "tracing::span::active", for the logs on entering and exiting a span), which
676//! may be enabled or disabled separately from other `log` records emitted by
677//! `tracing`.
678//!
679//! ### Consuming `log` Records
680//!
681//! The [`tracing-log`] crate provides a compatibility layer which
682//! allows a `tracing` [`Subscriber`] to consume `log` records as though they
683//! were `tracing` [events]. This allows applications using `tracing` to record
684//! the logs emitted by dependencies using `log` as events within the context of
685//! the application's trace tree. See [that crate's documentation][log-tracer]
686//! for details.
687//!
688//! [log-tracer]: https://docs.rs/tracing-log/latest/tracing_log/#convert-log-records-to-tracing-events
689//!
690//! ## Related Crates
691//!
692//! In addition to `tracing` and `tracing-core`, the [`tokio-rs/tracing`] repository
693//! contains several additional crates designed to be used with the `tracing` ecosystem.
694//! This includes a collection of `Subscriber` implementations, as well as utility
695//! and adapter crates to assist in writing `Subscriber`s and instrumenting
696//! applications.
697//!
698//! In particular, the following crates are likely to be of interest:
699//!
700//! - [`tracing-futures`] provides a compatibility layer with the `futures`
701//! crate, allowing spans to be attached to `Future`s, `Stream`s, and `Executor`s.
702//! - [`tracing-subscriber`] provides `Subscriber` implementations and
703//! utilities for working with `Subscriber`s. This includes a [`FmtSubscriber`]
704//! `FmtSubscriber` for logging formatted trace data to stdout, with similar
705//! filtering and formatting to the [`env_logger`] crate.
706//! - [`tracing-log`] provides a compatibility layer with the [`log`] crate,
707//! allowing log messages to be recorded as `tracing` `Event`s within the
708//! trace tree. This is useful when a project using `tracing` have
709//! dependencies which use `log`. Note that if you're using
710//! `tracing-subscriber`'s `FmtSubscriber`, you don't need to depend on
711//! `tracing-log` directly.
712//! - [`tracing-appender`] provides utilities for outputting tracing data,
713//! including a file appender and non blocking writer.
714//!
715//! Additionally, there are also several third-party crates which are not
716//! maintained by the `tokio` project. These include:
717//!
718//! - [`tracing-timing`] implements inter-event timing metrics on top of `tracing`.
719//! It provides a subscriber that records the time elapsed between pairs of
720//! `tracing` events and generates histograms.
721//! - [`tracing-opentelemetry`] provides a subscriber for emitting traces to
722//! [OpenTelemetry]-compatible distributed tracing systems.
723//! - [`tracing-honeycomb`] Provides a layer that reports traces spanning multiple machines to [honeycomb.io]. Backed by [`tracing-distributed`].
724//! - [`tracing-distributed`] Provides a generic implementation of a layer that reports traces spanning multiple machines to some backend.
725//! - [`tracing-actix-web`] provides `tracing` integration for the `actix-web` web framework.
726//! - [`tracing-actix`] provides `tracing` integration for the `actix` actor
727//! framework.
728//! - [`axum-insights`] provides `tracing` integration and Application insights export for the `axum` web framework.
729//! - [`tracing-gelf`] implements a subscriber for exporting traces in Greylog
730//! GELF format.
731//! - [`tracing-coz`] provides integration with the [coz] causal profiler
732//! (Linux-only).
733//! - [`tracing-bunyan-formatter`] provides a layer implementation that reports events and spans
734//! in [bunyan] format, enriched with timing information.
735//! - [`tracing-wasm`] provides a `Subscriber`/`Layer` implementation that reports
736//! events and spans via browser `console.log` and [User Timing API (`window.performance`)].
737//! - [`tracing-web`] provides a layer implementation of level-aware logging of events
738//! to web browsers' `console.*` and span events to the [User Timing API (`window.performance`)].
739//! - [`tide-tracing`] provides a [tide] middleware to trace all incoming requests and responses.
740//! - [`test-log`] takes care of initializing `tracing` for tests, based on
741//! environment variables with an `env_logger` compatible syntax.
742//! - [`tracing-unwrap`] provides convenience methods to report failed unwraps
743//! on `Result` or `Option` types to a `Subscriber`.
744//! - [`diesel-tracing`] provides integration with [`diesel`] database connections.
745//! - [`tracing-tracy`] provides a way to collect [Tracy] profiles in instrumented
746//! applications.
747//! - [`tracing-elastic-apm`] provides a layer for reporting traces to [Elastic APM].
748//! - [`tracing-etw`] provides a layer for emitting Windows [ETW] events.
749//! - [`tracing-fluent-assertions`] provides a fluent assertions-style testing
750//! framework for validating the behavior of `tracing` spans.
751//! - [`sentry-tracing`] provides a layer for reporting events and traces to [Sentry].
752//! - [`tracing-forest`] provides a subscriber that preserves contextual coherence by
753//! grouping together logs from the same spans during writing.
754//! - [`tracing-loki`] provides a layer for shipping logs to [Grafana Loki].
755//! - [`tracing-logfmt`] provides a layer that formats events and spans into the logfmt format.
756//! - [`reqwest-tracing`] provides a middleware to trace [`reqwest`] HTTP requests.
757//! - [`tracing-cloudwatch`] provides a layer that sends events to AWS CloudWatch Logs.
758//! - [`clippy-tracing`] provides a tool to add, remove and check for `tracing::instrument`.
759//!
760//! If you're the maintainer of a `tracing` ecosystem crate not listed above,
761//! please let us know! We'd love to add your project to the list!
762//!
763//! [`tracing-opentelemetry`]: https://crates.io/crates/tracing-opentelemetry
764//! [OpenTelemetry]: https://opentelemetry.io/
765//! [`tracing-honeycomb`]: https://crates.io/crates/tracing-honeycomb
766//! [`tracing-distributed`]: https://crates.io/crates/tracing-distributed
767//! [honeycomb.io]: https://www.honeycomb.io/
768//! [`tracing-actix-web`]: https://crates.io/crates/tracing-actix-web
769//! [`tracing-actix`]: https://crates.io/crates/tracing-actix
770//! [`axum-insights`]: https://crates.io/crates/axum-insights
771//! [`tracing-gelf`]: https://crates.io/crates/tracing-gelf
772//! [`tracing-coz`]: https://crates.io/crates/tracing-coz
773//! [coz]: https://github.com/plasma-umass/coz
774//! [`tracing-bunyan-formatter`]: https://crates.io/crates/tracing-bunyan-formatter
775//! [bunyan]: https://github.com/trentm/node-bunyan
776//! [`tracing-wasm`]: https://docs.rs/tracing-wasm
777//! [`tracing-web`]: https://docs.rs/tracing-web
778//! [User Timing API (`window.performance`)]: https://developer.mozilla.org/en-US/docs/Web/API/User_Timing_API
779//! [`tide-tracing`]: https://crates.io/crates/tide-tracing
780//! [tide]: https://crates.io/crates/tide
781//! [`test-log`]: https://crates.io/crates/test-log
782//! [`tracing-unwrap`]: https://docs.rs/tracing-unwrap
783//! [`diesel`]: https://crates.io/crates/diesel
784//! [`diesel-tracing`]: https://crates.io/crates/diesel-tracing
785//! [`tracing-tracy`]: https://crates.io/crates/tracing-tracy
786//! [Tracy]: https://github.com/wolfpld/tracy
787//! [`tracing-elastic-apm`]: https://crates.io/crates/tracing-elastic-apm
788//! [Elastic APM]: https://www.elastic.co/apm
789//! [`tracing-etw`]: https://github.com/microsoft/rust_win_etw/tree/main/win_etw_tracing
790//! [ETW]: https://docs.microsoft.com/en-us/windows/win32/etw/about-event-tracing
791//! [`tracing-fluent-assertions`]: https://crates.io/crates/tracing-fluent-assertions
792//! [`sentry-tracing`]: https://crates.io/crates/sentry-tracing
793//! [Sentry]: https://sentry.io/welcome/
794//! [`tracing-forest`]: https://crates.io/crates/tracing-forest
795//! [`tracing-loki`]: https://crates.io/crates/tracing-loki
796//! [Grafana Loki]: https://grafana.com/oss/loki/
797//! [`tracing-logfmt`]: https://crates.io/crates/tracing-logfmt
798//! [`reqwest-tracing`]: https://crates.io/crates/reqwest-tracing
799//! [`reqwest`]: https://crates.io/crates/reqwest
800//! [`tracing-cloudwatch`]: https://crates.io/crates/tracing-cloudwatch
801//! [`clippy-tracing`]: https://crates.io/crates/clippy-tracing
802//!
803//! <pre class="ignore" style="white-space:normal;font:inherit;">
804//! <strong>Note</strong>: Some of these ecosystem crates are currently
805//! unreleased and/or in earlier stages of development. They may be less stable
806//! than <code>tracing</code> and <code>tracing-core</code>.
807//! </pre>
808//!
809//! ## Crate Feature Flags
810//!
811//! The following crate [feature flags] are available:
812//!
813//! * A set of features controlling the [static verbosity level].
814//! * `log`: causes trace instrumentation points to emit [`log`] records as well
815//! as trace events, if a default `tracing` subscriber has not been set. This
816//! is intended for use in libraries whose users may be using either `tracing`
817//! or `log`.
818//! * `log-always`: Emit `log` records from all `tracing` spans and events, even
819//! if a `tracing` subscriber has been set. This should be set only by
820//! applications which intend to collect traces and logs separately; if an
821//! adapter is used to convert `log` records into `tracing` events, this will
822//! cause duplicate events to occur.
823//! * `attributes`: Includes support for the `#[instrument]` attribute.
824//! This is on by default, but does bring in the `syn` crate as a dependency,
825//! which may add to the compile time of crates that do not already use it.
826//! * `std`: Depend on the Rust standard library (enabled by default).
827//!
828//! `no_std` users may disable this feature with `default-features = false`:
829//!
830//! ```toml
831//! [dependencies]
832//! tracing = { version = "0.1.38", default-features = false }
833//! ```
834//!
835//! <pre class="ignore" style="white-space:normal;font:inherit;">
836//! <strong>Note</strong>: <code>tracing</code>'s <code>no_std</code> support
837//! requires <code>liballoc</code>.
838//! </pre>
839//!
840//! ### Unstable Features
841//!
842//! These feature flags enable **unstable** features. The public API may break in 0.1.x
843//! releases. To enable these features, the `--cfg tracing_unstable` must be passed to
844//! `rustc` when compiling.
845//!
846//! The following unstable feature flags are currently available:
847//!
848//! * `valuable`: Enables support for recording [field values] using the
849//! [`valuable`] crate.
850//!
851//! #### Enabling Unstable Features
852//!
853//! The easiest way to set the `tracing_unstable` cfg is to use the `RUSTFLAGS`
854//! env variable when running `cargo` commands:
855//!
856//! ```shell
857//! RUSTFLAGS="--cfg tracing_unstable" cargo build
858//! ```
859//! Alternatively, the following can be added to the `.cargo/config` file in a
860//! project to automatically enable the cfg flag for that project:
861//!
862//! ```toml
863//! [build]
864//! rustflags = ["--cfg", "tracing_unstable"]
865//! ```
866//!
867//! [feature flags]: https://doc.rust-lang.org/cargo/reference/manifest.html#the-features-section
868//! [field values]: crate::field
869//! [`valuable`]: https://crates.io/crates/valuable
870//!
871//! ## Supported Rust Versions
872//!
873//! Tracing is built against the latest stable release. The minimum supported
874//! version is 1.56. The current Tracing version is not guaranteed to build on
875//! Rust versions earlier than the minimum supported version.
876//!
877//! Tracing follows the same compiler support policies as the rest of the Tokio
878//! project. The current stable Rust compiler and the three most recent minor
879//! versions before it will always be supported. For example, if the current
880//! stable compiler version is 1.69, the minimum supported version will not be
881//! increased past 1.66, three minor versions prior. Increasing the minimum
882//! supported compiler version is not considered a semver breaking change as
883//! long as doing so complies with this policy.
884//!
885//! [`log`]: https://docs.rs/log/0.4.6/log/
886//! [span]: mod@span
887//! [spans]: mod@span
888//! [`Span`]: span::Span
889//! [`in_scope`]: span::Span::in_scope
890//! [event]: Event
891//! [events]: Event
892//! [`Subscriber`]: subscriber::Subscriber
893//! [Subscriber::event]: subscriber::Subscriber::event
894//! [`enter`]: subscriber::Subscriber::enter
895//! [`exit`]: subscriber::Subscriber::exit
896//! [`enabled`]: subscriber::Subscriber::enabled
897//! [metadata]: Metadata
898//! [`field::display`]: field::display
899//! [`field::debug`]: field::debug
900//! [`set_global_default`]: subscriber::set_global_default
901//! [`with_default`]: subscriber::with_default
902//! [`tokio-rs/tracing`]: https://github.com/tokio-rs/tracing
903//! [`tracing-futures`]: https://crates.io/crates/tracing-futures
904//! [`tracing-subscriber`]: https://crates.io/crates/tracing-subscriber
905//! [`tracing-log`]: https://crates.io/crates/tracing-log
906//! [`tracing-timing`]: https://crates.io/crates/tracing-timing
907//! [`tracing-appender`]: https://crates.io/crates/tracing-appender
908//! [`env_logger`]: https://crates.io/crates/env_logger
909//! [`FmtSubscriber`]: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/fmt/struct.Subscriber.html
910//! [static verbosity level]: level_filters#compile-time-filters
911//! [instrument]: https://docs.rs/tracing-attributes/latest/tracing_attributes/attr.instrument.html
912//! [flags]: #crate-feature-flags
913#![cfg_attr(not(feature = "std"), no_std)]
914#![cfg_attr(docsrs, feature(doc_cfg), deny(rustdoc::broken_intra_doc_links))]
915#![doc(
916 html_logo_url = "https://raw.githubusercontent.com/tokio-rs/tracing/master/assets/logo-type.png",
917 issue_tracker_base_url = "https://github.com/tokio-rs/tracing/issues/"
918)]
919#![warn(
920 missing_debug_implementations,
921 missing_docs,
922 rust_2018_idioms,
923 unreachable_pub,
924 bad_style,
925 dead_code,
926 improper_ctypes,
927 non_shorthand_field_patterns,
928 no_mangle_generic_items,
929 overflowing_literals,
930 path_statements,
931 patterns_in_fns_without_body,
932 private_in_public,
933 unconditional_recursion,
934 unused,
935 unused_allocation,
936 unused_comparisons,
937 unused_parens,
938 while_true
939)]
940
941#[cfg(not(feature = "std"))]
942extern crate alloc;
943
944// Somehow this `use` statement is necessary for us to re-export the `core`
945// macros on Rust 1.26.0. I'm not sure how this makes it work, but it does.
946#[allow(unused_imports)]
947#[doc(hidden)]
948use tracing_core::*;
949
950#[doc(inline)]
951pub use self::instrument::Instrument;
952pub use self::{dispatcher::Dispatch, event::Event, field::Value, subscriber::Subscriber};
953
954#[doc(hidden)]
955pub use self::span::Id;
956
957#[doc(hidden)]
958pub use tracing_core::{
959 callsite::{self, Callsite},
960 metadata,
961};
962pub use tracing_core::{event, Level, Metadata};
963
964#[doc(inline)]
965pub use self::span::Span;
966#[cfg(feature = "attributes")]
967#[cfg_attr(docsrs, doc(cfg(feature = "attributes")))]
968#[doc(inline)]
969pub use tracing_attributes::instrument;
970
971#[macro_use]
972mod macros;
973
974pub mod dispatcher;
975pub mod field;
976/// Attach a span to a `std::future::Future`.
977pub mod instrument;
978pub mod level_filters;
979pub mod span;
980pub(crate) mod stdlib;
981pub mod subscriber;
982
983#[doc(hidden)]
984pub mod __macro_support {
985 pub use crate::callsite::Callsite;
986 use crate::{subscriber::Interest, Metadata};
987 pub use core::concat;
988
989 /// Callsite implementation used by macro-generated code.
990 ///
991 /// /!\ WARNING: This is *not* a stable API! /!\
992 /// This type, and all code contained in the `__macro_support` module, is
993 /// a *private* API of `tracing`. It is exposed publicly because it is used
994 /// by the `tracing` macros, but it is not part of the stable versioned API.
995 /// Breaking changes to this module may occur in small-numbered versions
996 /// without warning.
997 pub use tracing_core::callsite::DefaultCallsite as MacroCallsite;
998
999 /// /!\ WARNING: This is *not* a stable API! /!\
1000 /// This function, and all code contained in the `__macro_support` module, is
1001 /// a *private* API of `tracing`. It is exposed publicly because it is used
1002 /// by the `tracing` macros, but it is not part of the stable versioned API.
1003 /// Breaking changes to this module may occur in small-numbered versions
1004 /// without warning.
1005 pub fn __is_enabled(meta: &Metadata<'static>, interest: Interest) -> bool {
1006 interest.is_always() || crate::dispatcher::get_default(|default| default.enabled(meta))
1007 }
1008
1009 /// /!\ WARNING: This is *not* a stable API! /!\
1010 /// This function, and all code contained in the `__macro_support` module, is
1011 /// a *private* API of `tracing`. It is exposed publicly because it is used
1012 /// by the `tracing` macros, but it is not part of the stable versioned API.
1013 /// Breaking changes to this module may occur in small-numbered versions
1014 /// without warning.
1015 #[inline]
1016 #[cfg(feature = "log")]
1017 pub fn __disabled_span(meta: &'static Metadata<'static>) -> crate::Span {
1018 crate::Span::new_disabled(meta)
1019 }
1020
1021 /// /!\ WARNING: This is *not* a stable API! /!\
1022 /// This function, and all code contained in the `__macro_support` module, is
1023 /// a *private* API of `tracing`. It is exposed publicly because it is used
1024 /// by the `tracing` macros, but it is not part of the stable versioned API.
1025 /// Breaking changes to this module may occur in small-numbered versions
1026 /// without warning.
1027 #[inline]
1028 #[cfg(not(feature = "log"))]
1029 pub fn __disabled_span(_: &'static Metadata<'static>) -> crate::Span {
1030 crate::Span::none()
1031 }
1032
1033 /// /!\ WARNING: This is *not* a stable API! /!\
1034 /// This function, and all code contained in the `__macro_support` module, is
1035 /// a *private* API of `tracing`. It is exposed publicly because it is used
1036 /// by the `tracing` macros, but it is not part of the stable versioned API.
1037 /// Breaking changes to this module may occur in small-numbered versions
1038 /// without warning.
1039 #[cfg(feature = "log")]
1040 pub fn __tracing_log(
1041 meta: &Metadata<'static>,
1042 logger: &'static dyn log::Log,
1043 log_meta: log::Metadata<'_>,
1044 values: &tracing_core::field::ValueSet<'_>,
1045 ) {
1046 logger.log(
1047 &crate::log::Record::builder()
1048 .file(meta.file())
1049 .module_path(meta.module_path())
1050 .line(meta.line())
1051 .metadata(log_meta)
1052 .args(format_args!(
1053 "{}",
1054 crate::log::LogValueSet {
1055 values,
1056 is_first: true
1057 }
1058 ))
1059 .build(),
1060 );
1061 }
1062}
1063
1064#[cfg(feature = "log")]
1065#[doc(hidden)]
1066pub mod log {
1067 use core::fmt;
1068 pub use log::*;
1069 use tracing_core::field::{Field, ValueSet, Visit};
1070
1071 /// Utility to format [`ValueSet`]s for logging.
1072 pub(crate) struct LogValueSet<'a> {
1073 pub(crate) values: &'a ValueSet<'a>,
1074 pub(crate) is_first: bool,
1075 }
1076
1077 impl<'a> fmt::Display for LogValueSet<'a> {
1078 #[inline]
1079 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1080 struct LogVisitor<'a, 'b> {
1081 f: &'a mut fmt::Formatter<'b>,
1082 is_first: bool,
1083 result: fmt::Result,
1084 }
1085
1086 impl Visit for LogVisitor<'_, '_> {
1087 fn record_debug(&mut self, field: &Field, value: &dyn fmt::Debug) {
1088 let res = if self.is_first {
1089 self.is_first = false;
1090 if field.name() == "message" {
1091 write!(self.f, "{:?}", value)
1092 } else {
1093 write!(self.f, "{}={:?}", field.name(), value)
1094 }
1095 } else {
1096 write!(self.f, " {}={:?}", field.name(), value)
1097 };
1098 if let Err(err) = res {
1099 self.result = self.result.and(Err(err));
1100 }
1101 }
1102
1103 fn record_str(&mut self, field: &Field, value: &str) {
1104 if field.name() == "message" {
1105 self.record_debug(field, &format_args!("{}", value))
1106 } else {
1107 self.record_debug(field, &value)
1108 }
1109 }
1110 }
1111
1112 let mut visit = LogVisitor {
1113 f,
1114 is_first: self.is_first,
1115 result: Ok(()),
1116 };
1117 self.values.record(&mut visit);
1118 visit.result
1119 }
1120 }
1121}
1122
1123mod sealed {
1124 pub trait Sealed {}
1125}
1126