Module polkadot_node_subsystem::gen::tracing::field
source · Expand description
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 spans 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
, 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
.
Note: valuable
support is an
unstable feature. See
the documentation on unstable features for details on how to enable it.
For example:
// 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.
Structs
- A
Value
which serializes as a string usingfmt::Debug
. - A
Value
which serializes usingfmt::Display
. - An empty field.
- An opaque key allowing O(1) access to a field in a
Span
’s key-value data. - Describes the fields present on a span.
- An iterator over a set of fields.
- A set of fields and values for a span.
Traits
- Trait implemented to allow a type to be used as a field key.
- A field value of an erased type.
- Visits typed values.
Functions
- Wraps a type implementing
fmt::Debug
as aValue
that can be recorded using itsDebug
implementation. - Wraps a type implementing
fmt::Display
as aValue
that can be recorded using itsDisplay
implementation.