Hugging Face's logo

Trackio documentation

跟踪

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

跟踪

Trackio 追踪记录会捕获用户请求、助手的响应以及生成该响应所涉及的操作。在仪表板中打开 Traces 页面，即可搜索请求、检查模型和工具操作，并查看延迟、令牌、成本和状态的汇总信息。

记录对话

将 Trace 与 OpenAI 风格的消息一起传递给 trackio.log()：

import trackio

trackio.init(project="research-agent")
trackio.log(
    {
        "trace": trackio.Trace(
            messages=[
                {"role": "user", "content": "Find agent training datasets."},
                {"role": "assistant", "content": "Here are three datasets..."},
            ],
            metadata={"session_id": "session-123", "environment": "production"},
        )
    }
)
trackio.finish()

消息可以包含 tool_calls 和 tool 结果。当跟踪中没有显式的 span 时，仪表板会将这些调用和结果配对为工具操作，以便于检查。

添加执行跨度

在需要获取计时、层级结构、模型使用情况、成本或操作状态时，请使用 spans。每个 span 都是一个字典。最小字段为 id、name 和 kind：

trackio.Trace(
    messages=messages,
    spans=[
        {
            "id": "research",
            "name": "answer-research-question",
            "kind": "span",
            "start_time": "2026-08-19T12:00:00Z",
            "end_time": "2026-08-19T12:00:03Z",
            "status": "success",
        },
        {
            "id": "generation-1",
            "parent_id": "research",
            "name": "provider-request",
            "kind": "generation",
            "start_time": "2026-08-19T12:00:00Z",
            "end_time": "2026-08-19T12:00:01.2Z",
            "model": "my-model",
            "input": {"messages": messages},
            "output": {"text": "I will search for datasets."},
            "usage": {"input_tokens": 8439, "output_tokens": 188},
            "cost_usd": 0.0042,
            "status": "success",
        },
        {
            "id": "tool-1",
            "parent_id": "research",
            "name": "hf search",
            "kind": "tool",
            "start_time": "2026-08-19T12:00:01.3Z",
            "end_time": "2026-08-19T12:00:02Z",
            "input": {"query": "agent training datasets"},
            "output": {"datasets": ["example/dataset"]},
            "status": "success",
        },
    ],
)

支持的 span 字段：

字段描述
id在跟踪中唯一的标识符
parent_id可选的父级 span ID；用于创建执行树
name检查器中显示的操作名称
kindspan、generation 或 tool
start_time, end_time用于推导延迟的 ISO-8601 时间戳
duration_ms时间戳不可用时的可选时长
status通常为 success 或 error
error结构化或文本形式的错误详情
input, output任何可 JSON 序列化的操作负载
model用于生成的模型标识符
usageinput_tokens、output_tokens 以及可选的 total_tokens
cost_usd此操作的成本（以美元计）
metadata附加操作元数据

Trace 延迟是指从最早的 span 开始到最晚的 span 结束之间的实际经过时间；如果没有任何 span 包含 end_time，则改用单个 duration_ms 的最大值。Token 和成本总计是对各个 span 上的值进行求和，因此 usage 和 cost_usd 应描述本地操作，而不是父级聚合值——如果父级重复了子级的总计，会导致重复计算。Trackio 不维护模型定价目录；插桩代码应提供实际成本。

当 status 为 error 或 failed，或者 span 携带 error 时，该 span 会被报告为失败。对于源自消息的 span，如果消息设置了 is_error、error 或错误 status，则工具结果会将其操作标记为失败；OpenAI 风格的工具结果不包含成功信号，因此这些操作不会假定成功，而是保持无状态。

从 CLI 检查跟踪

仪表盘并不是读取跟踪数据的唯一方式。CLI 可以针对本地数据，或者针对带有 --space 的 Space 进行操作：

trackio list traces --project research-agent
trackio list traces --project research-agent --search "rate limit"
trackio get trace --project research-agent --trace-id <id>
trackio get trace-summary --project research-agent

trackio get trace 会打印执行树，并显示每个 span 的延迟、模型、token 数、成本以及错误信息。trackio get trace-summary 按操作名称对所有 span 进行分组，并报告调用次数、错误数、平均延迟和最差情况延迟、token 用量以及成本——这对于找出哪个操作占用了最多的开销或最常失败非常有用。两者都支持 --json。

对于其他内容，spans 是一个 JSON 列，因此 json_each 可以与 trackio query project 一起使用：

trackio query project --project research-agent --sql "
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"

在 Hugging Face Hub 上查看 traces

每条记录的 trace 同时会写入一个 agent session .jsonl 文件，其格式与 Hub 的 agent trace 查看器所渲染的格式一致。当 Trackio 在 Space 上运行时，bucket 会挂载到 /data，因此这些文件会存储在 bucket 的 traces/{project}/{run}/{trace_id}.jsonl 路径下——通过 bucket 的文件浏览器打开其中一个文件，即可逐步查看对话、其工具调用以及相应的结果。

Trackio 会输出 Pi 的会话格式（版本 3），Hub 原生支持该格式。Hub 还记录了 Session Trace Simple Format，但按照该规范写入的文件目前无法在查看器中渲染。

会话文件是渲染产物，绝非权威数据源。traces 表始终具有权威性，本页面上的所有内容——搜索、span 树、trace-summary、直接 SQL——均从中读取。会话文件承载的是线性对话，并从 span 中补充了查看器可显示的详细信息：

从跨度在会话中显示为
model 在生成过程中model_change 条目
usage, cost_usdusage 在其生成的助手回合中
工具上的 status、error工具结果中的 isError
工具上的 input、output对于没有 messages 的跟踪，toolCall 的参数和结果

Token 用量与产生它的助手轮次配对，而非在每一轮中重复，因此查看器不会重复计算。Span 层级、duration_ms、每个 span 的 metadata 以及非工具 span 的 kind 不属于该格式的一部分，仍保留在 SQLite 中。

会话文件位于 trackio/ 前缀旁边，而不是在其内部，因此用于将存储桶同步到本地的 trackio CLI 命令不会拉取每个 trace 的第二份副本。设置 TRACKIO_TRACE_SESSIONS_DIR 可将它们写入其他位置。

跟踪级别元数据

Span 是延迟、成本和状态的首选来源。当 trace 没有 span，或其 span 中省略了这些值时，仪表板会回退到以下 metadata 键：

密钥用于
status除非某个 span 报告了错误，否则跟踪状态
duration_ms, latency_ms跟踪延迟
cost_usd未报告成本的 Span 的 Trace 成本

搜索

Trace 搜索会匹配消息内容、Trace 元数据，以及每个 Span 的 id、name、kind、model、status、error 和 metadata。Span 的 input 和 output 负载不会被索引：由于每次生成时通常会重复整个对话，因此索引这些负载会成倍增加存储的 Trace 大小，而搜索价值却很小。

消息、元数据、span 输入或 span 输出中嵌套的 Trackio 媒体值会与 trace 一起存储，并且图像会在检查器中内联渲染。

Update on GitHub

←超参数扫描 工件→