Buckets:

hf-doc-build
/

doc-dev

Files

xet

hf-doc-build/doc-dev / trackio /pr_679 /en /traces.html

qgallouedec

2 days ago

download

raw

32.1 kB

	<meta charset="utf-8" /><meta name="hf:doc:metadata" content="{"title":"Traces","local":"traces","sections":[{"title":"Log a conversation","local":"log-a-conversation","sections":[],"depth":2},{"title":"Add execution spans","local":"add-execution-spans","sections":[],"depth":2},{"title":"Inspect traces from the CLI","local":"inspect-traces-from-the-cli","sections":[],"depth":2},{"title":"Viewing traces on the Hugging Face Hub","local":"viewing-traces-on-the-hugging-face-hub","sections":[],"depth":2},{"title":"Trace-level metadata","local":"trace-level-metadata","sections":[],"depth":2},{"title":"Search","local":"search","sections":[],"depth":2}],"depth":1}"/>
	<link href="/docs/trackio/v0.36.0/en/_app/immutable/entry/start.DogV0ES3.js" rel="modulepreload">
	<link href="/docs/trackio/v0.36.0/en/_app/immutable/chunks/CGDdRX13.js" rel="modulepreload">
	<link href="/docs/trackio/v0.36.0/en/_app/immutable/chunks/c5epZbRJ.js" rel="modulepreload">
	<link href="/docs/trackio/v0.36.0/en/_app/immutable/entry/app.CrFflN0e.js" rel="modulepreload">
	<link href="/docs/trackio/v0.36.0/en/_app/immutable/chunks/CTPvGMXu.js" rel="modulepreload">
	<link href="/docs/trackio/v0.36.0/en/_app/immutable/chunks/Cbx9Bn2j.js" rel="modulepreload">
	<link href="/docs/trackio/v0.36.0/en/_app/immutable/chunks/DsnmJJEf.js" rel="modulepreload">
	<link href="/docs/trackio/v0.36.0/en/_app/immutable/chunks/CldSabhm.js" rel="modulepreload">
	<link href="/docs/trackio/v0.36.0/en/_app/immutable/nodes/0.DvOJ7cf9.js" rel="modulepreload">
	<link href="/docs/trackio/v0.36.0/en/_app/immutable/chunks/DoyOpfDJ.js" rel="modulepreload">
	<link href="/docs/trackio/v0.36.0/en/_app/immutable/nodes/22.Bz_TFkXS.js" rel="modulepreload">
	<link href="/docs/trackio/v0.36.0/en/_app/immutable/chunks/BQnA81uy.js" rel="modulepreload">
	<!--cn8k97--><meta name="hf:doc:metadata" content="{"title":"Traces","local":"traces","sections":[{"title":"Log a conversation","local":"log-a-conversation","sections":[],"depth":2},{"title":"Add execution spans","local":"add-execution-spans","sections":[],"depth":2},{"title":"Inspect traces from the CLI","local":"inspect-traces-from-the-cli","sections":[],"depth":2},{"title":"Viewing traces on the Hugging Face Hub","local":"viewing-traces-on-the-hugging-face-hub","sections":[],"depth":2},{"title":"Trace-level metadata","local":"trace-level-metadata","sections":[],"depth":2},{"title":"Search","local":"search","sections":[],"depth":2}],"depth":1}"/><!---->
	<link href="/docs/trackio/v0.36.0/en/_app/immutable/assets/0.tn0RQdqM.css" rel="modulepreload"> <!--[--><!--[0--><!--[--><!--[0--><!--[--><p></p> <div class="items-center shrink-0 min-w-[100px] max-sm:min-w-[50px] justify-end ml-auto flex" style="float: right; margin-left: 10px; display: inline-flex; position: relative; z-index: 10;"><div class="inline-flex rounded-md max-sm:rounded-sm"><button class="inline-flex items-center gap-1 h-7 max-sm:h-7 px-2 max-sm:px-1.5 text-sm font-medium text-gray-800 border border-r-0 rounded-l-md max-sm:rounded-l-sm border-gray-200 bg-white hover:shadow-inner dark:border-gray-850 dark:bg-gray-950 dark:text-gray-200 dark:hover:bg-gray-800" aria-live="polite"><span class="inline-flex items-center justify-center rounded-md p-0.5 max-sm:p-0 hover:text-gray-800 dark:hover:text-gray-200"><svg class="sm:size-3.5 size-3" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----></span> <span>Copy page</span></button> <button class="inline-flex items-center justify-center w-6 max-sm:w-5 h-7 max-sm:h-7 disabled:pointer-events-none text-sm text-gray-500 hover:text-gray-700 dark:hover:text-white rounded-r-md max-sm:rounded-r-sm border border-l transition border-gray-200 bg-white hover:shadow-inner dark:border-gray-850 dark:bg-gray-950 dark:text-gray-200 dark:hover:bg-gray-800" aria-haspopup="menu" aria-expanded="false" aria-label="Open copy menu"><svg class="transition-transform text-gray-400 overflow-visible sm:size-3.5 size-3 rotate-0" width="1em" height="1em" viewBox="0 0 12 7" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M1 1L6 6L11 1" stroke="currentColor"></path></svg><!----></button></div> <!--[-1--><!--]--></div><!----> <!--[0--><h1 class="relative group"><a id="traces" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#traces"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>Traces</span></h1><!--]--><!----> <p>Trackio traces capture a user request, the assistant response, and the operations
	that produced it. Open the <strong>Traces</strong> page in the dashboard to search requests,
	inspect model and tool operations, and see latency, token, cost, and status totals.</p> <!--[1--><h2 class="relative group"><a id="log-a-conversation" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#log-a-conversation"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>Log a conversation</span></h2><!--]--><!----> <p>Pass a <a href="./api#trace"><code>Trace</code></a> to <code>trackio.log()</code> with OpenAI-style
	messages:</p> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----> <div class=" absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0 "><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent;"></div> Copied</div><!----></button><!----></div> <pre class="language-python "><!----><span class="hljs-keyword">import</span> trackio

	trackio.init(project=<span class="hljs-string">"research-agent"</span>)
	trackio.log(
	{
	<span class="hljs-string">"trace"</span>: trackio.Trace(
	messages=[
	{<span class="hljs-string">"role"</span>: <span class="hljs-string">"user"</span>, <span class="hljs-string">"content"</span>: <span class="hljs-string">"Find agent training datasets."</span>},
	{<span class="hljs-string">"role"</span>: <span class="hljs-string">"assistant"</span>, <span class="hljs-string">"content"</span>: <span class="hljs-string">"Here are three datasets..."</span>},
	],
	metadata={<span class="hljs-string">"session_id"</span>: <span class="hljs-string">"session-123"</span>, <span class="hljs-string">"environment"</span>: <span class="hljs-string">"production"</span>},
	)
	}
	)
	trackio.finish()<!----></pre></div><!----> <p>Messages can include <code>tool_calls</code> and <code>tool</code> results. When a trace has no explicit
	spans, the dashboard pairs those calls and results into tool operations for easier
	inspection.</p> <!--[1--><h2 class="relative group"><a id="add-execution-spans" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#add-execution-spans"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>Add execution spans</span></h2><!--]--><!----> <p>Use <code>spans</code> when you need timings, hierarchy, model usage, cost, or operation
	status. Each span is a dictionary. The minimal fields are <code>id</code>, <code>name</code>, and <code>kind</code>:</p> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----> <div class=" absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0 "><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent;"></div> Copied</div><!----></button><!----></div> <pre class="language-python "><!---->trackio.Trace(
	messages=messages,
	spans=[
	{
	<span class="hljs-string">"id"</span>: <span class="hljs-string">"research"</span>,
	<span class="hljs-string">"name"</span>: <span class="hljs-string">"answer-research-question"</span>,
	<span class="hljs-string">"kind"</span>: <span class="hljs-string">"span"</span>,
	<span class="hljs-string">"start_time"</span>: <span class="hljs-string">"2026-08-19T12:00:00Z"</span>,
	<span class="hljs-string">"end_time"</span>: <span class="hljs-string">"2026-08-19T12:00:03Z"</span>,
	<span class="hljs-string">"status"</span>: <span class="hljs-string">"success"</span>,
	},
	{
	<span class="hljs-string">"id"</span>: <span class="hljs-string">"generation-1"</span>,
	<span class="hljs-string">"parent_id"</span>: <span class="hljs-string">"research"</span>,
	<span class="hljs-string">"name"</span>: <span class="hljs-string">"provider-request"</span>,
	<span class="hljs-string">"kind"</span>: <span class="hljs-string">"generation"</span>,
	<span class="hljs-string">"start_time"</span>: <span class="hljs-string">"2026-08-19T12:00:00Z"</span>,
	<span class="hljs-string">"end_time"</span>: <span class="hljs-string">"2026-08-19T12:00:01.2Z"</span>,
	<span class="hljs-string">"model"</span>: <span class="hljs-string">"my-model"</span>,
	<span class="hljs-string">"input"</span>: {<span class="hljs-string">"messages"</span>: messages},
	<span class="hljs-string">"output"</span>: {<span class="hljs-string">"text"</span>: <span class="hljs-string">"I will search for datasets."</span>},
	<span class="hljs-string">"usage"</span>: {<span class="hljs-string">"input_tokens"</span>: <span class="hljs-number">8439</span>, <span class="hljs-string">"output_tokens"</span>: <span class="hljs-number">188</span>},
	<span class="hljs-string">"cost_usd"</span>: <span class="hljs-number">0.0042</span>,
	<span class="hljs-string">"status"</span>: <span class="hljs-string">"success"</span>,
	},
	{
	<span class="hljs-string">"id"</span>: <span class="hljs-string">"tool-1"</span>,
	<span class="hljs-string">"parent_id"</span>: <span class="hljs-string">"research"</span>,
	<span class="hljs-string">"name"</span>: <span class="hljs-string">"hf search"</span>,
	<span class="hljs-string">"kind"</span>: <span class="hljs-string">"tool"</span>,
	<span class="hljs-string">"start_time"</span>: <span class="hljs-string">"2026-08-19T12:00:01.3Z"</span>,
	<span class="hljs-string">"end_time"</span>: <span class="hljs-string">"2026-08-19T12:00:02Z"</span>,
	<span class="hljs-string">"input"</span>: {<span class="hljs-string">"query"</span>: <span class="hljs-string">"agent training datasets"</span>},
	<span class="hljs-string">"output"</span>: {<span class="hljs-string">"datasets"</span>: [<span class="hljs-string">"example/dataset"</span>]},
	<span class="hljs-string">"status"</span>: <span class="hljs-string">"success"</span>,
	},
	],
	)<!----></pre></div><!----> <p>Supported span fields:</p> <table><thead><tr><th>Field</th><th>Description</th></tr></thead><tbody><tr><td><code>id</code></td><td>Identifier unique within the trace</td></tr><tr><td><code>parent_id</code></td><td>Optional parent span ID; creates the execution tree</td></tr><tr><td><code>name</code></td><td>Operation name shown in the inspector</td></tr><tr><td><code>kind</code></td><td><code>span</code>, <code>generation</code>, or <code>tool</code></td></tr><tr><td><code>start_time</code>, <code>end_time</code></td><td>ISO-8601 timestamps used to derive latency</td></tr><tr><td><code>duration_ms</code></td><td>Optional duration when timestamps are unavailable</td></tr><tr><td><code>status</code></td><td>Usually <code>success</code> or <code>error</code></td></tr><tr><td><code>error</code></td><td>Structured or textual error details</td></tr><tr><td><code>input</code>, <code>output</code></td><td>Any JSON-serializable operation payload</td></tr><tr><td><code>model</code></td><td>Model identifier for a generation</td></tr><tr><td><code>usage</code></td><td><code>input_tokens</code>, <code>output_tokens</code>, and optional <code>total_tokens</code></td></tr><tr><td><code>cost_usd</code></td><td>Cost for this operation in US dollars</td></tr><tr><td><code>metadata</code></td><td>Additional operation metadata</td></tr></tbody></table> <p>Trace latency is wall-clock time from the earliest span start to the latest span
	end; when no span carries an <code>end_time</code>, the longest single <code>duration_ms</code> is used
	instead. Token and cost totals sum the values on individual spans, so <code>usage</code> and <code>cost_usd</code> should describe the local operation rather than a parent aggregate — a
	parent that repeats its children’s totals will double-count. Trackio does not
	maintain a model pricing catalog; instrumentation should supply the actual cost.</p> <p>A span is reported as failed when its <code>status</code> is <code>error</code> or <code>failed</code>, or when it
	carries an <code>error</code>. For spans derived from messages, a tool result marks its
	operation failed when the message sets <code>is_error</code>, <code>error</code>, or an error <code>status</code>;
	OpenAI-style tool results carry no success signal, so those operations are left
	without a status rather than assumed successful.</p> <!--[1--><h2 class="relative group"><a id="inspect-traces-from-the-cli" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#inspect-traces-from-the-cli"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>Inspect traces from the CLI</span></h2><!--]--><!----> <p>The dashboard is not the only way to read traces back. The CLI works against
	local data, or against a Space with <code>--space</code>:</p> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----> <div class=" absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0 "><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent;"></div> Copied</div><!----></button><!----></div> <pre class="language-bash "><!---->trackio list traces --project research-agent
	trackio list traces --project research-agent --search <span class="hljs-string">"rate limit"</span>
	trackio get trace --project research-agent --trace-id <<span class="hljs-built_in">id</span>>
	trackio get trace-summary --project research-agent<!----></pre></div><!----> <p><code>trackio get trace</code> prints the execution tree with per-span latency, model,
	tokens, cost, and errors. <code>trackio get trace-summary</code> groups every span by
	operation name and reports calls, errors, average and worst-case latency, token
	usage, and cost — useful for finding which operation dominates spend or fails
	most often. Both accept <code>--json</code>.</p> <p>For anything else, <code>spans</code> is a JSON column, so <code>json_each</code> works with <a href="./cli_commands"><code>trackio query project</code></a>:</p> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----> <div class=" absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0 "><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent;"></div> Copied</div><!----></button><!----></div> <pre class="language-bash "><!---->trackio query project --project research-agent --sql <span class="hljs-string">"
	SELECT json_extract(s.value, '\$.name') AS operation,
	SUM(COALESCE(json_extract(s.value, '\$.usage.input_tokens'), 0)) AS input_tokens
	FROM traces, json_each(traces.spans) AS s
	GROUP BY operation ORDER BY input_tokens DESC"</span><!----></pre></div><!----> <!--[1--><h2 class="relative group"><a id="viewing-traces-on-the-hugging-face-hub" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#viewing-traces-on-the-hugging-face-hub"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>Viewing traces on the Hugging Face Hub</span></h2><!--]--><!----> <p>Every logged trace is also written as an agent session <code>.jsonl</code> file, in the
	format the Hub’s agent trace viewer renders. When Trackio runs on a Space, the
	bucket is mounted at <code>/data</code>, so these land in the bucket under <code>traces/{project}/{run}/{trace_id}.jsonl</code> — open one from the bucket’s file
	browser to step through the conversation, its tool calls, and their results.</p> <p>Trackio emits <a href="https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/session-format.md" rel="nofollow">Pi’s session
	format</a> (version 3), which the Hub supports natively. The Hub also documents a Session
	Trace Simple Format, but files written to that spec are not currently rendered
	by the viewer.</p> <p>The session files are a rendering artifact, never the source of truth. The <code>traces</code> table stays authoritative, and everything else on this page — search,
	the span tree, <code>trace-summary</code>, direct SQL — reads from it. What the session
	file carries is the linear conversation, enriched from the spans with the
	details the viewer can display:</p> <table><thead><tr><th>From the span</th><th>Appears in the session as</th></tr></thead><tbody><tr><td><code>model</code> on a generation</td><td>a <code>model_change</code> entry</td></tr><tr><td><code>usage</code>, <code>cost_usd</code></td><td><code>usage</code> on the assistant turn it produced</td></tr><tr><td><code>status</code>, <code>error</code> on a tool</td><td><code>isError</code> on the tool result</td></tr><tr><td><code>input</code>, <code>output</code> on a tool</td><td>the <code>toolCall</code> arguments and result, for traces with no <code>messages</code></td></tr></tbody></table> <p>Token usage is paired with the assistant turn that produced it rather than
	repeated on every turn, so the viewer does not double-count. Span hierarchy, <code>duration_ms</code>, per-span <code>metadata</code>, and the <code>kind</code> of non-tool spans have no
	place in the format and stay in SQLite.</p> <p>Session files sit beside the <code>trackio/</code> prefix rather than inside it, so <code>trackio</code> CLI commands that sync a bucket down do not pull a second copy of
	every trace. Set <code>TRACKIO_TRACE_SESSIONS_DIR</code> to write them somewhere else.</p> <!--[1--><h2 class="relative group"><a id="trace-level-metadata" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#trace-level-metadata"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>Trace-level metadata</span></h2><!--]--><!----> <p>Spans are the preferred source for latency, cost, and status. When a trace has no
	spans, or its spans omit these values, the dashboard falls back to these <code>metadata</code> keys:</p> <table><thead><tr><th>Key</th><th>Used for</th></tr></thead><tbody><tr><td><code>status</code></td><td>Trace status, unless a span reports an error</td></tr><tr><td><code>duration_ms</code>, <code>latency_ms</code></td><td>Trace latency</td></tr><tr><td><code>cost_usd</code></td><td>Trace cost, when no span reports a cost</td></tr></tbody></table> <!--[1--><h2 class="relative group"><a id="search" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#search"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>Search</span></h2><!--]--><!----> <p>Trace search matches message content, trace metadata, and each span’s <code>id</code>, <code>name</code>, <code>kind</code>, <code>model</code>, <code>status</code>, <code>error</code>, and <code>metadata</code>. Span <code>input</code> and <code>output</code> payloads are not indexed: they routinely repeat the whole conversation
	for every generation, so indexing them would multiply stored trace size for
	little search value.</p> <p>Nested Trackio media values in messages, metadata, span input, or span output are
	stored alongside the trace, and images are rendered inline in the inspector.</p> <a class="!text-gray-400 !no-underline text-sm flex items-center not-prose mt-4" href="https://github.com/gradio-app/trackio/blob/main/docs/source/traces.md" target="_blank"><svg class="mr-1" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M31,16l-7,7l-1.41-1.41L28.17,16l-5.58-5.59L24,9l7,7z"></path><path d="M1,16l7-7l1.41,1.41L3.83,16l5.58,5.59L8,23l-7-7z"></path><path d="M12.419,25.484L17.639,6.552l1.932,0.518L14.351,26.002z"></path></svg><!----> <span><span class="underline">Update</span> on GitHub</span></a><!----> <p></p><!--]--><!----><!--]--><!--]--><!--]--> <!--[-1--><!--]--><!--]-->

	<script>
	{
	__sveltekit_199qs9p = {
	base: "/docs/trackio/v0.36.0/en",
	assets: "/docs/trackio/v0.36.0/en"
	};

	const element = document.currentScript.parentElement;

	Promise.all([
	import("/docs/trackio/v0.36.0/en/_app/immutable/entry/start.DogV0ES3.js"),
	import("/docs/trackio/v0.36.0/en/_app/immutable/entry/app.CrFflN0e.js")
	]).then(([kit, app]) => {
	kit.start(app, element, {
	node_ids: [0, 22],
	data: [null,null],
	form: null,
	error: null
	});
	});
	}
	</script>

Xet Storage Details

Size:: 32.1 kB
Xet hash:: 422f5b64fc70b99c6388c7adcbd1d5a86189eb82434d6b0a1270ed83a69985dc

Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.