third_party/rust/tracing-core/README.md

   1 ![Tracing — Structured, application-level diagnostics][splash]
   2
   3 [splash]: https://raw.githubusercontent.com/tokio-rs/tracing/master/assets/splash.svg
   4
   5 # tracing-core
   6
   7 Core primitives for application-level tracing.
   8
   9 [![Crates.io][crates-badge]][crates-url]
  10 [![Documentation][docs-badge]][docs-url]
  11 [![Documentation (master)][docs-master-badge]][docs-master-url]
  12 [![MIT licensed][mit-badge]][mit-url]
  13 [![Build Status][actions-badge]][actions-url]
  14 [![Discord chat][discord-badge]][discord-url]
  15
  16 [Documentation][docs-url] | [Chat][discord-url]
  17
  18 [crates-badge]: https://img.shields.io/crates/v/tracing-core.svg
  19 [crates-url]: https://crates.io/crates/tracing-core/0.1.30
  20 [docs-badge]: https://docs.rs/tracing-core/badge.svg
  21 [docs-url]: https://docs.rs/tracing-core/0.1.30
  22 [docs-master-badge]: https://img.shields.io/badge/docs-master-blue
  23 [docs-master-url]: https://tracing-rs.netlify.com/tracing_core
  24 [mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg
  25 [mit-url]: LICENSE
  26 [actions-badge]: https://github.com/tokio-rs/tracing/workflows/CI/badge.svg
  27 [actions-url]:https://github.com/tokio-rs/tracing/actions?query=workflow%3ACI
  28 [discord-badge]: https://img.shields.io/discord/500028886025895936?logo=discord&label=discord&logoColor=white
  29 [discord-url]: https://discord.gg/EeF3cQw
  30
  31 ## Overview
  32
  33 [`tracing`] is a framework for instrumenting Rust programs to collect
  34 structured, event-based diagnostic information. This crate defines the core
  35 primitives of `tracing`.
  36
  37 The crate provides:
  38
  39 * [`span::Id`] identifies a span within the execution of a program.
  40
  41 * [`Event`] represents a single event within a trace.
  42
  43 * [`Subscriber`], the trait implemented to collect trace data.
  44
  45 * [`Metadata`] and [`Callsite`] provide information describing spans and
  46   events.
  47
  48 * [`Field`], [`FieldSet`], [`Value`], and [`ValueSet`] represent the
  49   structured data attached to spans and events.
  50
  51 * [`Dispatch`] allows spans and events to be dispatched to `Subscriber`s.
  52
  53 In addition, it defines the global callsite registry and per-thread current
  54 dispatcher which other components of the tracing system rely on.
  55
  56 *Compiler support: [requires `rustc` 1.49+][msrv]*
  57
  58 [msrv]: #supported-rust-versions
  59
  60 ## Usage
  61
  62 Application authors will typically not use this crate directly. Instead, they
  63 will use the [`tracing`] crate, which provides a much more fully-featured
  64 API. However, this crate's API will change very infrequently, so it may be used
  65 when dependencies must be very stable.
  66
  67 `Subscriber` implementations may depend on `tracing-core` rather than `tracing`,
  68 as the additional APIs provided by `tracing` are primarily useful for
  69 instrumenting libraries and applications, and are generally not necessary for
  70 `Subscriber` implementations.
  71
  72 ###  Crate Feature Flags
  73
  74 The following crate feature flags are available:
  75
  76 * `std`: Depend on the Rust standard library (enabled by default).
  77
  78   `no_std` users may disable this feature with `default-features = false`:
  79
  80   ```toml
  81   [dependencies]
  82   tracing-core = { version = "0.1.30", default-features = false }
  83   ```
  84
  85   **Note**:`tracing-core`'s `no_std` support requires `liballoc`.
  86
  87 [`tracing`]: ../tracing
  88 [`span::Id`]: https://docs.rs/tracing-core/0.1.30/tracing_core/span/struct.Id.html
  89 [`Event`]: https://docs.rs/tracing-core/0.1.30/tracing_core/event/struct.Event.html
  90 [`Subscriber`]: https://docs.rs/tracing-core/0.1.30/tracing_core/subscriber/trait.Subscriber.html
  91 [`Metadata`]: https://docs.rs/tracing-core/0.1.30/tracing_core/metadata/struct.Metadata.html
  92 [`Callsite`]: https://docs.rs/tracing-core/0.1.30/tracing_core/callsite/trait.Callsite.html
  93 [`Field`]: https://docs.rs/tracing-core/0.1.30/tracing_core/field/struct.Field.html
  94 [`FieldSet`]: https://docs.rs/tracing-core/0.1.30/tracing_core/field/struct.FieldSet.html
  95 [`Value`]: https://docs.rs/tracing-core/0.1.30/tracing_core/field/trait.Value.html
  96 [`ValueSet`]: https://docs.rs/tracing-core/0.1.30/tracing_core/field/struct.ValueSet.html
  97 [`Dispatch`]: https://docs.rs/tracing-core/0.1.30/tracing_core/dispatcher/struct.Dispatch.html
  98
  99 ## Supported Rust Versions
 100
 101 Tracing is built against the latest stable release. The minimum supported
 102 version is 1.49. The current Tracing version is not guaranteed to build on Rust
 103 versions earlier than the minimum supported version.
 104
 105 Tracing follows the same compiler support policies as the rest of the Tokio
 106 project. The current stable Rust compiler and the three most recent minor
 107 versions before it will always be supported. For example, if the current stable
 108 compiler version is 1.45, the minimum supported version will not be increased
 109 past 1.42, three minor versions prior. Increasing the minimum supported compiler
 110 version is not considered a semver breaking change as long as doing so complies
 111 with this policy.
 112
 113 ## License
 114
 115 This project is licensed under the [MIT license](LICENSE).
 116
 117 ### Contribution
 118
 119 Unless you explicitly state otherwise, any contribution intentionally submitted
 120 for inclusion in Tokio by you, shall be licensed as MIT, without any additional
 121 terms or conditions.