SpanHound

SpanHound

捕获本地 Agent 追踪记录。向 MCP 客户端询问发生了什么。 SpanHound （原名 mcp-trace-inspector）可捕获受支持的 Python Agent 调用，通过本地 OTLP/HTTP 接收 OpenTelemetry 数据，并提供只读 MCP 工具，用于查看故障、审批决策、令牌用量和运行对比。它会读取 JSONL 跨度数据和 OTLP JSON 导出文件，详情见用户指南，其中包括来自 agent-harness 的追踪记录。

演示：观看 48 秒完整视频 · 阅读可复现的案例。这是一条脚本化的回归追踪记录，并非实时模型基准测试。

该项目的具体起因是一次 shell 边界回归问题：harness 拦截了 cat ../outside.txt，但旧追踪记录只记下调用了 run_shell， 没有记录返回的诊断信息。现在，SpanHound 和 harness 都会保留并查询这条范围受限的错误信息。

一条命令即可试用

uvx spanhound demo

SpanHound demo — recorded agent failure
Tool: run_shell
Failure: error: shell path escapes workspace root: '../outside.txt'
Approval: approve (auto)
Trace: 563e779ee8fa2d7069fc63ed2cf9c8ec (6 spans)

演示展示了捆绑的脚本化回归追踪记录中的一次 run_shell 失败及其审批证据。无需克隆仓库、账号、追踪后端或 MCP 客户端。若要检查自己的追踪记录，请将 SpanHound 指向包含 JSONL 跨度数据或已保存 OTLP JSON 导出文件的目录：

uvx spanhound --trace-dir /path/to/traces --check

--check 会打印找到的运行记录后退出。按照下方的配置连接 MCP 客户端，即可询问有关这些运行记录的问题。

浏览仓库中的样例数据

git clone https://github.com/abhishekash/spanhound.git
cd spanhound
uvx --from . spanhound --trace-dir examples --check

--check 也会报告目录缺失，或完整的 JSONL、OTLP JSON 记录格式错误。

若要试用 OTLP JSON 导出文件，请使用 --trace-dir tests/fixtures 运行相同的命令。 样例导出文件包含一次模型调用、令牌 用量、一次工具调用和一个异常。

捕获你自己的跟踪

对于 Python Agent，请在与 Agent 相同的环境中安装 SpanHound 的可选自动检测，然后通过 SpanHound 运行它：

python -m pip install 'spanhound[auto]'
spanhound run --trace-dir ./traces -- python agent.py

此命令会启动并停止本地接收器、配置 OTLP 导出，并在无需更改 agent.py 的情况下捕获受支持的库调用。可选软件包包含针对 OpenAI、Anthropic、OpenAI Agents、HTTPX 和 Requests 的检测。如果未生成任何跨度，它会发出提示。Python Agent 和 SpanHound 必须共用一个环境；对于 uv 项目，请使用 uv add 'spanhound[auto]' 和 uv run spanhound run -- python agent.py。 参阅 Python 捕获指南。

对于其他运行时，或已导出 OpenTelemetry 跟踪的 Agent，请在一个终端中启动接收器：

uvx spanhound collect --trace-dir ./traces

将已使用 OpenTelemetry 跟踪导出器的 Agent 指向接收器，然后运行 Agent：

export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://127.0.0.1:4318/v1/traces
export OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf
# Start your instrumented agent here.

SpanHound 会将每个已接收的 OTLP/HTTP 跟踪请求存储为本地 JSON 文件。运行 uvx spanhound --trace-dir ./traces --check 查看捕获的运行，然后将 MCP 客户端连接到该文件夹。接收器在回环地址上接受 OTLP/HTTP JSON 或 protobuf；它不会为 Agent 添加检测。关于限制和隐私，请参阅捕获指南。

适用场景

如需实时查看本地 Codex/Claude Code 会话和收到的 OTLP 遥测数据（包括终端和浏览器界面），请试试 Agent Observatory。SpanHound 通过 MCP 使用 JSONL 和 OTLP JSON 文件进行跟踪调查。

如果你想通过 MCP 在本地查看跟踪，而无需设置跟踪后端，请使用此工具。你可以通过一条命令捕获受支持的 Python 库调用、接收其他运行时发送的 OTLP/HTTP，或读取受支持的 JSONL 或 OTLP JSON 格式。专项查询包括已记录的审批决策、有限范围的故障诊断和运行对比。

MCP Agent Trace Inspector 会将步骤记录到本地 SQLite 数据库，并提供仪表板和导出功能。SpanHound 会自动检测受支持的 Python 库，或接收 OTLP/HTTP 跟踪，然后通过 MCP 查询捕获的文件。它不会自动跟踪任意 Agent 函数或审批。

对于存储在 Jaeger、Tempo 或 Traceloop 中的跟踪，请使用 OpenTelemetry MCP Server 等连接后端的工具。如需跟踪 UI、检测和评估功能，请参阅 Phoenix。SpanHound 不会读取特定于后端的 JSON 导出文件。

AI 原生用例

Agent 运行期间的问题	MCP 工具	返回的证据
“昨天的运行为什么停滞了？”	list_runs → slowest_spans	运行 ID，以及耗时最长的模型或工具跨度。
“我拒绝写入后，Agent 是否仍有操作？”	approval_log → span_tree	记录的决策及后续执行路径。
“这次运行用了多少模型令牌？”	token_usage → span_tree	运行级用量总计，以及作为上下文的跨度树。
“哪个工具出错或超时了？”	failure_report / tool_stats	已脱敏的诊断信息、错误率、拒绝次数和 p95 延迟。
“谁／什么获准执行操作？”	security_audit	调用方、租户、服务来源、风险及缺失证据的发现。
“当前运行正在发生什么？”	recent_activity	基于游标轮询新写入的跨度。
“这个模型／版本是否出现退化？”	compare_runs	成本、延迟、令牌、工具调用和失败情况的差异。

