<!DOCTYPE html><htmllang="en"><head><metacharset="utf-8"><metaname="viewport"content="width=device-width, initial-scale=1.0"><metaname="generator"content="rustdoc"><metaname="description"content="Instruments a function to create and enter a `tracing` span every time the function is called."><title>instrument in tracing - Rust</title><linkrel="preload"as="font"type="font/woff2"crossoriginhref="../static.files/SourceSerif4-Regular-46f98efaafac5295.ttf.woff2"><linkrel="preload"as="font"type="font/woff2"crossoriginhref="../static.files/FiraSans-Regular-018c141bf0843ffd.woff2"><linkrel="preload"as="font"type="font/woff2"crossoriginhref="../static.files/FiraSans-Medium-8f9a781e4970d388.woff2"><linkrel="preload"as="font"type="font/woff2"crossoriginhref="../static.files/SourceCodePro-Regular-562dcc5011b6de7d.ttf.woff2"><linkrel="preload"as="font"type="font/woff2"crossoriginhref="../static.files/SourceCodePro-Semibold-d899c5a5c4aeb14a.ttf.woff2"><linkrel="stylesheet"href="../static.files/normalize-76eba96aa4d2e634.css"><linkrel="stylesheet"href="../static.files/rustdoc-5bc39a1768837dd0.css"><metaname="rustdoc-vars"data-root-path="../"data-static-root-path="../static.files/"data-current-crate="tracing"data-themes=""data-resource-suffix=""data-rustdoc-version="1.77.0 (aedd173a2 2024-03-17)"data-channel="1.77.0"data-search-js="search-dd67cee4cfa65049.js"data-settings-js="settings-4313503d2e1961c2.js"><scriptsrc="../static.files/storage-4c98445ec4002617.js"></script><scriptdefersrc="sidebar-items.js"></script><scriptdefersrc="../static.files/main-48f368f3872407c8.js"></script><noscript><linkrel="stylesheet"href="../static.files/noscript-04d5337699b92874.css"></noscript><linkrel="alternate icon"type="image/png"href="../static.files/favicon-16x16-8b506e7a72182f1c.png"><linkrel="alternate icon"type="image/png"href="../static.files/favicon-32x32-422f7d1d52889060.png"><linkrel="icon"type="image/svg+xml"href="../static.files/favicon-2c020d218678b618.svg"></head><bodyclass="rustdoc attr"><!--[if lte IE 11]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><navclass="mobile-topbar"><buttonclass="sidebar-menu-toggle"title="show sidebar"></button><aclass="logo-container"href="../tracing/index.html"><imgsrc="https://raw.githubusercontent.com/tokio-rs/tracing/master/assets/logo-type.png"alt=""></a></nav><navclass="sidebar"><divclass="sidebar-crate"><aclass="logo-container"href="../tracing/index.html"><imgsrc="https://raw.githubusercontent.com/tokio-rs/tracing/master/assets/logo-type.png"alt="logo"></a><h2><ahref="../tracing/index.html">tracing</a><spanclass="version">0.1.40</span></h2></div><divclass="sidebar-elems"></div></nav><divclass="sidebar-resizer"></div>
<main><divclass="width-limiter"><navclass="sub"><formclass="search-form"><span></span><divid="sidebar-button"tabindex="-1"><ahref="../tracing/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>Attribute Macro <ahref="index.html">tracing</a>::<wbr><aclass="attr"href="#">instrument</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_attributes/lib.rs.html#563-566">source</a> · <buttonid="toggle-all-docs"title="collapse all docs">[<span>−</span>]</button></span></div><preclass="rust item-decl"><code>#[instrument]</code></pre><detailsclass="toggle top-doc"open><summaryclass="hideme"><span>Expand description</span></summary><divclass="docblock"><p>Instruments a function to create and enter a <code>tracing</code><ahref="https://docs.rs/tracing/latest/tracing/span/index.html">span</a> every time
the function is called.</p>
<p>Unless overridden, a span with the <ahref="https://docs.rs/tracing/latest/tracing/struct.Level.html#associatedconstant.INFO"><code>INFO</code></a><ahref="https://docs.rs/tracing/latest/tracing/struct.Level.html">level</a> will be generated.
The generated span’s name will be the name of the function.
By default, all arguments to the function are included as fields on the
span. Arguments that are <code>tracing</code><ahref="https://docs.rs/tracing/latest/tracing/field/trait.Value.html#foreign-impls">primitive types</a> implementing the
<ahref="https://docs.rs/tracing/latest/tracing/field/trait.Value.html."><code>Value</code> trait</a> will be recorded as fields of that type. Types which do
not implement <code>Value</code> will be recorded using [<code>std::fmt::Debug</code>].</p>
<p>To change the <ahref="https://docs.rs/tracing/latest/tracing/struct.Metadata.html#method.name">name</a> of the generated span, add a <code>name</code> argument to the
<code>#[instrument]</code> macro, followed by an equals sign and a string literal. For
<spanclass="comment">// ... do something incredibly interesting and important ...
</span>}</code></pre></div>
<p>To override the <ahref="https://docs.rs/tracing/latest/tracing/struct.Metadata.html#method.target">target</a> of the generated span, add a <code>target</code> argument to
the <code>#[instrument]</code> macro, followed by an equals sign and a string literal
for the new target. The <ahref="https://docs.rs/tracing/latest/tracing/struct.Metadata.html#method.module_path">module path</a> is still recorded separately. For
example:</p>
<divclass="example-wrap"><preclass="rust rust-example-rendered"><code><spanclass="kw">pub mod </span>my_module {
<spanclass="comment">// The generated span's target will be "my_crate::some_special_target",
<spanclass="comment">// ... all kinds of neat code in here ...
</span>}
}</code></pre></div>
<p>Finally, to override the <ahref="https://docs.rs/tracing/latest/tracing/struct.Level.html">level</a> of the generated span, add a <code>level</code>
argument, followed by an equals sign and a string literal with the name of
the desired level. Level names are not case sensitive. For example:</p>
<divclass="example-wrap"><preclass="rust rust-example-rendered"><code><spanclass="comment">// The span's level will be TRACE rather than INFO.
<p>Additional fields (key-value pairs with arbitrary data) can be passed to
to the generated span through the <code>fields</code> argument on the
<code>#[instrument]</code> macro. Strings, integers or boolean literals are accepted values
for each field. The name of the field must be a single valid Rust
identifier, nested (dotted) field names are not supported. Any
Rust expression can be used as a field value in this manner. These
expressions will be evaluated at the beginning of the function’s body, so
arguments to the function may be used in these expressions. Field names may
also be specified <em>without</em> values. Doing so will result in an <ahref="https://docs.rs/tracing/latest/tracing/field/struct.Empty.html">empty field</a>
whose value may be recorded later within the function body.</p>
<p>Note that overlap between the names of fields and (non-skipped) arguments
<spanclass="comment">// ... handle the request ...
</span>}</code></pre></div>
<p>This can be used in conjunction with <code>skip</code> or <code>skip_all</code> to record only
some fields of a struct:</p>
<divclass="example-wrap"><preclass="rust rust-example-rendered"><code><spanclass="comment">// Remember the struct with the very large `data` field from the earlier
// example? Now it also has a `name`, which we might want to include in
<p>Levels can be specified either with <ahref="https://docs.rs/tracing/latest/tracing/struct.Level.html"><code>Level</code></a> constants, literal strings
(e.g., <code>"debug"</code>, <code>"info"</code>) or numerically (1—5, corresponding to <ahref="https://docs.rs/tracing/latest/tracing/struct.Level.html#associatedconstant.TRACE"><code>Level::TRACE</code></a>—<ahref="https://docs.rs/tracing/latest/tracing/struct.Level.html#associatedconstant.ERROR"><code>Level::ERROR</code></a>).</p>
<p>The return value event will have the same level as the span generated by <code>#[instrument]</code>.
By default, this will be <ahref="https://docs.rs/tracing/latest/tracing/struct.Level.html#associatedconstant.INFO"><code>INFO</code></a>, but if the level is overridden, the event will be at the same
level.</p>
<p>It’s also possible to override the level for the <code>ret</code> event independently:</p>
<p><code>const fn</code> cannot be instrumented, and will result in a compilation failure:</p>
<divclass="example-wrap compile_fail"><ahref="#"class="tooltip"title="This example deliberately fails to compile">ⓘ</a><preclass="rust rust-example-rendered"><code><spanclass="attr">#[instrument]
