Spoor

Spoor

Spoor 用几百个 token 告诉 AI Agent，你的服务发生了什么变化，以及变化从哪里开始。

网站：telespoor.com

Spoor 是面向可观测性后端的开源 MCP 服务和命令行工具，支持 VictoriaMetrics 技术栈、Prometheus、Loki、Tempo 和 New Relic。出现故障时，Agent 会询问 Spoor：“过去 30 分钟发生了什么变化？” 随后会收到一份简短的排序结果，涵盖指标、日志和追踪，并将故障起始服务排在首位，同时标明其在其他服务中引发的连带影响。

Spoor（名词）：动物留下的足迹或踪迹。Spoor 沿着故障在遥测数据中留下的踪迹，追溯到它的起点。

$ spoor what-changed --since 30m

{
  "summary": "11 change(s) in 3 services. Strongest: payment — Failures start here, in \"POST /charge\" (100% of 100 failed traces). Also: payment — Span \"POST /charge\" errors 0.2% → 43.7% (229 spans). … Errors not significantly up (not new) in: product-catalog, recommendation, ad.",
  "findings": [
    {"service": "payment",  "signal": "traces",  "kind": "error_origin",    "score": 0.99, "title": "Failures start here, in \"POST /charge\" (100% of 100 failed traces)"},
    {"service": "payment",  "signal": "logs",    "kind": "new_log_pattern", "score": 0.94, "title": "New error log pattern: \"charge failed: card processor returned <N> for order <N>\""},
    {"service": "payment",  "signal": "metrics", "kind": "error_rate_up",   "score": 0.92, "title": "Error rate up: 0.2% → 40.5%", "onset": "2026-10-16T09:50:00Z"},
    {"service": "checkout", "signal": "logs",    "kind": "spiking_log_pattern", "score": 0.74, "title": "Error log pattern spiking: \"call to payment.Charge failed with status <N>\" — originates in payment"}
  ],
  "coverage": {"metrics": "ok", "logs": "ok", "traces": "ok"}
}

发现结果会附带其背后查询的证据链接（token 预算允许时），方便人工一键核查 Agent 的工作。

为什么使用它

在微服务故障中，出问题的服务及其所有调用方都会亮起告警。只有原始查询工具的 Agent 必须自行决定查询什么、对照“正常”情况、翻阅结果，并判断哪个服务是原因、哪些只是受到连带影响。这会消耗工具调用和 token，而且往往会误判最显眼的症状，或将一直存在的错误归咎于故障。

Spoor 使用简单、确定性的 Go 代码完成这些工作，并将结论的依据交给 Agent：

• 跨信号： 请求率、错误率、延迟、CPU、内存和消费者滞后；日志中的新增错误、激增错误及错误量；同一时间窗口内、相对于同一基线的每个跨度错误和延迟。
• 专为真实日志打造： 仅 ID、数值、堆栈追踪或日志前缀不同的消息会被视为同一种错误；JSON 错误会根据其 message 和 code 字段解析；服务可以使用不同的级别字段，或将级别写在文本中；spoor doctor 会查找你的字段并写入配置。
• 原因与连带影响： 追踪树会显示故障从何处开始，以及延迟增加的位置。仅受影响的调用方会被降级排序，并标记为 — originates in payment。
• 明确指出持续存在的错误： 已经存在的错误会列在 steady_errors 中，并标注“不是新问题”，避免 Agent 将其误认为故障原因。
• 限制输出： 每个工具都接受 budget_tokens（默认值为 800）。
• 如实报告缺失数据： coverage 会说明后端是否故障或无数据、基线是否为空、错误筛选条件是否未匹配任何内容，或日志行是否缺少服务或级别字段。“没有变化”绝不会被用来代替“无法查看”。
• 不使用内部大模型、只读、脱敏： 相同输入会产生相同输出；只会调用查询端点；所有文本字段在输出前都会清除电子邮件地址、令牌、IP 地址和生成的 ID。

评测结果

基准测试 会以无头模式运行 Claude Code，针对六个事件（五个故障和一个无故障对照）各测试五次：一次仅使用官方 VictoriaMetrics MCP 服务，另一次则额外加入 Spoor。 在 Claude Haiku 上，共进行了 60 次相互隔离的会话：

	官方 Victoria MCP 服务	+ Spoor
故障场景中正确定位根因	19/25	25/25
所有场景中答案正确（包括“没有问题”）	23/30	30/30
每次调查的工具调用数中位数	24	10
耗时中位数	55 秒	23 秒
总成本	$0.60	$0.19（−68%）

这些是合成事件，且只使用了一个小型模型，因此请将其视为第一项数据。

在真实生产日志上（约 25 个服务，格式混合，只读回放）：摘要比其取代的原始证据缩小了 99.8%，候选项为 0 个，而 v0.1.1 有 4 个；摘要中的基线计数与独立查询结果完全一致。它并不比四条手写查询更快（28 秒 vs 26 秒），真实事件中的准确率尚未测量。

测试方法、各场景结果、生产回放和注意事项：docs/benchmark.md。

快速开始

需要 Go 1.25+、Docker 和 jq。约需五分钟。

git clone https://github.com/asinha07/spoor && cd spoor
make it-up          # empty VictoriaMetrics, VictoriaLogs, VictoriaTraces in Docker
make demo-data      # six synthetic incidents; ground truth in scenarios/out/
make build

T=scenarios/out/payment-failure.truth.json
./bin/spoor what-changed --since $(jq -r .since $T) --until $(jq -r .until $T) --pretty

将其连接到 Claude Code：