这些工具会读取已存储的追踪记录，也可以轮询正在写入的文件，但不会推送事件，也不会从最终回答中推断意图。请先阅读安装和用户指南，然后查看真实追踪样例和工具说明，了解查询约定。

安装和运行

uvx spanhound --trace-dir ./traces
# or, for local development:
git clone https://github.com/abhishekash/spanhound
cd spanhound
uvx --from . spanhound --trace-dir ./traces

对于支持 MCP Bundles 的桌面客户端，请从最新版本下载 .mcpb 资源，并在客户端中安装下载的文件；下载链接不会打开网页。在 Claude Desktop 中，选择 Settings → Extensions → Advanced settings → Install Extension…，然后选择 .mcpb 文件。此捆绑包会提示你选择本地追踪文件夹。 首次运行时，它会使用 UV 安装 Python 依赖项。SpanHound 会在本地读取该文件夹；连接的客户端会收到其 MCP 工具返回的证据。

如果你之前运行的是 uvx mcp-trace-inspector，请将该命令改为 uvx spanhound，以获取此版本。旧的 PyPI 发行版仍为 0.3.1；新软件包保留了 Python 导入路径和命令别名，供明确安装 spanhound 的客户端使用。

客户端配置

Claude Desktop（claude_desktop_config.json）：

{
  "mcpServers": {
    "agent-traces": {
      "command": "uvx",
      "args": ["spanhound", "--trace-dir", "/path/to/traces"]
    }
  }
}

pi（~/.pi/agent/settings.json）：

{
  "mcpServers": {
    "agent-traces": {
      "command": "uvx",
      "args": ["spanhound", "--trace-dir", "/path/to/traces"]
    }
  }
}

agent-harness（作为受控工具挂载）：

harness run "Why was my last run slow?" --mcp "uvx spanhound --trace-dir ./traces"

工具

工具	适用场景
list_runs	开始使用时——查看近期运行的任务、模型、时长、成本和决策次数
run_summary	快速查看单次运行（接受追踪 ID 前缀）
span_tree	“Agent 实际做了什么？”——查看运行的嵌套结构
slowest_spans	“为什么这么慢？”——按时长列出前 k 个跨度
approval_log	人机协同（HITL）审计——记录每次批准／拒绝／编辑、决策者及理由
token_usage	成本相关问题——汇总多次运行或按单次运行统计
search_spans	按工具名称、文件路径、“denied”等查找跨度
failure_report	查找可采取行动、范围有限且已脱敏的错误和失败的工具调用。
tool_stats	按调用量、错误率、拒绝次数和延迟对工具进行排序。
security_audit	审计调用方身份、租户、服务来源、风险和审批证据。
recent_activity	运行期间使用游标轮询新跨度。
compare_runs	比较所选追踪记录，检查不同模型或版本之间的退化情况。

工具说明以提示词形式编写（说明何时使用，而不只是说明功能）——对于由 Agent 调用的工具而言，说明就是接口。

示例会话（真实追踪样例）

> list_runs
[{ "trace_id": "f920798dd2558fcb84f9977736432a8b", "task": "Summarize the workspace's notes…",
   "tool_calls": 4, "human_decisions": 2, "stopped_reason": "completed" }]

> approval_log
[{ "tool": "write_file", "decision": "approve", "approver": "auto", … },
 { "tool": "run_shell",  "decision": "approve", "approver": "auto", … }]

设计

traces/*.jsonl ──┐
traces/*.json  ──┴─▶ mcp_trace.core (local query functions)
                          │
                   mcp_trace.server (MCP adapter)
                          │
                    stdio (JSON-RPC)

• 核心层与服务层分离：所有逻辑都是基于已解析跨度的纯函数；MCP 层只解析参数并将结果编码为 JSON。测试会覆盖这两个层级。
• trace_id 前缀：Agent 难以处理完整的 32 位十六进制 ID；每个工具都接受前缀。
• 限制输出：诊断信息会被截断，明显的凭据会在查询结果离开服务前被脱敏。
• 如实统计成本：如果任何模型跨度缺少成本，或标记定价不可用，token_usage 就会返回 cost_known: false 和 null 成本；绝不会把未知定价显示为 $0。
• 游标轮询：recent_activity 让快照读取器在运行仍在写入跨度时也能派上用场。
• 演示样例（examples/example_trace.jsonl）来自一次真实的 Agent 框架运行，并非手写。

已知限制

• 仅支持 MCP stdio 传输（Streamable HTTP 加经身份验证的远程访问是下一个传输边界）
• 实时轮询会重新读取快照；它不是推送订阅
• 安全审计只能报告追踪数据生成器记录的身份／来源信息
• 工具仅支持读取；追踪数据修改（注释）已列入路线图
• Python 查询模块和服务模块可通过 mcp_trace 使用；较早的导入和命令别名仍为现有客户端保留。

首次运行反馈

告诉我们你的试用体验： 你使用的 MCP 客户端或追踪数据生成器、你尝试回答的问题，以及 任何缺失的证据。如果文件加载失败，请分享一段已脱敏的摘录。

许可证

MIT