<!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="Spans represent periods of time in which a program was executing in a particular context."><title>tracing::span - Rust</title><script>if(window.location.protocol!=="file:")document.head.insertAdjacentHTML("beforeend","SourceSerif4-Regular-46f98efaafac5295.ttf.woff2,FiraSans-Regular-018c141bf0843ffd.woff2,FiraSans-Medium-8f9a781e4970d388.woff2,SourceCodePro-Regular-562dcc5011b6de7d.ttf.woff2,SourceCodePro-Semibold-d899c5a5c4aeb14a.ttf.woff2".split(",").map(f=>`<link rel="preload" as="font" type="font/woff2" crossorigin href="../../static.files/${f}">`).join(""))</script><linkrel="stylesheet"href="../../static.files/normalize-76eba96aa4d2e634.css"><linkrel="stylesheet"href="../../static.files/rustdoc-dd39b87e5fcfba68.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.80.0 (051478957 2024-07-21)"data-channel="1.80.0"data-search-js="search-d52510db62a78183.js"data-settings-js="settings-4313503d2e1961c2.js"><scriptsrc="../../static.files/storage-118b08c4c78b968e.js"></script><scriptdefersrc="../sidebar-items.js"></script><scriptdefersrc="../../static.files/main-20a3ad099b048cf2.js"></script><noscript><linkrel="stylesheet"href="../../static.files/noscript-df360f571f6edeae.css"></noscript><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 mod"><!--[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><h2class="location"><ahref="#">Module span</a></h2><divclass="sidebar-elems"><section><ulclass="block"><li><ahref="#structs">Structs</a></li><li><ahref="#traits">Traits</a></li></ul></section><h2><ahref="../index.html">In crate tracing</a></h2></div></nav><divclass="sidebar-resizer"></div><main><divclass="width-limiter"><rustdoc-search></rustdoc-search><sectionid="main-content"class="content"><divclass="main-heading"><h1>Module <ahref="../index.html">tracing</a>::<wbr><aclass="mod"href="#">span</a><buttonid="copy-path"title="Copy item path to clipboard">Copy item path</button></h1><spanclass="out-of-band"><aclass="src"href="../../src/tracing/span.rs.html#1-1623">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>Spans represent periods of time in which a program was executing in a
<p>Spans are created using the <ahref="../macro.span.html"title="macro tracing::span"><code>span!</code></a> macro. This macro is invoked with the
following arguments, in order:</p>
<ul>
<li>The <ahref="../struct.Metadata.html#method.target"title="method tracing::Metadata::target"><code>target</code></a> and/or <ahref="#span-relationships"><code>parent</code></a> attributes, if the user wishes to
<p>The <ahref="struct.Attributes.html"title="struct tracing::span::Attributes"><code>Attributes</code></a> type contains data associated with a span, and is
provided to the <ahref="../trait.Subscriber.html"title="trait tracing::Subscriber"><code>Subscriber</code></a> when a new span is created. It contains
the span’s metadata, the ID of <ahref="#span-relationships">the span’s parent</a> if one was
explicitly set, and any fields whose values were recorded when the span was
constructed. The subscriber, which is responsible for recording <code>tracing</code>
<h2id="the-span-lifecycle"><aclass="doc-anchor"href="#the-span-lifecycle">§</a>The Span Lifecycle</h2><h3id="entering-a-span"><aclass="doc-anchor"href="#entering-a-span">§</a>Entering a Span</h3>
<p>A thread of execution is said to <em>enter</em> a span when it begins executing,
and <em>exit</em> the span when it switches to another context. Spans may be
entered through the <ahref="../struct.Span.html#method.enter"title="method tracing::Span::enter"><code>enter</code></a>, <ahref="../struct.Span.html#method.entered"title="method tracing::Span::entered"><code>entered</code></a>, and <ahref="../struct.Span.html#method.in_scope"title="method tracing::Span::in_scope"><code>in_scope</code></a> methods.</p>
<p>The <ahref="../struct.Span.html#method.enter"title="method tracing::Span::enter"><code>enter</code></a> method enters a span, returning a <ahref="struct.Entered.html"title="struct tracing::span::Entered">guard</a> that exits the span
<p>The <ahref="../struct.Span.html#method.entered"title="method tracing::Span::entered"><code>entered</code></a> method is analogous to <ahref="../struct.Span.html#method.enter"title="method tracing::Span::enter"><code>enter</code></a>, but moves the span into
the returned guard, rather than borrowing it. This allows creating and
entering a span in a single expression:</p>
<divclass="example-wrap"><preclass="rust rust-example-rendered"><code><spanclass="comment">// Create a span and enter it, returning a guard:
<p>Finally, <ahref="../struct.Span.html#method.in_scope"title="method tracing::Span::in_scope"><code>in_scope</code></a> takes a closure or function pointer and executes it
before <code>poll</code> returns <ahref="https://doc.rust-lang.org/1.80.0/core/task/poll/enum.Poll.html#variant.Ready"title="variant core::task::poll::Poll::Ready"><code>Poll::Ready</code></a>. If the future were to yield, then
the executor would move on to poll the next future, which may <em>also</em> enter
an associated span or series of spans. Therefore, it is valid for a span to
be entered repeatedly before it completes. Only the time when that span or
one of its children was the current span is considered to be time spent in
that span. A span which is not executing and has not yet been closed is said
to be <em>idle</em>.</p>
<p>Because spans may be entered and exited multiple times before they close,
<ahref="../trait.Subscriber.html"title="trait tracing::Subscriber"><code>Subscriber</code></a>s have separate trait methods which are called to notify them
of span exits and when span handles are dropped. When execution exits a
span, <ahref="../trait.Subscriber.html#tymethod.exit"title="method tracing::Subscriber::exit"><code>exit</code></a> will always be called with that span’s ID to notify the
subscriber that the span has been exited. When span handles are dropped, the
<ahref="../trait.Subscriber.html#method.drop_span"title="method tracing::Subscriber::drop_span"><code>drop_span</code></a> method is called with that span’s ID. The subscriber may use
this to determine whether or not the span will be entered again.</p>
<p>If there is only a single handle with the capacity to exit a span, dropping
that handle “closes” the span, since the capacity to enter it no longer
<p>However, if multiple handles exist, the span can still be re-entered even if
one or more is dropped. For determining when <em>all</em> handles to a span have
been dropped, <code>Subscriber</code>s have a <ahref="../trait.Subscriber.html#method.clone_span"title="method tracing::Subscriber::clone_span"><code>clone_span</code></a> method, which is called
every time a span handle is cloned. Combined with <code>drop_span</code>, this may be
used to track the number of handles to a given span — if <code>drop_span</code> has
been called one more time than the number of calls to <code>clone_span</code> for a
given ID, then no more handles to the span with that ID exist. The
</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.Attributes.html"title="struct tracing::span::Attributes">Attributes</a></div><divclass="desc docblock-short">Attributes provided to a <code>Subscriber</code> describing a new span when it is
created.</div></li><li><divclass="item-name"><aclass="struct"href="struct.Entered.html"title="struct tracing::span::Entered">Entered</a></div><divclass="desc docblock-short">A guard representing a span which has been entered and is currently
executing.</div></li><li><divclass="item-name"><aclass="struct"href="struct.EnteredSpan.html"title="struct tracing::span::EnteredSpan">EnteredSpan</a></div><divclass="desc docblock-short">An owned version of <ahref="struct.Entered.html"title="struct tracing::span::Entered"><code>Entered</code></a>, a guard representing a span which has been
entered and is currently executing.</div></li><li><divclass="item-name"><aclass="struct"href="struct.Id.html"title="struct tracing::span::Id">Id</a></div><divclass="desc docblock-short">Identifies a span within the context of a subscriber.</div></li><li><divclass="item-name"><aclass="struct"href="struct.Record.html"title="struct tracing::span::Record">Record</a></div><divclass="desc docblock-short">A set of fields recorded by a span.</div></li><li><divclass="item-name"><aclass="struct"href="struct.Span.html"title="struct tracing::span::Span">Span</a></div><divclass="desc docblock-short">A handle representing a span, with the capability to enter the span if it
exists.</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.AsId.html"title="trait tracing::span::AsId">AsId</a></div><divclass="desc docblock-short">Trait implemented by types which have a span <code>Id</code>.</div></li></ul></section></div></main></body></html>
