Module field

Span and Event key-value data.

Spans and events may be annotated with key-value data, referred to 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.

Values and Subscribers

Subscribers consume Values as fields attached to spans or Events. The set of field keys on a given span or event 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 Records 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. Subscribers 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, Vecs, or HashMaps 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

• DebugValue
  A Value which serializes as a string using fmt::Debug.
• DisplayValue
  A Value which serializes using fmt::Display.
• Empty
  An empty field.
• Field
  An opaque key allowing O(1) access to a field in a Span’s key-value data.
• FieldSet
  Describes the fields present on a span.
• Iter
  An iterator over a set of fields.
• ValueSet
  A set of fields and values for a span.

Traits

• AsField
  Trait implemented to allow a type to be used as a field key.
• Value
  A field value of an erased type.
• Visit
  Visits typed values.

Functions

• debug
  Wraps a type implementing fmt::Debug as a Value that can be recorded using its Debug implementation.
• display
  Wraps a type implementing fmt::Display as a Value that can be recorded using its Display implementation.
• valuable
  Wraps a type implementing Valuable as a Value that can be recorded using its Valuable implementation.