claude mcp add spoor \
  -e SPOOR_METRICS_URL=http://localhost:8428 \
  -e SPOOR_LOGS_URL=http://localhost:9428 \
  -e SPOOR_TRACES_URL=http://localhost:10428 \
  -- "$PWD/bin/spoor" serve

在 spoor 目录中运行（或添加 -s user 以在所有位置注册），然后询问 Claude：“商店里有东西出故障了。发生了什么变化？问题最初出现在哪里？”

在你自己的后端上，先运行 spoor doctor --since 15m：它会检查 Spoor 能看到什么，并提供配置建议。 其他客户端、仅使用 Grafana 的访问方式等内容：入门指南。

后端

每种信号通过 type: 选择后端，也可以混合使用：

	指标	日志	追踪
VictoriaMetrics 技术栈	VictoriaMetrics	VictoriaLogs	VictoriaTraces
Grafana 技术栈	Prometheus、Mimir、Thanos	Loki	Tempo
New Relic	事务事件（NRQL）	日志事件	Span 事件

metrics: {type: prometheus, url: http://prometheus:9090}
logs:    {type: loki, url: http://loki:3100}
traces:  {type: tempo, url: http://tempo:3200}

设置方法及各后端的差异（Tempo 统计数据经过采样；New Relic 的 Span 变化需要与服务指标一致）：后端。

工具

工具	返回内容
what_changed	汇总所有信号中的变化并排序，标注原因／回声归因；可查询单个服务或全部服务。建议从这里开始。
new_errors	新出现或激增的错误日志模式，包含计数、首次出现时间和已脱敏示例。
trace_diff	变慢或开始失败的 Span 名称，以及示例追踪 ID。
list_services	时间窗口内的服务，以及每个服务有哪些信号数据。

输入：service、since、until、baseline（previous、1d、7d）、budget_tokens。 完整参考：docs/tools.md。

工作原理

flowchart LR
    Agent[AI agent / CLI] -->|MCP| S[Spoor]
    S -->|"PromQL / NRQL"| M[(VictoriaMetrics, Prometheus, New Relic)]
    S -->|"LogsQL / LogQL / NRQL"| L[(VictoriaLogs, Loki, New Relic)]
    S -->|"LogsQL / TraceQL / NRQL"| T[(VictoriaTraces, Tempo, New Relic)]
    S -->|"ranked digest ≤ budget"| Agent

对于一个时间窗口和基线（默认使用该窗口之前的六个窗口），Spoor 会使用稳健 z 分数为每个指标评分，使用 Poisson 检验比较错误日志模式，比较 Span 错误率和 p95，沿失败追踪遍历到每次故障开始的 Span，提高得到多个信号确认的变化的权重，并将结果裁剪到令牌预算以内。详情：架构 · 评分与归因。

为团队运行

spoor serve --http :8080 --auth-token … 会通过支持流式传输的 HTTP 提供 MCP，并使用 bearer-token 身份验证，同时提供 /healthz 和 Prometheus /metrics。可直接使用的加固版清单：

• Kubernetes（Kustomize）：deploy/kubernetes/
• Docker Compose：deploy/docker/
• systemd：deploy/systemd/

安全性、容量规划、监控和升级：生产环境指南。

在 OpenTelemetry Demo 上验证

在 OpenTelemetry Demo v3.1.0（约 20 个真实服务）上，50% 的支付失败被诊断为“payment：故障始于 charge”，checkout 和 frontend 错误被标记为“源自 payment”（732 个 token）；adHighCpu 故障则被诊断为单一问题：“ad：CPU 从 0.07 升至 3.97 核”（192 个 token）。复现方法：deploy/demo/。

文档

快速入门	安装、试用、连接 Agent
生产环境	Kubernetes、Docker、systemd、安全、监控
后端	VictoriaMetrics 技术栈、Prometheus、Loki、Tempo、New Relic
配置	所有选项以及常见设置方案
工具	输入和响应格式
架构 · 工作原理	设计和评分
基准测试 · 对比	为什么使用它，以及还有哪些选择
故障排除 · 常见问题	遇到异常时的处理方法

状态和局限

早期版本（1.0 之前）。工具输出字段在次要版本间仍可能变化；请参阅变更日志。

• 评分是在 VictoriaMetrics 技术栈上开发并进行基准测试的。Prometheus、Loki 和 Tempo 已通过针对真实容器的相同场景测试；New Relic 已在一个真实账户上检查。Tempo 统计数据采用抽样方式，只有在服务指标一致时才会报告 New Relic 的 span 变化；请参阅后端。
• 归因故障原因及关联现象需要 traces；没有 traces 时，Spoor 仍会对指标和日志变化进行排序。
• 每次读取的归因最多处理 50,000 行 span；在非常繁忙的系统中，trace 可能会被截断。
• 基准测试使用作者编写的合成故障和一个模型；请将其视为初步数据点，并在依赖它之前，使用 bench/replay.py 重放你自己的历史故障。
• 指标和 traces 按服务查询；对于大型系统，请在已知服务时传入 service。

更多信息请参阅 how-it-works.md。

路线图

后续工作：提高对带标签真实故障的准确度，支持“自上次部署以来”的时间窗口，添加 Datadog 和 Elasticsearch 后端，以及通过 TraceQL 指标获取精确的 Tempo 统计数据。完整清单以及明确不在范围内的内容： docs/roadmap.md。

参与贡献

欢迎提交问题和拉取请求。make test 只需要 Go；请参阅 CONTRIBUTING.md。 安全问题请参阅：SECURITY.md。

许可证

Apache-2.0。请参阅 LICENSE。