<p>Spans and events may be annotated with key-value data, referred to as <em>fields</em>.
These fields consist of a mapping from a key (corresponding to
a <code>&str</code> but represented internally as an array index) to a <ahref="../trait.Value.html"title="trait tracing::Value"><code>Value</code></a>.</p>
<p><code>Subscriber</code>s consume <code>Value</code>s as fields attached to <ahref="../span/index.html"title="mod tracing::span">span</a>s or <ahref="../event/struct.Event.html"title="struct tracing::event::Event"><code>Event</code></a>s.
The set of field keys on a given span or event is defined on its <ahref="../struct.Metadata.html"title="struct tracing::Metadata"><code>Metadata</code></a>.
When a span is created, it provides <ahref="../span/struct.Attributes.html"title="struct tracing::span::Attributes"><code>Attributes</code></a> to the <code>Subscriber</code>’s
<ahref="../trait.Subscriber.html#tymethod.new_span"title="method tracing::Subscriber::new_span"><code>new_span</code></a> method, containing any fields whose values were provided when
the span was created; and may call the <code>Subscriber</code>’s <ahref="../span/struct.Record.html"title="struct tracing::span::Record"><code>record</code></a> method
with additional <ahref="../span/struct.Record.html"title="struct tracing::span::Record"><code>Record</code></a>s if values are added for more of its fields.
Similarly, the <ahref="../event/struct.Event.html"title="struct tracing::event::Event"><code>Event</code></a> type passed to the subscriber’s <ahref="../event/struct.Event.html"title="struct tracing::event::Event"><code>event</code></a> method
will contain any fields attached to each event.</p>
<p><code>tracing</code> represents values as either one of a set of Rust primitives
(<code>i64</code>, <code>u64</code>, <code>f64</code>, <code>bool</code>, and <code>&str</code>) or using a <code>fmt::Display</code> or
<code>fmt::Debug</code> implementation. <code>Subscriber</code>s are provided these primitive
value types as <code>dyn Value</code> trait objects.</p>
<p>These trait objects can be formatted using <code>fmt::Debug</code>, but may also be
recorded as typed data by calling the <ahref="../trait.Value.html#tymethod.record"title="method tracing::Value::record"><code>Value::record</code></a> method on these
trait objects with a <em>visitor</em> implementing the <ahref="trait.Visit.html"title="trait tracing::field::Visit"><code>Visit</code></a> trait. This trait
represents the behavior used to record values of various types. For example,
an implementation of <code>Visit</code> might record integers by incrementing counters
for their field names rather than printing them.</p>
<p><code>tracing</code>’s <ahref="../trait.Value.html"title="trait tracing::Value"><code>Value</code></a> 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 <ahref="https://doc.rust-lang.org/1.80.0/core/fmt/trait.Debug.html"title="trait core::fmt::Debug"><code>fmt::Debug</code></a> or <ahref="https://doc.rust-lang.org/1.80.0/core/fmt/trait.Debug.html"title="trait core::fmt::Debug"><code>fmt::Display</code></a>
implementations. However, there are some cases where it may be useful to record
nested values (such as arrays, <code>Vec</code>s, or <code>HashMap</code>s containing values), or
user-defined <code>struct</code> and <code>enum</code> types without having to format them as
unstructured text.</p>
<p>To address <code>Value</code>’s limitations, <code>tracing</code> offers experimental support for
the <ahref="https://crates.io/crates/valuable"><code>valuable</code></a> crate, which provides object-safe inspection of structured
values. User-defined types can implement the <ahref="https://docs.rs/valuable/latest/valuable/trait.Valuable.html"><code>valuable::Valuable</code></a> trait,
and be recorded as a <code>tracing</code> field by calling their <ahref="https://docs.rs/valuable/latest/valuable/trait.Valuable.html#tymethod.as_value"><code>as_value</code></a> method.
If the <ahref="../trait.Subscriber.html"title="trait tracing::Subscriber"><code>Subscriber</code></a> also supports the <code>valuable</code> crate, it can
then visit those types fields as structured values using <code>valuable</code>.</p>
<strong>Note</strong>: <code>valuable</code> support is an
<ahref ="../index.html#unstable-features">unstable feature</a>. See
the documentation on unstable features for details on how to enable it.
</pre>
<p>For example:</p>
<divclass="example-wrap ignore"><ahref="#"class="tooltip"title="This example is not tested">ⓘ</a><preclass="rust rust-example-rendered"><code><spanclass="comment">// Derive `Valuable` for our types:
<p>Alternatively, the [<code>valuable()</code>] function may be used to convert a type
implementing <ahref="https://crates.io/crates/valuable"><code>Valuable</code></a> into a <code>tracing</code> field value.</p>
<p>When the <code>valuable</code> feature is enabled, the <ahref="trait.Visit.html"title="trait tracing::field::Visit"><code>Visit</code></a> trait will include an
optional <ahref="Visit::record_value"><code>record_value</code></a> method. <code>Visit</code> implementations that wish to
record <code>valuable</code> values can implement this method with custom behavior.
If a visitor does not implement <code>record_value</code>, the <ahref="https://docs.rs/valuable/latest/valuable/enum.Value.html"><code>valuable::Value</code></a> will
be forwarded to the visitor’s <ahref="trait.Visit.html#tymethod.record_debug"title="method tracing::field::Visit::record_debug"><code>record_debug</code></a> method.</p>
</div></details><h2id="structs"class="section-header">Structs<ahref="#structs"class="anchor">§</a></h2><ulclass="item-table"><li><divclass="item-name"><aclass="struct"href="struct.DebugValue.html"title="struct tracing::field::DebugValue">DebugValue</a></div><divclass="desc docblock-short">A <code>Value</code> which serializes as a string using <code>fmt::Debug</code>.</div></li><li><divclass="item-name"><aclass="struct"href="struct.DisplayValue.html"title="struct tracing::field::DisplayValue">DisplayValue</a></div><divclass="desc docblock-short">A <code>Value</code> which serializes using <code>fmt::Display</code>.</div></li><li><divclass="item-name"><aclass="struct"href="struct.Empty.html"title="struct tracing::field::Empty">Empty</a></div><divclass="desc docblock-short">An empty field.</div></li><li><divclass="item-name"><aclass="struct"href="struct.Field.html"title="struct tracing::field::Field">Field</a></div><divclass="desc docblock-short">An opaque key allowing <em>O</em>(1) access to a field in a <code>Span</code>’s key-value
data.</div></li><li><divclass="item-name"><aclass="struct"href="struct.FieldSet.html"title="struct tracing::field::FieldSet">FieldSet</a></div><divclass="desc docblock-short">Describes the fields present on a span.</div></li><li><divclass="item-name"><aclass="struct"href="struct.Iter.html"title="struct tracing::field::Iter">Iter</a></div><divclass="desc docblock-short">An iterator over a set of fields.</div></li><li><divclass="item-name"><aclass="struct"href="struct.ValueSet.html"title="struct tracing::field::ValueSet">ValueSet</a></div><divclass="desc docblock-short">A set of fields and values for a span.</div></li></ul><h2id="traits"class="section-header">Traits<ahref="#traits"class="anchor">§</a></h2><ulclass="item-table"><li><divclass="item-name"><aclass="trait"href="trait.AsField.html"title="trait tracing::field::AsField">AsField</a></div><divclass="desc docblock-short">Trait implemented to allow a type to be used as a field key.</div></li><li><divclass="item-name"><aclass="trait"href="trait.Value.html"title="trait tracing::field::Value">Value</a></div><divclass="desc docblock-short">A field value of an erased type.</div></li><li><divclass="item-name"><aclass="trait"href="trait.Visit.html"title="trait tracing::field::Visit">Visit</a></div><divclass="desc docblock-short">Visits typed values.</div></li></ul><h2id="functions"class="section-header">Functions<ahref="#functions"class="anchor">§</a></h2><ulclass="item-table"><li><divclass="item-name"><aclass="fn"href="fn.debug.html"title="fn tracing::field::debug">debug</a></div><divclass="desc docblock-short">Wraps a type implementing <code>fmt::Debug</code> as a <code>Value</code> that can be
recorded using its <code>Debug</code> implementation.</div></li><li><divclass="item-name"><aclass="fn"href="fn.display.html"title="fn tracing::field::display">display</a></div><divclass="desc docblock-short">Wraps a type implementing <code>fmt::Display</code> as a <code>Value</code> that can be
recorded using its <code>Display</code> implementation.</div></li></ul></section></div></main></body></html>
