| callsite.rs |
|
23258 |
| dispatcher.rs |
|
34190 |
| event.rs |
Events represent single points in time during the execution of a program. |
4402 |
| field.rs |
`Span` and `Event` key-value data.
Spans and events may be annotated with key-value data, referred to as known
as _fields_. These fields consist of a mapping from a key (corresponding to
a `&str` but represented internally as an array index) to a [`Value`].
# `Value`s and `Subscriber`s
`Subscriber`s consume `Value`s as fields attached to [span]s or [`Event`]s.
The set of field keys on a given span or is defined on its [`Metadata`].
When a span is created, it provides [`Attributes`] to the `Subscriber`'s
[`new_span`] method, containing any fields whose values were provided when
the span was created; and may call the `Subscriber`'s [`record`] method
with additional [`Record`]s if values are added for more of its fields.
Similarly, the [`Event`] type passed to the subscriber's [`event`] method
will contain any fields attached to each event.
`tracing` represents values as either one of a set of Rust primitives
(`i64`, `u64`, `f64`, `i128`, `u128`, `bool`, and `&str`) or using a
`fmt::Display` or `fmt::Debug` implementation. `Subscriber`s are provided
these primitive value types as `dyn Value` trait objects.
These trait objects can be formatted using `fmt::Debug`, but may also be
recorded as typed data by calling the [`Value::record`] method on these
trait objects with a _visitor_ implementing the [`Visit`] trait. This trait
represents the behavior used to record values of various types. For example,
an implementation of `Visit` might record integers by incrementing counters
for their field names rather than printing them.
# Using `valuable`
`tracing`'s [`Value`] trait is intentionally minimalist: it supports only a small
number of Rust primitives as typed values, and only permits recording
user-defined types with their [`fmt::Debug`] or [`fmt::Display`]
implementations. However, there are some cases where it may be useful to record
nested values (such as arrays, `Vec`s, or `HashMap`s containing values), or
user-defined `struct` and `enum` types without having to format them as
unstructured text.
To address `Value`'s limitations, `tracing` offers experimental support for
the [`valuable`] crate, which provides object-safe inspection of structured
values. User-defined types can implement the [`valuable::Valuable`] trait,
and be recorded as a `tracing` field by calling their [`as_value`] method.
If the [`Subscriber`] also supports the `valuable` crate, it can
then visit those types fields as structured values using `valuable`.
<pre class="ignore" style="white-space:normal;font:inherit;">
<strong>Note</strong>: <code>valuable</code> support is an
<a href = "../index.html#unstable-features">unstable feature</a>. See
the documentation on unstable features for details on how to enable it.
</pre>
For example:
```ignore
// Derive `Valuable` for our types:
use valuable::Valuable;
#[derive(Clone, Debug, Valuable)]
struct User {
name: String,
age: u32,
address: Address,
}
#[derive(Clone, Debug, Valuable)]
struct Address {
country: String,
city: String,
street: String,
}
let user = User {
name: "Arwen Undomiel".to_string(),
age: 3000,
address: Address {
country: "Middle Earth".to_string(),
city: "Rivendell".to_string(),
street: "leafy lane".to_string(),
},
};
// Recording `user` as a `valuable::Value` will allow the `tracing` subscriber
// to traverse its fields as a nested, typed structure:
tracing::info!(current_user = user.as_value());
```
Alternatively, the [`valuable()`] function may be used to convert a type
implementing [`Valuable`] into a `tracing` field value.
When the `valuable` feature is enabled, the [`Visit`] trait will include an
optional [`record_value`] method. `Visit` implementations that wish to
record `valuable` values can implement this method with custom behavior.
If a visitor does not implement `record_value`, the [`valuable::Value`] will
be forwarded to the visitor's [`record_debug`] method.
[`valuable`]: https://crates.io/crates/valuable
[`as_value`]: valuable::Valuable::as_value
[`Subscriber`]: crate::Subscriber
[`record_value`]: Visit::record_value
[`record_debug`]: Visit::record_debug
[span]: super::span
[`Event`]: super::event::Event
[`Metadata`]: super::metadata::Metadata
[`Attributes`]: super::span::Attributes
[`Record`]: super::span::Record
[`new_span`]: super::subscriber::Subscriber::new_span
[`record`]: super::subscriber::Subscriber::record
[`event`]: super::subscriber::Subscriber::event
[`Value::record`]: Value::record |
40032 |
| lazy.rs |
|
2521 |
| lib.rs |
Core primitives for `tracing`.
[`tracing`] is a framework for instrumenting Rust programs to collect
structured, event-based diagnostic information. This crate defines the core
primitives of `tracing`.
This crate provides:
* [`span::Id`] identifies a span within the execution of a program.
* [`Event`] represents a single event within a trace.
* [`Subscriber`], the trait implemented to collect trace data.
* [`Metadata`] and [`Callsite`] provide information describing spans and
`Event`s.
* [`Field`], [`FieldSet`], [`Value`], and [`ValueSet`] represent the
structured data attached to a span.
* [`Dispatch`] allows spans and events to be dispatched to `Subscriber`s.
In addition, it defines the global callsite registry and per-thread current
dispatcher which other components of the tracing system rely on.
*Compiler support: [requires `rustc` 1.49+][msrv]*
[msrv]: #supported-rust-versions
## Usage
Application authors will typically not use this crate directly. Instead,
they will use the [`tracing`] crate, which provides a much more
fully-featured API. However, this crate's API will change very infrequently,
so it may be used when dependencies must be very stable.
`Subscriber` implementations may depend on `tracing-core` rather than
`tracing`, as the additional APIs provided by `tracing` are primarily useful
for instrumenting libraries and applications, and are generally not
necessary for `Subscriber` implementations.
The [`tokio-rs/tracing`] repository contains less stable crates designed to
be used with the `tracing` ecosystem. It includes a collection of
`Subscriber` implementations, as well as utility and adapter crates.
## Crate Feature Flags
The following crate [feature flags] are available:
* `std`: Depend on the Rust standard library (enabled by default).
`no_std` users may disable this feature with `default-features = false`:
```toml
[dependencies]
tracing-core = { version = "0.1.22", default-features = false }
```
**Note**:`tracing-core`'s `no_std` support requires `liballoc`.
### 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.
[`span::Id`]: span::Id
[`Event`]: event::Event
[`Subscriber`]: subscriber::Subscriber
[`Metadata`]: metadata::Metadata
[`Callsite`]: callsite::Callsite
[`Field`]: field::Field
[`FieldSet`]: field::FieldSet
[`Value`]: field::Value
[`ValueSet`]: field::ValueSet
[`Dispatch`]: dispatcher::Dispatch
[`tokio-rs/tracing`]: https://github.com/tokio-rs/tracing
[`tracing`]: https://crates.io/crates/tracing |
8980 |
| metadata.rs |
Metadata describing trace data. |
39506 |
| parent.rs |
|
263 |
| span.rs |
Spans represent periods of time in the execution of a program. |
10498 |
| spin |
|
|
| stdlib.rs |
Re-exports either the Rust `std` library or `core` and `alloc` when `std` is
disabled.
`crate::stdlib::...` should be used rather than `std::` when adding code that
will be available with the standard library disabled.
Note that this module is called `stdlib` rather than `std`, as Rust 1.34.0
does not permit redefining the name `stdlib` (although this works on the
latest stable Rust). |
2488 |
| subscriber.rs |
Collectors collect and record trace data. |
35446 |