Crate tracing_serde
source · [−]Expand description
tracing-serde
An adapter for serializing tracing
types using serde
.
Overview
tracing
is a framework for instrumenting Rust programs to collect
scoped, structured, and async-aware diagnostics.tracing-serde
enables
serializing tracing
types using serde
.
Traditional logging is based on human-readable text messages.
tracing
gives us machine-readable structured diagnostic
information. This lets us interact with diagnostic data
programmatically. With tracing-serde
, you can implement a
Subscriber
to serialize your tracing
types and make use of the
existing ecosystem of serde
serializers to talk with distributed
tracing systems.
Serializing diagnostic information allows us to do more with our logged values. For instance, when working with logging data in JSON gives us pretty-print when we’re debugging in development and you can emit JSON and tracing data to monitor your services in production.
The tracing
crate provides the APIs necessary for instrumenting
libraries and applications to emit trace data.
Compiler support: requires rustc
1.42+
Usage
First, add this to your Cargo.toml
:
[dependencies]
tracing = "0.1"
tracing-serde = "0.1"
Next, add this to your crate:
use tracing_serde::AsSerde;
Please read the tracing
documentation
for more information on how to create trace data.
This crate provides the as_serde
function, via the AsSerde
trait,
which enables serializing the Attributes
, Event
, Id
, Metadata
,
and Record
tracing
values.
For the full example, please see the examples folder.
Implement a Subscriber
to format the serialization of tracing
types how you’d like.
use tracing_serde::AsSerde;
use serde_json::json;
pub struct JsonSubscriber {
next_id: AtomicUsize, // you need to assign span IDs, so you need a counter
}
impl Subscriber for JsonSubscriber {
fn new_span(&self, attrs: &Attributes<'_>) -> Id {
let id = self.next_id.fetch_add(1, Ordering::Relaxed);
let id = Id::from_u64(id as u64);
let json = json!({
"new_span": {
"attributes": attrs.as_serde(),
"id": id.as_serde(),
}});
println!("{}", json);
id
}
fn event(&self, event: &Event<'_>) {
let json = json!({
"event": event.as_serde(),
});
println!("{}", json);
}
// ...
}
After you implement your Subscriber
, you can use your tracing
subscriber (JsonSubscriber
in the above example) to record serialized
trace data.
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 [Visit::record_value
] implementations, for serializing values recorded using thevaluable
crate.
Enabling Unstable Features
The easiest way to set the tracing_unstable
cfg is to use the RUSTFLAGS
env variable when running cargo
commands:
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:
[build]
rustflags = ["--cfg", "tracing_unstable"]
Supported Rust Versions
Tracing is built against the latest stable release. The minimum supported version is 1.42. 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.
Modules
Support for serializing fields as serde
structs or maps.
Structs
Implements tracing_core::field::Visit
for some serde::ser::SerializeMap
.
Implements tracing_core::field::Visit
for some serde::ser::SerializeStruct
.
Implements serde::Serialize
to write Attributes
data to a serializer.
Implements serde::Serialize
to write Event
data to a serializer.
Implements serde::Serialize
to write Record
data to a serializer.