edlang/tracing_core/field/trait.Visit.html
2024-02-13 06:38:44 +00:00

97 lines
23 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="generator" content="rustdoc"><meta name="description" content="Visits typed values."><title>Visit in tracing_core::field - Rust</title><link rel="preload" as="font" type="font/woff2" crossorigin href="../../static.files/SourceSerif4-Regular-46f98efaafac5295.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../../static.files/FiraSans-Regular-018c141bf0843ffd.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../../static.files/FiraSans-Medium-8f9a781e4970d388.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../../static.files/SourceCodePro-Regular-562dcc5011b6de7d.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../../static.files/SourceCodePro-Semibold-d899c5a5c4aeb14a.ttf.woff2"><link rel="stylesheet" href="../../static.files/normalize-76eba96aa4d2e634.css"><link rel="stylesheet" href="../../static.files/rustdoc-ac92e1bbe349e143.css"><meta name="rustdoc-vars" data-root-path="../../" data-static-root-path="../../static.files/" data-current-crate="tracing_core" data-themes="" data-resource-suffix="" data-rustdoc-version="1.76.0 (07dca489a 2024-02-04)" data-channel="1.76.0" data-search-js="search-2b6ce74ff89ae146.js" data-settings-js="settings-4313503d2e1961c2.js" ><script src="../../static.files/storage-f2adc0d6ca4d09fb.js"></script><script defer src="sidebar-items.js"></script><script defer src="../../static.files/main-305769736d49e732.js"></script><noscript><link rel="stylesheet" href="../../static.files/noscript-feafe1bb7466e4bd.css"></noscript><link rel="alternate icon" type="image/png" href="../../static.files/favicon-16x16-8b506e7a72182f1c.png"><link rel="alternate icon" type="image/png" href="../../static.files/favicon-32x32-422f7d1d52889060.png"><link rel="icon" type="image/svg+xml" href="../../static.files/favicon-2c020d218678b618.svg"></head><body class="rustdoc trait"><!--[if lte IE 11]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><nav class="mobile-topbar"><button class="sidebar-menu-toggle">&#9776;</button><a class="logo-container" href="../../tracing_core/index.html"><img src="https://raw.githubusercontent.com/tokio-rs/tracing/master/assets/logo-type.png" alt=""></a></nav><nav class="sidebar"><div class="sidebar-crate"><a class="logo-container" href="../../tracing_core/index.html"><img src="https://raw.githubusercontent.com/tokio-rs/tracing/master/assets/logo-type.png" alt="logo"></a><h2><a href="../../tracing_core/index.html">tracing_core</a><span class="version">0.1.32</span></h2></div><h2 class="location"><a href="#">Visit</a></h2><div class="sidebar-elems"><section><h3><a href="#required-methods">Required Methods</a></h3><ul class="block"><li><a href="#tymethod.record_debug">record_debug</a></li></ul><h3><a href="#provided-methods">Provided Methods</a></h3><ul class="block"><li><a href="#method.record_bool">record_bool</a></li><li><a href="#method.record_error">record_error</a></li><li><a href="#method.record_f64">record_f64</a></li><li><a href="#method.record_i128">record_i128</a></li><li><a href="#method.record_i64">record_i64</a></li><li><a href="#method.record_str">record_str</a></li><li><a href="#method.record_u128">record_u128</a></li><li><a href="#method.record_u64">record_u64</a></li></ul><h3><a href="#foreign-impls">Implementations on Foreign Types</a></h3><ul class="block"><li><a href="#impl-Visit-for-DebugMap%3C'a,+'b%3E">DebugMap&lt;&#x27;a, &#x27;b&gt;</a></li><li><a href="#impl-Visit-for-DebugStruct%3C'a,+'b%3E">DebugStruct&lt;&#x27;a, &#x27;b&gt;</a></li></ul><h3><a href="#implementors">Implementors</a></h3></section><h2><a href="index.html">In tracing_core::field</a></h2></div></nav><div class="sidebar-resizer"></div>
<main><div class="width-limiter"><nav class="sub"><form class="search-form"><span></span><div id="sidebar-button" tabindex="-1"><a href="../../tracing_core/all.html" title="show sidebar"></a></div><input class="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"><div id="help-button" tabindex="-1"><a href="../../help.html" title="help">?</a></div><div id="settings-menu" tabindex="-1"><a href="../../settings.html" title="settings"><img width="22" height="22" alt="Change settings" src="../../static.files/wheel-7b819b6101059cd0.svg"></a></div></form></nav><section id="main-content" class="content"><div class="main-heading"><h1>Trait <a href="../index.html">tracing_core</a>::<wbr><a href="index.html">field</a>::<wbr><a class="trait" href="#">Visit</a><button id="copy-path" title="Copy item path to clipboard"><img src="../../static.files/clipboard-7571035ce49a181d.svg" width="19" height="18" alt="Copy item path"></button></h1><span class="out-of-band"><a class="src" href="../../src/tracing_core/field.rs.html#266-327">source</a> · <button id="toggle-all-docs" title="collapse all docs">[<span>&#x2212;</span>]</button></span></div><pre class="rust item-decl"><code>pub trait Visit {
// Required method
fn <a href="#tymethod.record_debug" class="fn">record_debug</a>(&amp;mut self, field: &amp;<a class="struct" href="../struct.Field.html" title="struct tracing_core::Field">Field</a>, value: &amp;dyn <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/fmt/trait.Debug.html" title="trait core::fmt::Debug">Debug</a>);
// Provided methods
fn <a href="#method.record_f64" class="fn">record_f64</a>(&amp;mut self, field: &amp;<a class="struct" href="../struct.Field.html" title="struct tracing_core::Field">Field</a>, value: <a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.f64.html">f64</a>) { ... }
<span class="item-spacer"></span> fn <a href="#method.record_i64" class="fn">record_i64</a>(&amp;mut self, field: &amp;<a class="struct" href="../struct.Field.html" title="struct tracing_core::Field">Field</a>, value: <a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.i64.html">i64</a>) { ... }
<span class="item-spacer"></span> fn <a href="#method.record_u64" class="fn">record_u64</a>(&amp;mut self, field: &amp;<a class="struct" href="../struct.Field.html" title="struct tracing_core::Field">Field</a>, value: <a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.u64.html">u64</a>) { ... }
<span class="item-spacer"></span> fn <a href="#method.record_i128" class="fn">record_i128</a>(&amp;mut self, field: &amp;<a class="struct" href="../struct.Field.html" title="struct tracing_core::Field">Field</a>, value: <a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.i128.html">i128</a>) { ... }
<span class="item-spacer"></span> fn <a href="#method.record_u128" class="fn">record_u128</a>(&amp;mut self, field: &amp;<a class="struct" href="../struct.Field.html" title="struct tracing_core::Field">Field</a>, value: <a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.u128.html">u128</a>) { ... }
<span class="item-spacer"></span> fn <a href="#method.record_bool" class="fn">record_bool</a>(&amp;mut self, field: &amp;<a class="struct" href="../struct.Field.html" title="struct tracing_core::Field">Field</a>, value: <a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.bool.html">bool</a>) { ... }
<span class="item-spacer"></span> fn <a href="#method.record_str" class="fn">record_str</a>(&amp;mut self, field: &amp;<a class="struct" href="../struct.Field.html" title="struct tracing_core::Field">Field</a>, value: &amp;<a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.str.html">str</a>) { ... }
<span class="item-spacer"></span> fn <a href="#method.record_error" class="fn">record_error</a>(&amp;mut self, field: &amp;<a class="struct" href="../struct.Field.html" title="struct tracing_core::Field">Field</a>, value: &amp;(dyn <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/error/trait.Error.html" title="trait core::error::Error">Error</a> + 'static)) { ... }
}</code></pre><details class="toggle top-doc" open><summary class="hideme"><span>Expand description</span></summary><div class="docblock"><p>Visits typed values.</p>
<p>An instance of <code>Visit</code> (“a visitor”) represents the logic necessary to
record field values of various types. When an implementor of <a href="trait.Value.html" title="trait tracing_core::field::Value"><code>Value</code></a> is
<a href="trait.Value.html#tymethod.record" title="method tracing_core::field::Value::record">recorded</a>, it calls the appropriate method on the provided visitor to
indicate the type that value should be recorded as.</p>
<p>When a <a href="../trait.Subscriber.html" title="trait tracing_core::Subscriber"><code>Subscriber</code></a> implementation <a href="../trait.Subscriber.html#tymethod.event" title="method tracing_core::Subscriber::event">records an <code>Event</code></a> or a
<a href="../trait.Subscriber.html#tymethod.record" title="method tracing_core::Subscriber::record">set of <code>Value</code>s added to a <code>Span</code></a>, it can pass an <code>&amp;mut Visit</code> to the
<code>record</code> method on the provided <a href="struct.ValueSet.html" title="struct tracing_core::field::ValueSet"><code>ValueSet</code></a> or <a href="../struct.Event.html" title="struct tracing_core::Event"><code>Event</code></a>. This visitor
will then be used to record all the field-value pairs present on that
<code>Event</code> or <code>ValueSet</code>.</p>
<h2 id="examples"><a href="#examples">Examples</a></h2>
<p>A simple visitor that writes to a string might be implemented like so:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>std::fmt::{<span class="self">self</span>, Write};
<span class="kw">use </span>tracing::field::{Value, Visit, Field};
<span class="kw">pub struct </span>StringVisitor&lt;<span class="lifetime">'a</span>&gt; {
string: <span class="kw-2">&amp;</span><span class="lifetime">'a </span><span class="kw-2">mut </span>String,
}
<span class="kw">impl</span>&lt;<span class="lifetime">'a</span>&gt; Visit <span class="kw">for </span>StringVisitor&lt;<span class="lifetime">'a</span>&gt; {
<span class="kw">fn </span>record_debug(<span class="kw-2">&amp;mut </span><span class="self">self</span>, field: <span class="kw-2">&amp;</span>Field, value: <span class="kw-2">&amp;</span><span class="kw">dyn </span>fmt::Debug) {
<span class="macro">write!</span>(<span class="self">self</span>.string, <span class="string">"{} = {:?}; "</span>, field.name(), value).unwrap();
}
}</code></pre></div>
<p>This visitor will format each recorded value using <code>fmt::Debug</code>, and
append the field name and formatted value to the provided string,
regardless of the type of the recorded value. When all the values have
been recorded, the <code>StringVisitor</code> may be dropped, allowing the string
to be printed or stored in some other data structure.</p>
<p>The <code>Visit</code> trait provides default implementations for <code>record_i64</code>,
<code>record_u64</code>, <code>record_bool</code>, <code>record_str</code>, and <code>record_error</code>, which simply
forward the recorded value to <code>record_debug</code>. Thus, <code>record_debug</code> is the
only method which a <code>Visit</code> implementation <em>must</em> implement. However,
visitors may override the default implementations of these functions in
order to implement type-specific behavior.</p>
<p>Additionally, when a visitor receives a value of a type it does not care
about, it is free to ignore those values completely. For example, a
visitor which only records numeric data might look like this:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">pub struct </span>SumVisitor {
sum: i64,
}
<span class="kw">impl </span>Visit <span class="kw">for </span>SumVisitor {
<span class="kw">fn </span>record_i64(<span class="kw-2">&amp;mut </span><span class="self">self</span>, _field: <span class="kw-2">&amp;</span>Field, value: i64) {
<span class="self">self</span>.sum += value;
}
<span class="kw">fn </span>record_u64(<span class="kw-2">&amp;mut </span><span class="self">self</span>, _field: <span class="kw-2">&amp;</span>Field, value: u64) {
<span class="self">self</span>.sum += value <span class="kw">as </span>i64;
}
<span class="kw">fn </span>record_debug(<span class="kw-2">&amp;mut </span><span class="self">self</span>, _field: <span class="kw-2">&amp;</span>Field, _value: <span class="kw-2">&amp;</span>fmt::Debug) {
<span class="comment">// Do nothing
</span>}
}</code></pre></div>
<p>This visitor (which is probably not particularly useful) keeps a running
sum of all the numeric values it records, and ignores all other values. A
more practical example of recording typed values is presented in
<code>examples/counters.rs</code>, which demonstrates a very simple metrics system
implemented using <code>tracing</code>.</p>
<div class="example-wrap" style="display:inline-block">
<pre class="ignore" style="white-space:normal;font:inherit;">
<strong>Note</strong>: The <code>record_error</code> trait method is only
available when the Rust standard library is present, as it requires the
<code>std::error::Error</code> trait.
</pre></div>
</div></details><h2 id="required-methods" class="section-header">Required Methods<a href="#required-methods" class="anchor">§</a></h2><div class="methods"><details class="toggle method-toggle" open><summary><section id="tymethod.record_debug" class="method"><a class="src rightside" href="../../src/tracing_core/field.rs.html#326">source</a><h4 class="code-header">fn <a href="#tymethod.record_debug" class="fn">record_debug</a>(&amp;mut self, field: &amp;<a class="struct" href="../struct.Field.html" title="struct tracing_core::Field">Field</a>, value: &amp;dyn <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/fmt/trait.Debug.html" title="trait core::fmt::Debug">Debug</a>)</h4></section></summary><div class="docblock"><p>Visit a value implementing <code>fmt::Debug</code>.</p>
</div></details></div><h2 id="provided-methods" class="section-header">Provided Methods<a href="#provided-methods" class="anchor">§</a></h2><div class="methods"><details class="toggle method-toggle" open><summary><section id="method.record_f64" class="method"><a class="src rightside" href="../../src/tracing_core/field.rs.html#277-279">source</a><h4 class="code-header">fn <a href="#method.record_f64" class="fn">record_f64</a>(&amp;mut self, field: &amp;<a class="struct" href="../struct.Field.html" title="struct tracing_core::Field">Field</a>, value: <a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.f64.html">f64</a>)</h4></section></summary><div class="docblock"><p>Visit a double-precision floating point value.</p>
</div></details><details class="toggle method-toggle" open><summary><section id="method.record_i64" class="method"><a class="src rightside" href="../../src/tracing_core/field.rs.html#282-284">source</a><h4 class="code-header">fn <a href="#method.record_i64" class="fn">record_i64</a>(&amp;mut self, field: &amp;<a class="struct" href="../struct.Field.html" title="struct tracing_core::Field">Field</a>, value: <a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.i64.html">i64</a>)</h4></section></summary><div class="docblock"><p>Visit a signed 64-bit integer value.</p>
</div></details><details class="toggle method-toggle" open><summary><section id="method.record_u64" class="method"><a class="src rightside" href="../../src/tracing_core/field.rs.html#287-289">source</a><h4 class="code-header">fn <a href="#method.record_u64" class="fn">record_u64</a>(&amp;mut self, field: &amp;<a class="struct" href="../struct.Field.html" title="struct tracing_core::Field">Field</a>, value: <a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.u64.html">u64</a>)</h4></section></summary><div class="docblock"><p>Visit an unsigned 64-bit integer value.</p>
</div></details><details class="toggle method-toggle" open><summary><section id="method.record_i128" class="method"><a class="src rightside" href="../../src/tracing_core/field.rs.html#292-294">source</a><h4 class="code-header">fn <a href="#method.record_i128" class="fn">record_i128</a>(&amp;mut self, field: &amp;<a class="struct" href="../struct.Field.html" title="struct tracing_core::Field">Field</a>, value: <a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.i128.html">i128</a>)</h4></section></summary><div class="docblock"><p>Visit a signed 128-bit integer value.</p>
</div></details><details class="toggle method-toggle" open><summary><section id="method.record_u128" class="method"><a class="src rightside" href="../../src/tracing_core/field.rs.html#297-299">source</a><h4 class="code-header">fn <a href="#method.record_u128" class="fn">record_u128</a>(&amp;mut self, field: &amp;<a class="struct" href="../struct.Field.html" title="struct tracing_core::Field">Field</a>, value: <a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.u128.html">u128</a>)</h4></section></summary><div class="docblock"><p>Visit an unsigned 128-bit integer value.</p>
</div></details><details class="toggle method-toggle" open><summary><section id="method.record_bool" class="method"><a class="src rightside" href="../../src/tracing_core/field.rs.html#302-304">source</a><h4 class="code-header">fn <a href="#method.record_bool" class="fn">record_bool</a>(&amp;mut self, field: &amp;<a class="struct" href="../struct.Field.html" title="struct tracing_core::Field">Field</a>, value: <a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.bool.html">bool</a>)</h4></section></summary><div class="docblock"><p>Visit a boolean value.</p>
</div></details><details class="toggle method-toggle" open><summary><section id="method.record_str" class="method"><a class="src rightside" href="../../src/tracing_core/field.rs.html#307-309">source</a><h4 class="code-header">fn <a href="#method.record_str" class="fn">record_str</a>(&amp;mut self, field: &amp;<a class="struct" href="../struct.Field.html" title="struct tracing_core::Field">Field</a>, value: &amp;<a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.str.html">str</a>)</h4></section></summary><div class="docblock"><p>Visit a string value.</p>
</div></details><details class="toggle method-toggle" open><summary><section id="method.record_error" class="method"><a class="src rightside" href="../../src/tracing_core/field.rs.html#321-323">source</a><h4 class="code-header">fn <a href="#method.record_error" class="fn">record_error</a>(&amp;mut self, field: &amp;<a class="struct" href="../struct.Field.html" title="struct tracing_core::Field">Field</a>, value: &amp;(dyn <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/error/trait.Error.html" title="trait core::error::Error">Error</a> + 'static))</h4></section></summary><div class="docblock"><p>Records a type implementing <code>Error</code>.</p>
<div class="example-wrap" style="display:inline-block">
<pre class="ignore" style="white-space:normal;font:inherit;">
<strong>Note</strong>: This is only enabled when the Rust standard library is
present.
</pre>
</div></div></details></div><h2 id="foreign-impls" class="section-header">Implementations on Foreign Types<a href="#foreign-impls" class="anchor">§</a></h2><details class="toggle implementors-toggle"><summary><section id="impl-Visit-for-DebugMap%3C'a,+'b%3E" class="impl"><a class="src rightside" href="../../src/tracing_core/field.rs.html#391-395">source</a><a href="#impl-Visit-for-DebugMap%3C'a,+'b%3E" class="anchor">§</a><h3 class="code-header">impl&lt;'a, 'b&gt; <a class="trait" href="trait.Visit.html" title="trait tracing_core::field::Visit">Visit</a> for <a class="struct" href="https://doc.rust-lang.org/1.76.0/core/fmt/builders/struct.DebugMap.html" title="struct core::fmt::builders::DebugMap">DebugMap</a>&lt;'a, 'b&gt;</h3></section></summary><div class="impl-items"><section id="method.record_debug" class="method trait-impl"><a class="src rightside" href="../../src/tracing_core/field.rs.html#392-394">source</a><a href="#method.record_debug" class="anchor">§</a><h4 class="code-header">fn <a href="#tymethod.record_debug" class="fn">record_debug</a>(&amp;mut self, field: &amp;<a class="struct" href="../struct.Field.html" title="struct tracing_core::Field">Field</a>, value: &amp;dyn <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/fmt/trait.Debug.html" title="trait core::fmt::Debug">Debug</a>)</h4></section></div></details><details class="toggle implementors-toggle"><summary><section id="impl-Visit-for-DebugStruct%3C'a,+'b%3E" class="impl"><a class="src rightside" href="../../src/tracing_core/field.rs.html#385-389">source</a><a href="#impl-Visit-for-DebugStruct%3C'a,+'b%3E" class="anchor">§</a><h3 class="code-header">impl&lt;'a, 'b&gt; <a class="trait" href="trait.Visit.html" title="trait tracing_core::field::Visit">Visit</a> for <a class="struct" href="https://doc.rust-lang.org/1.76.0/core/fmt/builders/struct.DebugStruct.html" title="struct core::fmt::builders::DebugStruct">DebugStruct</a>&lt;'a, 'b&gt;</h3></section></summary><div class="impl-items"><section id="method.record_debug-1" class="method trait-impl"><a class="src rightside" href="../../src/tracing_core/field.rs.html#386-388">source</a><a href="#method.record_debug-1" class="anchor">§</a><h4 class="code-header">fn <a href="#tymethod.record_debug" class="fn">record_debug</a>(&amp;mut self, field: &amp;<a class="struct" href="../struct.Field.html" title="struct tracing_core::Field">Field</a>, value: &amp;dyn <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/fmt/trait.Debug.html" title="trait core::fmt::Debug">Debug</a>)</h4></section></div></details><h2 id="implementors" class="section-header">Implementors<a href="#implementors" class="anchor">§</a></h2><div id="implementors-list"><section id="impl-Visit-for-F" class="impl"><a class="src rightside" href="../../src/tracing_core/field.rs.html#397-404">source</a><a href="#impl-Visit-for-F" class="anchor">§</a><h3 class="code-header">impl&lt;F&gt; <a class="trait" href="trait.Visit.html" title="trait tracing_core::field::Visit">Visit</a> for F<div class="where">where
F: <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/ops/function/trait.FnMut.html" title="trait core::ops::function::FnMut">FnMut</a>(&amp;<a class="struct" href="../struct.Field.html" title="struct tracing_core::Field">Field</a>, &amp;dyn <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/fmt/trait.Debug.html" title="trait core::fmt::Debug">Debug</a>),</div></h3></section></div><script src="../../trait.impl/tracing_core/field/trait.Visit.js" data-ignore-extern-crates="core" async></script></section></div></main></body></html>