]>
Commit | Line | Data |
---|---|---|
3dfed10e | 1 | ![Tracing — Structured, application-level diagnostics][splash] |
1b1a35ee | 2 | |
3dfed10e XL |
3 | [splash]: https://raw.githubusercontent.com/tokio-rs/tracing/master/assets/splash.svg |
4 | ||
f035d41b XL |
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 | |
2b03887a | 19 | [crates-url]: https://crates.io/crates/tracing-core/0.1.30 |
f035d41b | 20 | [docs-badge]: https://docs.rs/tracing-core/badge.svg |
2b03887a | 21 | [docs-url]: https://docs.rs/tracing-core/0.1.30 |
f035d41b XL |
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 | ||
5e7ed085 | 56 | *Compiler support: [requires `rustc` 1.49+][msrv]* |
1b1a35ee XL |
57 | |
58 | [msrv]: #supported-rust-versions | |
f035d41b | 59 | |
1b1a35ee XL |
60 | ## Usage |
61 | ||
f035d41b XL |
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 | ||
1b1a35ee | 78 | `no_std` users may disable this feature with `default-features = false`: |
f035d41b XL |
79 | |
80 | ```toml | |
81 | [dependencies] | |
2b03887a | 82 | tracing-core = { version = "0.1.30", default-features = false } |
f035d41b XL |
83 | ``` |
84 | ||
f035d41b XL |
85 | **Note**:`tracing-core`'s `no_std` support requires `liballoc`. |
86 | ||
87 | [`tracing`]: ../tracing | |
2b03887a FG |
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 | |
1b1a35ee XL |
98 | |
99 | ## Supported Rust Versions | |
100 | ||
101 | Tracing is built against the latest stable release. The minimum supported | |
5e7ed085 | 102 | version is 1.49. The current Tracing version is not guaranteed to build on Rust |
1b1a35ee XL |
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. | |
f035d41b XL |
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. |