Announcing Experimental valuable Support

[hawkw]

Hi everyone!

Today we're excited to announce the release of tracing-core v0.1.22, which introduces experimental support for the valuable crate in tracing!

For a long time, many people have wanted a way to record both user-defined types, and standard library collections such as Vec and HashMap, as structured data attached to tracing spans and events. The current design of the tracing::Value trait is not flexible enough to represent this kind of data, but adding support for arbitrary user-defined types has been a goal since day one.

A lot of approaches have been considered, such as extending the tracing::Value system to add support for serde (#819) and making dyn std::any::Any a primitive Value type (#905). Unfortunately, while serde is a great library, it has some limitations that make it difficult to use in tracing; primarily around object safety.

Enter valuable. valuable is a library providing object-safe inspection of structured values. Unlike serde, it was designed specifically for use-cases like tracing's, while remaining compatible with serde for serialization.

Our long term goal is to replace most of tracing's current Value system with valuable in tracing 0.2.x. However, before we can do that, we need to actually experiment with using the valuable APIs in practice. The recent tracing v0.1.30 and tracing-core v0.1.22 have backwards-compatible support for valuable in addition to the existing tracing::Value trait. We're hoping you'll help try out using valuable with tracing and share your experiences so we can refine the design for v0.2!

How it Works

For details on how valuable itself works, refer to this post on the Tokio blog.

The valuable support in tracing v0.1.x works by adding a new Visit::record_value method to the tracing::field::Visit trait, to record a valuable::Value. If a Visit implementation provides this method, it can record those values using valuable. Otherwise, if the visitor does not implement record_value, it will fall back to recording the Value using fmt::Debug as normal.

To record your types using valuable, derive the valuable::Valuable trait, and record them by calling Valuable::as_value:

use valuable::Valuable;

#[derive(Debug, Valuable)]
pub struct MyType {
    // ...
};

let my_value = MyType {
    // ...
};

tracing::info!(my_value = my_value.as_value());

See the documentation and examples for more information.

Enabling Experimental Features

Note that the valuable support is currently an experimental feature. This means that breaking changes to valuable are not considered breaking changes to the tracing API. Therefore, you must opt in to using the valuable support by both enabling the "valuable" feature flag and enabling the "tracing_unstable" cfg flag, such as by building with

RUSTFLAGS="--cfg tracing_unstable" cargo build

See the documentation on unstable features for more information.

Crates With valuable Support

Currently, the following crates offer some experimental support for valuable

• tracing-core v0.1.22
• tracing v0.1.30
• tracing-subscriber v0.3.8 supports recording valuable::Valuable fields as structured JSON with the JSON formatter
• tracing-serde v0.1.3 supports serializing valuable::Valuable fields using the [valuable-serde] crate

We'd Love To Hear Your Thoughts!

Since this is an experimental feature, we'd love to hear your thoughts and experiences with the new valuable support in tracing! Please try it out and feel free to leave a comment in this thread with any questions and thoughts you may have. Also, you can join us on Discord, and open new issues for any bugs you find or new features you'd like to see.

Thanks!

[dlight]

Hello, it's been more than two years since this was announced with experimental status. Are there any blockers preventing this feature being stabilized?

Or otherwise, is there any discussion about this feature somewhere else?

[teohhanhui]

Would you consider adding a sigil for recording the field using its Valuable implementation?

Similar to ? for Debug and % for Display:
https://docs.rs/tracing/latest/tracing/#recording-fields

There's a similar request for pretty-printing: #1752 #1311

[davidbarsky]

We probably would need a sigil for Valuable, yes.

[teohhanhui]

Valuable sounds like it should be $ (pun intended lol)

[mladedav]

Sadly, the character $ cannot be matched or transcribed literally.

[fosskers]

We have hit something of a bug recently: #3051

[nastynaz]

How can I implement Valuable for my own structs such that it will register Duration/Instant fields by calling .as_secs_f32() on them? I looked through the examples and documentation but I'm too dumb to figure it out.

[xujihui1985]

Hi team, are there any updates on the valuable feature?
It’s been three years since it was announced, yet it is still marked experimental.
This capability would be extremely helpful when I need to build a custom layer to collect metrics.
Instead of writing
tracing::info!(metrics.http_duration = xx, metrics.count = xxx),
I could bundle them in a single Valuable object:
tracing::info!(metrics = metrics.as_value()).

Are there any blockers keeping this feature from being stabilized?

[xujihui1985]

@hawkw can we remain opt-in via a crate feature flag, but it shouldn’t require cfg(tracing_unstable). Having it gated by an “unstable” cfg can discourage users from adopting it, even if the functionality is already reliable.

[felix-1-money]

Just like @nastynaz, there should be an example of implementing the trait by hand. It's the pain to figure it out.