<main><divclass="width-limiter"><navclass="sub"><formclass="search-form"><span></span><divid="sidebar-button"tabindex="-1"><ahref="../../tracing_core/all.html"title="show sidebar"></a></div><inputclass="search-input"name="search"aria-label="Run search in the documentation"autocomplete="off"spellcheck="false"placeholder="Click or press ‘S’ to search, ‘?’ for more options…"type="search"><divid="help-button"tabindex="-1"><ahref="../../help.html"title="help">?</a></div><divid="settings-menu"tabindex="-1"><ahref="../../settings.html"title="settings"><imgwidth="22"height="22"alt="Change settings"src="../../static.files/wheel-7b819b6101059cd0.svg"></a></div></form></nav><sectionid="main-content"class="content"><divclass="main-heading"><h1>Module <ahref="../index.html">tracing_core</a>::<wbr><aclass="mod"href="#">field</a><buttonid="copy-path"title="Copy item path to clipboard"><imgsrc="../../static.files/clipboard-7571035ce49a181d.svg"width="19"height="18"alt="Copy item path"></button></h1><spanclass="out-of-band"><aclass="src"href="../../src/tracing_core/field.rs.html#1-1255">source</a> · <buttonid="toggle-all-docs"title="collapse all docs">[<span>−</span>]</button></span></div><detailsclass="toggle top-doc"open><summaryclass="hideme"><span>Expand description</span></summary><divclass="docblock"><p><code>Span</code> and <code>Event</code> key-value data.</p>
<p>Spans and events may be annotated with key-value data, known 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_core::field::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_core::span">span</a>s or <ahref="../struct.Event.html"title="struct tracing_core::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_core::Metadata"><code>Metadata</code></a>.
When a span is created, it provides <ahref="../span/struct.Attributes.html"title="struct tracing_core::span::Attributes"><code>Attributes</code></a> to the <code>Subscriber</code>’s
<ahref="../trait.Subscriber.html#tymethod.new_span"title="method tracing_core::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_core::span::Record"><code>record</code></a> method
with additional <ahref="../span/struct.Record.html"title="struct tracing_core::span::Record"><code>Record</code></a>s if values are added for more of its fields.
Similarly, the <ahref="../struct.Event.html"title="struct tracing_core::Event"><code>Event</code></a> type passed to the subscriber’s <ahref="../struct.Event.html"title="struct tracing_core::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>i128</code>, <code>u128</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_core::field::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_core::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_core::field::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.78.0/core/fmt/trait.Debug.html"title="trait core::fmt::Debug"><code>fmt::Debug</code></a> or <ahref="https://doc.rust-lang.org/1.78.0/core/fmt/trait.Display.html"title="trait core::fmt::Display"><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 [<code>valuable::Valuable</code>] trait,
and be recorded as a <code>tracing</code> field by calling their <ahref="valuable::Valuable::as_value"><code>as_value</code></a> method.
If the <ahref="../trait.Subscriber.html"title="trait tracing_core::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_core::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 [<code>valuable::Value</code>] will
be forwarded to the visitor’s <ahref="trait.Visit.html#tymethod.record_debug"title="method tracing_core::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_core::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_core::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_core::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_core::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_core::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_core::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_core::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.Value.html"title="trait tracing_core::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_core::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_core::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_core::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>
