Adding upstream version 110.0.1.upstream/110.0.1upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 1115 insertions, 0 deletions

diff --git a/third_party/rust/tracing/src/lib.rs b/third_party/rust/tracing/src/lib.rs
new file mode 100644
index 0000000000..342e04a825
--- /dev/null
+++ b/third_party/rust/tracing/src/lib.rs
@@ -0,0 +1,1115 @@
+//! A scoped, structured logging and diagnostics system.
+//!
+//! # Overview
+//!
+//! `tracing` is a framework for instrumenting Rust programs to collect
+//! structured, event-based diagnostic information.
+//!
+//! In asynchronous systems like Tokio, interpreting traditional log messages can
+//! often be quite challenging. Since individual tasks are multiplexed on the same
+//! thread, associated events and log lines are intermixed making it difficult to
+//! trace the logic flow. `tracing` expands upon logging-style diagnostics by
+//! allowing libraries and applications to record structured events with additional
+//! information about *temporality* and *causality* — unlike a log message, a span
+//! in `tracing` has a beginning and end time, may be entered and exited by the
+//! flow of execution, and may exist within a nested tree of similar spans. In
+//! addition, `tracing` spans are *structured*, with the ability to record typed
+//! data as well as textual messages.
+//!
+//! The `tracing` crate provides the APIs necessary for instrumenting libraries
+//! and applications to emit trace data.
+//!
+//! *Compiler support: [requires `rustc` 1.49+][msrv]*
+//!
+//! [msrv]: #supported-rust-versions
+//! # Core Concepts
+//!
+//! The core of `tracing`'s API is composed of _spans_, _events_ and
+//! _subscribers_. We'll cover these in turn.
+//!
+//! ## Spans
+//!
+//! To record the flow of execution through a program, `tracing` introduces the
+//! concept of [spans]. Unlike a log line that represents a _moment in
+//! time_, a span represents a _period of time_ with a beginning and an end. When a
+//! program begins executing in a context or performing a unit of work, it
+//! _enters_ that context's span, and when it stops executing in that context,
+//! it _exits_ the span. The span in which a thread is currently executing is
+//! referred to as that thread's _current_ span.
+//!
+//! For example:
+//! ```
+//! use tracing::{span, Level};
+//! # fn main() {
+//! let span = span!(Level::TRACE, "my_span");
+//! // `enter` returns a RAII guard which, when dropped, exits the span. this
+//! // indicates that we are in the span for the current lexical scope.
+//! let _enter = span.enter();
+//! // perform some work in the context of `my_span`...
+//! # }
+//!```
+//!
+//! The [`span` module][span]'s documentation provides further details on how to
+//! use spans.
+//!
+//! <div class="example-wrap" style="display:inline-block"><pre class="compile_fail" style="white-space:normal;font:inherit;">
+//!
+//!  **Warning**: In asynchronous code that uses async/await syntax,
+//!  `Span::enter` may produce incorrect traces if the returned drop
+//!  guard is held across an await point. See
+//!  [the method documentation][Span#in-asynchronous-code] for details.
+//!
+//! </pre></div>
+//!
+//! ## Events
+//!
+//! An [`Event`] represents a _moment_ in time. It signifies something that
+//! happened while a trace was being recorded. `Event`s are comparable to the log
+//! records emitted by unstructured logging code, but unlike a typical log line,
+//! an `Event` may occur within the context of a span.
+//!
+//! For example:
+//! ```
+//! use tracing::{event, span, Level};
+//!
+//! # fn main() {
+//! // records an event outside of any span context:
+//! event!(Level::INFO, "something happened");
+//!
+//! let span = span!(Level::INFO, "my_span");
+//! let _guard = span.enter();
+//!
+//! // records an event within "my_span".
+//! event!(Level::DEBUG, "something happened inside my_span");
+//! # }
+//!```
+//!
+//! In general, events should be used to represent points in time _within_ a
+//! span — a request returned with a given status code, _n_ new items were
+//! taken from a queue, and so on.
+//!
+//! The [`Event` struct][`Event`] documentation provides further details on using
+//! events.
+//!
+//! ## Subscribers
+//!
+//! As `Span`s and `Event`s occur, they are recorded or aggregated by
+//! implementations of the [`Subscriber`] trait. `Subscriber`s are notified
+//! when an `Event` takes place and when a `Span` is entered or exited. These
+//! notifications are represented by the following `Subscriber` trait methods:
+//!
+//! + [`event`][Subscriber::event], called when an `Event` takes place,
+//! + [`enter`], called when execution enters a `Span`,
+//! + [`exit`], called when execution exits a `Span`
+//!
+//! In addition, subscribers may implement the [`enabled`] function to _filter_
+//! the notifications they receive based on [metadata] describing each `Span`
+//! or `Event`. If a call to `Subscriber::enabled` returns `false` for a given
+//! set of metadata, that `Subscriber` will *not* be notified about the
+//! corresponding `Span` or `Event`. For performance reasons, if no currently
+//! active subscribers express interest in a given set of metadata by returning
+//! `true`, then the corresponding `Span` or `Event` will never be constructed.
+//!
+//! # Usage
+//!
+//! First, add this to your `Cargo.toml`:
+//!
+//! ```toml
+//! [dependencies]
+//! tracing = "0.1"
+//! ```
+//!
+//! ## Recording Spans and Events
+//!
+//! Spans and events are recorded using macros.
+//!
+//! ### Spans
+//!
+//! The [`span!`] macro expands to a [`Span` struct][`Span`] which is used to
+//! record a span. The [`Span::enter`] method on that struct records that the
+//! span has been entered, and returns a [RAII] guard object, which will exit
+//! the span when dropped.
+//!
+//! For example:
+//!
+//! ```rust
+//! use tracing::{span, Level};
+//! # fn main() {
+//! // Construct a new span named "my span" with trace log level.
+//! let span = span!(Level::TRACE, "my span");
+//!
+//! // Enter the span, returning a guard object.
+//! let _enter = span.enter();
+//!
+//! // Any trace events that occur before the guard is dropped will occur
+//! // within the span.
+//!
+//! // Dropping the guard will exit the span.
+//! # }
+//! ```
+//!
+//! The [`#[instrument]`][instrument] attribute provides an easy way to
+//! add `tracing` spans to functions. A function annotated with `#[instrument]`
+//! will create and enter a span with that function's name every time the
+//! function is called, with arguments to that function will be recorded as
+//! fields using `fmt::Debug`.
+//!
+//! For example:
+//! ```ignore
+//! # // this doctest is ignored because we don't have a way to say
+//! # // that it should only be run with cfg(feature = "attributes")
+//! use tracing::{Level, event, instrument};
+//!
+//! #[instrument]
+//! pub fn my_function(my_arg: usize) {
+//!     // This event will be recorded inside a span named `my_function` with the
+//!     // field `my_arg`.
+//!     event!(Level::INFO, "inside my_function!");
+//!     // ...
+//! }
+//! # fn main() {}
+//! ```
+//!
+//! For functions which don't have built-in tracing support and can't have
+//! the `#[instrument]` attribute applied (such as from an external crate),
+//! the [`Span` struct][`Span`] has a [`in_scope()` method][`in_scope`]
+//! which can be used to easily wrap synchonous code in a span.
+//!
+//! For example:
+//! ```rust
+//! use tracing::info_span;
+//!
+//! # fn doc() -> Result<(), ()> {
+//! # mod serde_json {
+//! #    pub(crate) fn from_slice(buf: &[u8]) -> Result<(), ()> { Ok(()) }
+//! # }
+//! # let buf: [u8; 0] = [];
+//! let json = info_span!("json.parse").in_scope(|| serde_json::from_slice(&buf))?;
+//! # let _ = json; // suppress unused variable warning
+//! # Ok(())
+//! # }
+//! ```
+//!
+//! You can find more examples showing how to use this crate [here][examples].
+//!
+//! [RAII]: https://github.com/rust-unofficial/patterns/blob/master/patterns/behavioural/RAII.md
+//! [examples]: https://github.com/tokio-rs/tracing/tree/master/examples
+//!
+//! ### Events
+//!
+//! [`Event`]s are recorded using the [`event!`] macro:
+//!
+//! ```rust
+//! # fn main() {
+//! use tracing::{event, Level};
+//! event!(Level::INFO, "something has happened!");
+//! # }
+//! ```
+//!
+//! ## Using the Macros
+//!
+//! The [`span!`] and [`event!`] macros as well as the `#[instrument]` attribute
+//! use fairly similar syntax, with some exceptions.
+//!
+//! ### Configuring Attributes
+//!
+//! Both macros require a [`Level`] specifying the verbosity of the span or
+//! event. Optionally, the [target] and [parent span] may be overridden. If the
+//! target and parent span are not overridden, they will default to the
+//! module path where the macro was invoked and the current span (as determined
+//! by the subscriber), respectively.
+//!
+//! For example:
+//!
+//! ```
+//! # use tracing::{span, event, Level};
+//! # fn main() {
+//! span!(target: "app_spans", Level::TRACE, "my span");
+//! event!(target: "app_events", Level::INFO, "something has happened!");
+//! # }
+//! ```
+//! ```
+//! # use tracing::{span, event, Level};
+//! # fn main() {
+//! let span = span!(Level::TRACE, "my span");
+//! event!(parent: &span, Level::INFO, "something has happened!");
+//! # }
+//! ```
+//!
+//! The span macros also take a string literal after the level, to set the name
+//! of the span.
+//!
+//! ### Recording Fields
+//!
+//! Structured fields on spans and events are specified using the syntax
+//! `field_name = field_value`. Fields are separated by commas.
+//!
+//! ```
+//! # use tracing::{event, Level};
+//! # fn main() {
+//! // records an event with two fields:
+//! //  - "answer", with the value 42
+//! //  - "question", with the value "life, the universe and everything"
+//! event!(Level::INFO, answer = 42, question = "life, the universe, and everything");
+//! # }
+//! ```
+//!
+//! As shorthand, local variables may be used as field values without an
+//! assignment, similar to [struct initializers]. For example:
+//!
+//! ```
+//! # use tracing::{span, Level};
+//! # fn main() {
+//! let user = "ferris";
+//!
+//! span!(Level::TRACE, "login", user);
+//! // is equivalent to:
+//! span!(Level::TRACE, "login", user = user);
+//! # }
+//!```
+//!
+//! Field names can include dots, but should not be terminated by them:
+//! ```
+//! # use tracing::{span, Level};
+//! # fn main() {
+//! let user = "ferris";
+//! let email = "ferris@rust-lang.org";
+//! span!(Level::TRACE, "login", user, user.email = email);
+//! # }
+//!```
+//!
+//! Since field names can include dots, fields on local structs can be used
+//! using the local variable shorthand:
+//! ```
+//! # use tracing::{span, Level};
+//! # fn main() {
+//! # struct User {
+//! #    name: &'static str,
+//! #    email: &'static str,
+//! # }
+//! let user = User {
+//!     name: "ferris",
+//!     email: "ferris@rust-lang.org",
+//! };
+//! // the span will have the fields `user.name = "ferris"` and
+//! // `user.email = "ferris@rust-lang.org"`.
+//! span!(Level::TRACE, "login", user.name, user.email);
+//! # }
+//!```
+//!
+//! Fields with names that are not Rust identifiers, or with names that are Rust reserved words,
+//! may be created using quoted string literals. However, this may not be used with the local
+//! variable shorthand.
+//! ```
+//! # use tracing::{span, Level};
+//! # fn main() {
+//! // records an event with fields whose names are not Rust identifiers
+//! //  - "guid:x-request-id", containing a `:`, with the value "abcdef"
+//! //  - "type", which is a reserved word, with the value "request"
+//! span!(Level::TRACE, "api", "guid:x-request-id" = "abcdef", "type" = "request");
+//! # }
+//!```
+//!
+//! The `?` sigil is shorthand that specifies a field should be recorded using
+//! its [`fmt::Debug`] implementation:
+//! ```
+//! # use tracing::{event, Level};
+//! # fn main() {
+//! #[derive(Debug)]
+//! struct MyStruct {
+//!     field: &'static str,
+//! }
+//!
+//! let my_struct = MyStruct {
+//!     field: "Hello world!"
+//! };
+//!
+//! // `my_struct` will be recorded using its `fmt::Debug` implementation.
+//! event!(Level::TRACE, greeting = ?my_struct);
+//! // is equivalent to:
+//! event!(Level::TRACE, greeting = tracing::field::debug(&my_struct));
+//! # }
+//! ```
+//!
+//! The `%` sigil operates similarly, but indicates that the value should be
+//! recorded using its [`fmt::Display`] implementation:
+//! ```
+//! # use tracing::{event, Level};
+//! # fn main() {
+//! # #[derive(Debug)]
+//! # struct MyStruct {
+//! #     field: &'static str,
+//! # }
+//! #
+//! # let my_struct = MyStruct {
+//! #     field: "Hello world!"
+//! # };
+//! // `my_struct.field` will be recorded using its `fmt::Display` implementation.
+//! event!(Level::TRACE, greeting = %my_struct.field);
+//! // is equivalent to:
+//! event!(Level::TRACE, greeting = tracing::field::display(&my_struct.field));
+//! # }
+//! ```
+//!
+//! The `%` and `?` sigils may also be used with local variable shorthand:
+//!
+//! ```
+//! # use tracing::{event, Level};
+//! # fn main() {
+//! # #[derive(Debug)]
+//! # struct MyStruct {
+//! #     field: &'static str,
+//! # }
+//! #
+//! # let my_struct = MyStruct {
+//! #     field: "Hello world!"
+//! # };
+//! // `my_struct.field` will be recorded using its `fmt::Display` implementation.
+//! event!(Level::TRACE, %my_struct.field);
+//! # }
+//! ```
+//!
+//! Additionally, a span may declare fields with the special value [`Empty`],
+//! which indicates that that the value for that field does not currently exist
+//! but may be recorded later. For example:
+//!
+//! ```
+//! use tracing::{trace_span, field};
+//!
+//! // Create a span with two fields: `greeting`, with the value "hello world", and
+//! // `parting`, without a value.
+//! let span = trace_span!("my_span", greeting = "hello world", parting = field::Empty);
+//!
+//! // ...
+//!
+//! // Now, record a value for parting as well.
+//! span.record("parting", &"goodbye world!");
+//! ```
+//!
+//! Note that a span may have up to 32 fields. The following will not compile:
+//!
+//! ```rust,compile_fail
+//! # use tracing::Level;
+//! # fn main() {
+//! let bad_span = span!(
+//!     Level::TRACE,
+//!     "too many fields!",
+//!     a = 1, b = 2, c = 3, d = 4, e = 5, f = 6, g = 7, h = 8, i = 9,
+//!     j = 10, k = 11, l = 12, m = 13, n = 14, o = 15, p = 16, q = 17,
+//!     r = 18, s = 19, t = 20, u = 21, v = 22, w = 23, x = 24, y = 25,
+//!     z = 26, aa = 27, bb = 28, cc = 29, dd = 30, ee = 31, ff = 32, gg = 33
+//! );
+//! # }
+//! ```
+//!
+//! Finally, events may also include human-readable messages, in the form of a
+//! [format string][fmt] and (optional) arguments, **after** the event's
+//! key-value fields. If a format string and arguments are provided,
+//! they will implicitly create a new field named `message` whose value is the
+//! provided set of format arguments.
+//!
+//! For example:
+//!
+//! ```
+//! # use tracing::{event, Level};
+//! # fn main() {
+//! let question = "the ultimate question of life, the universe, and everything";
+//! let answer = 42;
+//! // records an event with the following fields:
+//! // - `question.answer` with the value 42,
+//! // - `question.tricky` with the value `true`,
+//! // - "message", with the value "the answer to the ultimate question of life, the
+//! //    universe, and everything is 42."
+//! event!(
+//!     Level::DEBUG,
+//!     question.answer = answer,
+//!     question.tricky = true,
+//!     "the answer to {} is {}.", question, answer
+//! );
+//! # }
+//! ```
+//!
+//! Specifying a formatted message in this manner does not allocate by default.
+//!
+//! [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
+//! [target]: Metadata::target
+//! [parent span]: span::Attributes::parent
+//! [determined contextually]: span::Attributes::is_contextual
+//! [`fmt::Debug`]: std::fmt::Debug
+//! [`fmt::Display`]: std::fmt::Display
+//! [fmt]: std::fmt#usage
+//! [`Empty`]: field::Empty
+//!
+//! ### Shorthand Macros
+//!
+//! `tracing` also offers a number of macros with preset verbosity levels.
+//! The [`trace!`], [`debug!`], [`info!`], [`warn!`], and [`error!`] behave
+//! similarly to the [`event!`] macro, but with the [`Level`] argument already
+//! specified, while the corresponding [`trace_span!`], [`debug_span!`],
+//! [`info_span!`], [`warn_span!`], and [`error_span!`] macros are the same,
+//! but for the [`span!`] macro.
+//!
+//! These are intended both as a shorthand, and for compatibility with the [`log`]
+//! crate (see the next section).
+//!
+//! [`span!`]: span!
+//! [`event!`]: event!
+//! [`trace!`]: trace!
+//! [`debug!`]: debug!
+//! [`info!`]: info!
+//! [`warn!`]: warn!
+//! [`error!`]: error!
+//! [`trace_span!`]: trace_span!
+//! [`debug_span!`]: debug_span!
+//! [`info_span!`]: info_span!
+//! [`warn_span!`]: warn_span!
+//! [`error_span!`]: error_span!
+//!
+//! ### For `log` Users
+//!
+//! Users of the [`log`] crate should note that `tracing` exposes a set of
+//! macros for creating `Event`s (`trace!`, `debug!`, `info!`, `warn!`, and
+//! `error!`) which may be invoked with the same syntax as the similarly-named
+//! macros from the `log` crate. Often, the process of converting a project to
+//! use `tracing` can begin with a simple drop-in replacement.
+//!
+//! Let's consider the `log` crate's yak-shaving example:
+//!
+//! ```rust,ignore
+//! use std::{error::Error, io};
+//! use tracing::{debug, error, info, span, warn, Level};
+//!
+//! // the `#[tracing::instrument]` attribute creates and enters a span
+//! // every time the instrumented function is called. The span is named after the
+//! // the function or method. Parameters passed to the function are recorded as fields.
+//! #[tracing::instrument]
+//! pub fn shave(yak: usize) -> Result<(), Box<dyn Error + 'static>> {
+//!     // this creates an event at the DEBUG level with two fields:
+//!     // - `excitement`, with the key "excitement" and the value "yay!"
+//!     // - `message`, with the key "message" and the value "hello! I'm gonna shave a yak."
+//!     //
+//!     // unlike other fields, `message`'s shorthand initialization is just the string itself.
+//!     debug!(excitement = "yay!", "hello! I'm gonna shave a yak.");
+//!     if yak == 3 {
+//!         warn!("could not locate yak!");
+//!         // note that this is intended to demonstrate `tracing`'s features, not idiomatic
+//!         // error handling! in a library or application, you should consider returning
+//!         // a dedicated `YakError`. libraries like snafu or thiserror make this easy.
+//!         return Err(io::Error::new(io::ErrorKind::Other, "shaving yak failed!").into());
+//!     } else {
+//!         debug!("yak shaved successfully");
+//!     }
+//!     Ok(())
+//! }
+//!
+//! pub fn shave_all(yaks: usize) -> usize {
+//!     // Constructs a new span named "shaving_yaks" at the TRACE level,
+//!     // and a field whose key is "yaks". This is equivalent to writing:
+//!     //
+//!     // let span = span!(Level::TRACE, "shaving_yaks", yaks = yaks);
+//!     //
+//!     // local variables (`yaks`) can be used as field values
+//!     // without an assignment, similar to struct initializers.
+//!     let _span = span!(Level::TRACE, "shaving_yaks", yaks).entered();
+//!
+//!     info!("shaving yaks");
+//!
+//!     let mut yaks_shaved = 0;
+//!     for yak in 1..=yaks {
+//!         let res = shave(yak);
+//!         debug!(yak, shaved = res.is_ok());
+//!
+//!         if let Err(ref error) = res {
+//!             // Like spans, events can also use the field initialization shorthand.
+//!             // In this instance, `yak` is the field being initalized.
+//!             error!(yak, error = error.as_ref(), "failed to shave yak!");
+//!         } else {
+//!             yaks_shaved += 1;
+//!         }
+//!         debug!(yaks_shaved);
+//!     }
+//!
+//!     yaks_shaved
+//! }
+//! ```
+//!
+//! ## In libraries
+//!
+//! Libraries should link only to the `tracing` crate, and use the provided
+//! macros to record whatever information will be useful to downstream
+//! consumers.
+//!
+//! ## In executables
+//!
+//! In order to record trace events, executables have to use a `Subscriber`
+//! implementation compatible with `tracing`. A `Subscriber` implements a
+//! way of collecting trace data, such as by logging it to standard output.
+//!
+//! This library does not contain any `Subscriber` implementations; these are
+//! provided by [other crates](#related-crates).
+//!
+//! The simplest way to use a subscriber is to call the [`set_global_default`]
+//! function:
+//!
+//! ```
+//! extern crate tracing;
+//! # pub struct FooSubscriber;
+//! # use tracing::{span::{Id, Attributes, Record}, Metadata};
+//! # impl tracing::Subscriber for FooSubscriber {
+//! #   fn new_span(&self, _: &Attributes) -> Id { Id::from_u64(0) }
+//! #   fn record(&self, _: &Id, _: &Record) {}
+//! #   fn event(&self, _: &tracing::Event) {}
+//! #   fn record_follows_from(&self, _: &Id, _: &Id) {}
+//! #   fn enabled(&self, _: &Metadata) -> bool { false }
+//! #   fn enter(&self, _: &Id) {}
+//! #   fn exit(&self, _: &Id) {}
+//! # }
+//! # impl FooSubscriber {
+//! #   fn new() -> Self { FooSubscriber }
+//! # }
+//! # fn main() {
+//!
+//! let my_subscriber = FooSubscriber::new();
+//! tracing::subscriber::set_global_default(my_subscriber)
+//!     .expect("setting tracing default failed");
+//! # }
+//! ```
+//!
+//! <pre class="compile_fail" style="white-space:normal;font:inherit;">
+//!     <strong>Warning</strong>: In general, libraries should <em>not</em> call
+//!     <code>set_global_default()</code>! Doing so will cause conflicts when
+//!     executables that depend on the library try to set the default later.
+//! </pre>
+//!
+//! This subscriber will be used as the default in all threads for the
+//! remainder of the duration of the program, similar to setting the logger
+//! in the `log` crate.
+//!
+//! In addition, the default subscriber can be set through using the
+//! [`with_default`] function. This follows the `tokio` pattern of using
+//! closures to represent executing code in a context that is exited at the end
+//! of the closure. For example:
+//!
+//! ```rust
+//! # pub struct FooSubscriber;
+//! # use tracing::{span::{Id, Attributes, Record}, Metadata};
+//! # impl tracing::Subscriber for FooSubscriber {
+//! #   fn new_span(&self, _: &Attributes) -> Id { Id::from_u64(0) }
+//! #   fn record(&self, _: &Id, _: &Record) {}
+//! #   fn event(&self, _: &tracing::Event) {}
+//! #   fn record_follows_from(&self, _: &Id, _: &Id) {}
+//! #   fn enabled(&self, _: &Metadata) -> bool { false }
+//! #   fn enter(&self, _: &Id) {}
+//! #   fn exit(&self, _: &Id) {}
+//! # }
+//! # impl FooSubscriber {
+//! #   fn new() -> Self { FooSubscriber }
+//! # }
+//! # fn main() {
+//!
+//! let my_subscriber = FooSubscriber::new();
+//! # #[cfg(feature = "std")]
+//! tracing::subscriber::with_default(my_subscriber, || {
+//!     // Any trace events generated in this closure or by functions it calls
+//!     // will be collected by `my_subscriber`.
+//! })
+//! # }
+//! ```
+//!
+//! This approach allows trace data to be collected by multiple subscribers
+//! within different contexts in the program. Note that the override only applies to the
+//! currently executing thread; other threads will not see the change from with_default.
+//!
+//! Any trace events generated outside the context of a subscriber will not be collected.
+//!
+//! Once a subscriber has been set, instrumentation points may be added to the
+//! executable using the `tracing` crate's macros.
+//!
+//! ## `log` Compatibility
+//!
+//! The [`log`] crate provides a simple, lightweight logging facade for Rust.
+//! While `tracing` builds upon `log`'s foundation with richer structured
+//! diagnostic data, `log`'s simplicity and ubiquity make it the "lowest common
+//! denominator" for text-based logging in Rust — a vast majority of Rust
+//! libraries and applications either emit or consume `log` records. Therefore,
+//! `tracing` provides multiple forms of interoperability with `log`: `tracing`
+//! instrumentation can emit `log` records, and a compatibility layer enables
+//! `tracing` [`Subscriber`]s to consume `log` records as `tracing` [`Event`]s.
+//!
+//! ### Emitting `log` Records
+//!
+//! This crate provides two feature flags, "log" and "log-always", which will
+//! cause [spans] and [events] to emit `log` records. When the "log" feature is
+//! enabled, if no `tracing` `Subscriber` is active, invoking an event macro or
+//! creating a span with fields will emit a `log` record. This is intended
+//! primarily for use in libraries which wish to emit diagnostics that can be
+//! consumed by applications using `tracing` *or* `log`, without paying the
+//! additional overhead of emitting both forms of diagnostics when `tracing` is
+//! in use.
+//!
+//! Enabling the "log-always" feature will cause `log` records to be emitted
+//! even if a `tracing` `Subscriber` _is_ set. This is intended to be used in
+//! applications where a `log` `Logger` is being used to record a textual log,
+//! and `tracing` is used only to record other forms of diagnostics (such as
+//! metrics, profiling, or distributed tracing data). Unlike the "log" feature,
+//! libraries generally should **not** enable the "log-always" feature, as doing
+//! so will prevent applications from being able to opt out of the `log` records.
+//!
+//! See [here][flags] for more details on this crate's feature flags.
+//!
+//! The generated `log` records' messages will be a string representation of the
+//! span or event's fields, and all additional information recorded by `log`
+//! (target, verbosity level, module path, file, and line number) will also be
+//! populated. Additionally, `log` records are also generated when spans are
+//! entered, exited, and closed. Since these additional span lifecycle logs have
+//! the potential to be very verbose, and don't include additional fields, they
+//! will always be emitted at the `Trace` level, rather than inheriting the
+//! level of the span that generated them. Furthermore, they are are categorized
+//! under a separate `log` target, "tracing::span" (and its sub-target,
+//! "tracing::span::active", for the logs on entering and exiting a span), which
+//! may be enabled or disabled separately from other `log` records emitted by
+//! `tracing`.
+//!
+//! ### Consuming `log` Records
+//!
+//! The [`tracing-log`] crate provides a compatibility layer which
+//! allows a `tracing` [`Subscriber`] to consume `log` records as though they
+//! were `tracing` [events]. This allows applications using `tracing` to record
+//! the logs emitted by dependencies using `log` as events within the context of
+//! the application's trace tree. See [that crate's documentation][log-tracer]
+//! for details.
+//!
+//! [log-tracer]: https://docs.rs/tracing-log/latest/tracing_log/#convert-log-records-to-tracing-events
+//!
+//! ## Related Crates
+//!
+//! In addition to `tracing` and `tracing-core`, the [`tokio-rs/tracing`] repository
+//! contains several additional crates designed to be used with the `tracing` ecosystem.
+//! This includes a collection of `Subscriber` implementations, as well as utility
+//! and adapter crates to assist in writing `Subscriber`s and instrumenting
+//! applications.
+//!
+//! In particular, the following crates are likely to be of interest:
+//!
+//!  - [`tracing-futures`] provides a compatibility layer with the `futures`
+//!    crate, allowing spans to be attached to `Future`s, `Stream`s, and `Executor`s.
+//!  - [`tracing-subscriber`] provides `Subscriber` implementations and
+//!    utilities for working with `Subscriber`s. This includes a [`FmtSubscriber`]
+//!    `FmtSubscriber` for logging formatted trace data to stdout, with similar
+//!    filtering and formatting to the [`env_logger`] crate.
+//!  - [`tracing-log`] provides a compatibility layer with the [`log`] crate,
+//!    allowing log messages to be recorded as `tracing` `Event`s within the
+//!    trace tree. This is useful when a project using `tracing` have
+//!    dependencies which use `log`. Note that if you're using
+//!    `tracing-subscriber`'s `FmtSubscriber`, you don't need to depend on
+//!    `tracing-log` directly.
+//!  - [`tracing-appender`] provides utilities for outputting tracing data,
+//!     including a file appender and non blocking writer.
+//!
+//! Additionally, there are also several third-party crates which are not
+//! maintained by the `tokio` project. These include:
+//!
+//!  - [`tracing-timing`] implements inter-event timing metrics on top of `tracing`.
+//!    It provides a subscriber that records the time elapsed between pairs of
+//!    `tracing` events and generates histograms.
+//!  - [`tracing-opentelemetry`] provides a subscriber for emitting traces to
+//!    [OpenTelemetry]-compatible distributed tracing systems.
+//!  - [`tracing-honeycomb`] Provides a layer that reports traces spanning multiple machines to [honeycomb.io]. Backed by [`tracing-distributed`].
+//!  - [`tracing-distributed`] Provides a generic implementation of a layer that reports traces spanning multiple machines to some backend.
+//!  - [`tracing-actix-web`] provides `tracing` integration for the `actix-web` web framework.
+//!  - [`tracing-actix`] provides `tracing` integration for the `actix` actor
+//!    framework.
+//!  - [`tracing-gelf`] implements a subscriber for exporting traces in Greylog
+//!    GELF format.
+//!  - [`tracing-coz`] provides integration with the [coz] causal profiler
+//!    (Linux-only).
+//!  - [`tracing-bunyan-formatter`] provides a layer implementation that reports events and spans
+//!    in [bunyan] format, enriched with timing information.
+//!  - [`tracing-wasm`] provides a `Subscriber`/`Layer` implementation that reports
+//!    events and spans via browser `console.log` and [User Timing API (`window.performance`)].
+//!  - [`tracing-web`] provides a layer implementation of level-aware logging of events
+//!    to web browsers' `console.*` and span events to the [User Timing API (`window.performance`)].
+//!  - [`tide-tracing`] provides a [tide] middleware to trace all incoming requests and responses.
+//!  - [`test-log`] takes care of initializing `tracing` for tests, based on
+//!    environment variables with an `env_logger` compatible syntax.
+//!  - [`tracing-unwrap`] provides convenience methods to report failed unwraps
+//!    on `Result` or `Option` types to a `Subscriber`.
+//!  - [`diesel-tracing`] provides integration with [`diesel`] database connections.
+//!  - [`tracing-tracy`] provides a way to collect [Tracy] profiles in instrumented
+//!    applications.
+//!  - [`tracing-elastic-apm`] provides a layer for reporting traces to [Elastic APM].
+//!  - [`tracing-etw`] provides a layer for emitting Windows [ETW] events.
+//!  - [`tracing-fluent-assertions`] provides a fluent assertions-style testing
+//!    framework for validating the behavior of `tracing` spans.
+//!  - [`sentry-tracing`] provides a layer for reporting events and traces to [Sentry].
+//!  - [`tracing-forest`] provides a subscriber that preserves contextual coherence by
+//!    grouping together logs from the same spans during writing.
+//!  - [`tracing-loki`] provides a layer for shipping logs to [Grafana Loki].
+//!  - [`tracing-logfmt`] provides a layer that formats events and spans into the logfmt format.
+//!  - [`reqwest-tracing`] provides a middleware to trace [`reqwest`] HTTP requests.
+//!
+//! If you're the maintainer of a `tracing` ecosystem crate not listed above,
+//! please let us know! We'd love to add your project to the list!
+//!
+//! [`tracing-opentelemetry`]: https://crates.io/crates/tracing-opentelemetry
+//! [OpenTelemetry]: https://opentelemetry.io/
+//! [`tracing-honeycomb`]: https://crates.io/crates/tracing-honeycomb
+//! [`tracing-distributed`]: https://crates.io/crates/tracing-distributed
+//! [honeycomb.io]: https://www.honeycomb.io/
+//! [`tracing-actix-web`]: https://crates.io/crates/tracing-actix-web
+//! [`tracing-actix`]: https://crates.io/crates/tracing-actix
+//! [`tracing-gelf`]: https://crates.io/crates/tracing-gelf
+//! [`tracing-coz`]: https://crates.io/crates/tracing-coz
+//! [coz]: https://github.com/plasma-umass/coz
+//! [`tracing-bunyan-formatter`]: https://crates.io/crates/tracing-bunyan-formatter
+//! [bunyan]: https://github.com/trentm/node-bunyan
+//! [`tracing-wasm`]: https://docs.rs/tracing-wasm
+//! [`tracing-web`]: https://docs.rs/tracing-web
+//! [User Timing API (`window.performance`)]: https://developer.mozilla.org/en-US/docs/Web/API/User_Timing_API
+//! [`tide-tracing`]: https://crates.io/crates/tide-tracing
+//! [tide]: https://crates.io/crates/tide
+//! [`test-log`]: https://crates.io/crates/test-log
+//! [`tracing-unwrap`]: https://docs.rs/tracing-unwrap
+//! [`diesel`]: https://crates.io/crates/diesel
+//! [`diesel-tracing`]: https://crates.io/crates/diesel-tracing
+//! [`tracing-tracy`]: https://crates.io/crates/tracing-tracy
+//! [Tracy]: https://github.com/wolfpld/tracy
+//! [`tracing-elastic-apm`]: https://crates.io/crates/tracing-elastic-apm
+//! [Elastic APM]: https://www.elastic.co/apm
+//! [`tracing-etw`]: https://github.com/microsoft/tracing-etw
+//! [ETW]: https://docs.microsoft.com/en-us/windows/win32/etw/about-event-tracing
+//! [`tracing-fluent-assertions`]: https://crates.io/crates/tracing-fluent-assertions
+//! [`sentry-tracing`]: https://crates.io/crates/sentry-tracing
+//! [Sentry]: https://sentry.io/welcome/
+//! [`tracing-forest`]: https://crates.io/crates/tracing-forest
+//! [`tracing-loki`]: https://crates.io/crates/tracing-loki
+//! [Grafana Loki]: https://grafana.com/oss/loki/
+//! [`tracing-logfmt`]: https://crates.io/crates/tracing-logfmt
+//! [`reqwest-tracing`]: https://crates.io/crates/reqwest-tracing
+//! [`reqwest`]: https://crates.io/crates/reqwest
+//!
+//! <pre class="ignore" style="white-space:normal;font:inherit;">
+//!     <strong>Note</strong>: Some of these ecosystem crates are currently
+//!     unreleased and/or in earlier stages of development. They may be less stable
+//!     than <code>tracing</code> and <code>tracing-core</code>.
+//! </pre>
+//!
+//! ## Crate Feature Flags
+//!
+//! The following crate [feature flags] are available:
+//!
+//! * A set of features controlling the [static verbosity level].
+//! * `log`: causes trace instrumentation points to emit [`log`] records as well
+//!   as trace events, if a default `tracing` subscriber has not been set. This
+//!   is intended for use in libraries whose users may be using either `tracing`
+//!   or `log`.
+//! * `log-always`: Emit `log` records from all `tracing` spans and events, even
+//!   if a `tracing` subscriber has been set. This should be set only by
+//!   applications which intend to collect traces and logs separately; if an
+//!   adapter is used to convert `log` records into `tracing` events, this will
+//!   cause duplicate events to occur.
+//! * `attributes`: Includes support for the `#[instrument]` attribute.
+//!   This is on by default, but does bring in the `syn` crate as a dependency,
+//!   which may add to the compile time of crates that do not already use it.
+//! * `std`: Depend on the Rust standard library (enabled by default).
+//!
+//!   `no_std` users may disable this feature with `default-features = false`:
+//!
+//!   ```toml
+//!   [dependencies]
+//!   tracing = { version = "0.1.37", default-features = false }
+//!   ```
+//!
+//! <pre class="ignore" style="white-space:normal;font:inherit;">
+//!     <strong>Note</strong>: <code>tracing</code>'s <code>no_std</code> support
+//!     requires <code>liballoc</code>.
+//! </pre>
+//!
+//! ### Unstable Features
+//!
+//! These feature flags enable **unstable** features. The public API may break in 0.1.x
+//! releases. To enable these features, the `--cfg tracing_unstable` must be passed to
+//! `rustc` when compiling.
+//!
+//! The following unstable feature flags are currently available:
+//!
+//! * `valuable`: Enables support for recording [field values] using the
+//!   [`valuable`] crate.
+//!
+//! #### Enabling Unstable Features
+//!
+//! The easiest way to set the `tracing_unstable` cfg is to use the `RUSTFLAGS`
+//! env variable when running `cargo` commands:
+//!
+//! ```shell
+//! RUSTFLAGS="--cfg tracing_unstable" cargo build
+//! ```
+//! Alternatively, the following can be added to the `.cargo/config` file in a
+//! project to automatically enable the cfg flag for that project:
+//!
+//! ```toml
+//! [build]
+//! rustflags = ["--cfg", "tracing_unstable"]
+//! ```
+//!
+//! [feature flags]: https://doc.rust-lang.org/cargo/reference/manifest.html#the-features-section
+//! [field values]: crate::field
+//! [`valuable`]: https://crates.io/crates/valuable
+//!
+//! ## Supported Rust Versions
+//!
+//! Tracing is built against the latest stable release. The minimum supported
+//! version is 1.49. The current Tracing version is not guaranteed to build on
+//! Rust versions earlier than the minimum supported version.
+//!
+//! Tracing follows the same compiler support policies as the rest of the Tokio
+//! project. The current stable Rust compiler and the three most recent minor
+//! versions before it will always be supported. For example, if the current
+//! stable compiler version is 1.45, the minimum supported version will not be
+//! increased past 1.42, three minor versions prior. Increasing the minimum
+//! supported compiler version is not considered a semver breaking change as
+//! long as doing so complies with this policy.
+//!
+//! [`log`]: https://docs.rs/log/0.4.6/log/
+//! [span]: mod@span
+//! [spans]: mod@span
+//! [`Span`]: span::Span
+//! [`in_scope`]: span::Span::in_scope
+//! [event]: Event
+//! [events]: Event
+//! [`Subscriber`]: subscriber::Subscriber
+//! [Subscriber::event]: subscriber::Subscriber::event
+//! [`enter`]: subscriber::Subscriber::enter
+//! [`exit`]: subscriber::Subscriber::exit
+//! [`enabled`]: subscriber::Subscriber::enabled
+//! [metadata]: Metadata
+//! [`field::display`]: field::display
+//! [`field::debug`]: field::debug
+//! [`set_global_default`]: subscriber::set_global_default
+//! [`with_default`]: subscriber::with_default
+//! [`tokio-rs/tracing`]: https://github.com/tokio-rs/tracing
+//! [`tracing-futures`]: https://crates.io/crates/tracing-futures
+//! [`tracing-subscriber`]: https://crates.io/crates/tracing-subscriber
+//! [`tracing-log`]: https://crates.io/crates/tracing-log
+//! [`tracing-timing`]: https://crates.io/crates/tracing-timing
+//! [`tracing-appender`]: https://crates.io/crates/tracing-appender
+//! [`env_logger`]: https://crates.io/crates/env_logger
+//! [`FmtSubscriber`]: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/fmt/struct.Subscriber.html
+//! [static verbosity level]: level_filters#compile-time-filters
+//! [instrument]: https://docs.rs/tracing-attributes/latest/tracing_attributes/attr.instrument.html
+//! [flags]: #crate-feature-flags
+#![cfg_attr(not(feature = "std"), no_std)]
+#![cfg_attr(docsrs, feature(doc_cfg), deny(rustdoc::broken_intra_doc_links))]
+#![doc(html_root_url = "https://docs.rs/tracing/0.1.37")]
+#![doc(
+    html_logo_url = "https://raw.githubusercontent.com/tokio-rs/tracing/master/assets/logo-type.png",
+    issue_tracker_base_url = "https://github.com/tokio-rs/tracing/issues/"
+)]
+#![warn(
+    missing_debug_implementations,
+    missing_docs,
+    rust_2018_idioms,
+    unreachable_pub,
+    bad_style,
+    const_err,
+    dead_code,
+    improper_ctypes,
+    non_shorthand_field_patterns,
+    no_mangle_generic_items,
+    overflowing_literals,
+    path_statements,
+    patterns_in_fns_without_body,
+    private_in_public,
+    unconditional_recursion,
+    unused,
+    unused_allocation,
+    unused_comparisons,
+    unused_parens,
+    while_true
+)]
+
+#[cfg(not(feature = "std"))]
+extern crate alloc;
+
+// Somehow this `use` statement is necessary for us to re-export the `core`
+// macros on Rust 1.26.0. I'm not sure how this makes it work, but it does.
+#[allow(unused_imports)]
+#[doc(hidden)]
+use tracing_core::*;
+
+#[doc(inline)]
+pub use self::instrument::Instrument;
+pub use self::{dispatcher::Dispatch, event::Event, field::Value, subscriber::Subscriber};
+
+#[doc(hidden)]
+pub use self::span::Id;
+
+#[doc(hidden)]
+pub use tracing_core::{
+    callsite::{self, Callsite},
+    metadata,
+};
+pub use tracing_core::{event, Level, Metadata};
+
+#[doc(inline)]
+pub use self::span::Span;
+#[cfg(feature = "attributes")]
+#[cfg_attr(docsrs, doc(cfg(feature = "attributes")))]
+#[doc(inline)]
+pub use tracing_attributes::instrument;
+
+#[macro_use]
+mod macros;
+
+pub mod dispatcher;
+pub mod field;
+/// Attach a span to a `std::future::Future`.
+pub mod instrument;
+pub mod level_filters;
+pub mod span;
+pub(crate) mod stdlib;
+pub mod subscriber;
+
+#[doc(hidden)]
+pub mod __macro_support {
+    pub use crate::callsite::Callsite;
+    use crate::{subscriber::Interest, Metadata};
+    pub use core::concat;
+
+    /// Callsite implementation used by macro-generated code.
+    ///
+    /// /!\ WARNING: This is *not* a stable API! /!\
+    /// This type, and all code contained in the `__macro_support` module, is
+    /// a *private* API of `tracing`. It is exposed publicly because it is used
+    /// by the `tracing` macros, but it is not part of the stable versioned API.
+    /// Breaking changes to this module may occur in small-numbered versions
+    /// without warning.
+    pub use tracing_core::callsite::DefaultCallsite as MacroCallsite;
+
+    /// /!\ WARNING: This is *not* a stable API! /!\
+    /// This function, and all code contained in the `__macro_support` module, is
+    /// a *private* API of `tracing`. It is exposed publicly because it is used
+    /// by the `tracing` macros, but it is not part of the stable versioned API.
+    /// Breaking changes to this module may occur in small-numbered versions
+    /// without warning.
+    pub fn __is_enabled(meta: &Metadata<'static>, interest: Interest) -> bool {
+        interest.is_always() || crate::dispatcher::get_default(|default| default.enabled(meta))
+    }
+
+    /// /!\ WARNING: This is *not* a stable API! /!\
+    /// This function, and all code contained in the `__macro_support` module, is
+    /// a *private* API of `tracing`. It is exposed publicly because it is used
+    /// by the `tracing` macros, but it is not part of the stable versioned API.
+    /// Breaking changes to this module may occur in small-numbered versions
+    /// without warning.
+    #[inline]
+    #[cfg(feature = "log")]
+    pub fn __disabled_span(meta: &'static Metadata<'static>) -> crate::Span {
+        crate::Span::new_disabled(meta)
+    }
+
+    /// /!\ WARNING: This is *not* a stable API! /!\
+    /// This function, and all code contained in the `__macro_support` module, is
+    /// a *private* API of `tracing`. It is exposed publicly because it is used
+    /// by the `tracing` macros, but it is not part of the stable versioned API.
+    /// Breaking changes to this module may occur in small-numbered versions
+    /// without warning.
+    #[inline]
+    #[cfg(not(feature = "log"))]
+    pub fn __disabled_span(_: &'static Metadata<'static>) -> crate::Span {
+        crate::Span::none()
+    }
+
+    /// /!\ WARNING: This is *not* a stable API! /!\
+    /// This function, and all code contained in the `__macro_support` module, is
+    /// a *private* API of `tracing`. It is exposed publicly because it is used
+    /// by the `tracing` macros, but it is not part of the stable versioned API.
+    /// Breaking changes to this module may occur in small-numbered versions
+    /// without warning.
+    #[cfg(feature = "log")]
+    pub fn __tracing_log(
+        meta: &Metadata<'static>,
+        logger: &'static dyn log::Log,
+        log_meta: log::Metadata<'_>,
+        values: &tracing_core::field::ValueSet<'_>,
+    ) {
+        logger.log(
+            &crate::log::Record::builder()
+                .file(meta.file())
+                .module_path(meta.module_path())
+                .line(meta.line())
+                .metadata(log_meta)
+                .args(format_args!(
+                    "{}",
+                    crate::log::LogValueSet {
+                        values,
+                        is_first: true
+                    }
+                ))
+                .build(),
+        );
+    }
+}
+
+#[cfg(feature = "log")]
+#[doc(hidden)]
+pub mod log {
+    use core::fmt;
+    pub use log::*;
+    use tracing_core::field::{Field, ValueSet, Visit};
+
+    /// Utility to format [`ValueSet`]s for logging.
+    pub(crate) struct LogValueSet<'a> {
+        pub(crate) values: &'a ValueSet<'a>,
+        pub(crate) is_first: bool,
+    }
+
+    impl<'a> fmt::Display for LogValueSet<'a> {
+        #[inline]
+        fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+            struct LogVisitor<'a, 'b> {
+                f: &'a mut fmt::Formatter<'b>,
+                is_first: bool,
+                result: fmt::Result,
+            }
+
+            impl Visit for LogVisitor<'_, '_> {
+                fn record_debug(&mut self, field: &Field, value: &dyn fmt::Debug) {
+                    let res = if self.is_first {
+                        self.is_first = false;
+                        if field.name() == "message" {
+                            write!(self.f, "{:?}", value)
+                        } else {
+                            write!(self.f, "{}={:?}", field.name(), value)
+                        }
+                    } else {
+                        write!(self.f, " {}={:?}", field.name(), value)
+                    };
+                    if let Err(err) = res {
+                        self.result = self.result.and(Err(err));
+                    }
+                }
+
+                fn record_str(&mut self, field: &Field, value: &str) {
+                    if field.name() == "message" {
+                        self.record_debug(field, &format_args!("{}", value))
+                    } else {
+                        self.record_debug(field, &value)
+                    }
+                }
+            }
+
+            let mut visit = LogVisitor {
+                f,
+                is_first: self.is_first,
+                result: Ok(()),
+            };
+            self.values.record(&mut visit);
+            visit.result
+        }
+    }
+}
+
+mod sealed {
+    pub trait Sealed {}
+}