Spoor

Spoor

Spoor は、サービスで何が変わったのか、そしてどこで始まったのかを、わずか数百トークンで AI エージェントに伝えます。

ウェブサイト：telespoor.com

Spoor は、オブザーバビリティのバックエンド（VictoriaMetrics スタック、Prometheus、Loki、Tempo、New Relic）向けのオープンソースの MCP サーバー兼 CLI です。何かが壊れたとき、エージェントは 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"}
}

調査結果には、その根拠となったクエリへのリンクが含まれます（トークン予算に余裕がある場合）。そのため、人間はワンクリックでエージェントの作業を確認できます。

導入する理由

マイクロサービスの障害では、故障したサービスとその呼び出し元がすべて異常を示します。生のクエリツールしか持たないエージェントは、何をクエリするかを判断し、「通常」の状態と自分で比較し、結果を順に調べて、どのサービスが原因で、どれが波及症状なのかを突き止める必要があります。ツール呼び出しとトークンを浪費し、最も目立つ症状や、以前から存在していたエラーを原因と誤認することもよくあります。

Spoor は、その作業をシンプルで決定論的な Go で処理し、結論の根拠をエージェントに渡します。

• シグナル横断型： リクエストレート、エラーレート、レイテンシ、CPU、メモリ、コンシューマーラグ、新たに発生したエラーや急増したエラー、ログのエラー件数、スパンごとのエラーとレイテンシを、同一期間・同一ベースラインで分析します。
• 実際のログに対応： ID、値、スタックトレース、ログプレフィックスだけが異なるメッセージは、1つのエラーとして扱います。JSON エラーは message フィールドと code フィールドで読み取ります。サービスごとに異なるレベルフィールドを使う場合や、テキスト内にレベルを記載する場合にも対応します。spoor doctor はフィールドを検出し、設定を書き込みます。
• 原因と波及症状を区別： トレースツリーによって、障害の発生箇所とレイテンシが加わった箇所を確認できます。単に影響を受けているだけの呼び出し元は順位が下がり、— payment に起因 とラベル付けされます。
• 継続中のエラーを明示： 以前から発生しているエラーは steady_errors として「新しい問題ではない」と示されるため、エージェントがそれらを原因と誤認することを防ぎます。
• 出力を制限： すべてのツールで budget_tokens を指定できます（既定値は800です）。
• データ不足も正直に報告： coverage は、バックエンドの障害やデータの欠如、空のベースライン、エラーフィルターに一致する項目がない場合、または行にサービスフィールドやレベルフィールドがない場合を示します。「変化なし」が「確認できない」の代わりになることはありません。
• 内部に LLM なし、読み取り専用、機密情報をマスキング： 同じ入力には同じ出力を返します。呼び出すのはクエリエンドポイントのみです。テキストフィールドはすべて、外部に出る前にメールアドレス、トークン、IP アドレス、生成 ID をマスキングします。

測定結果

ベンチマークでは、6件のインシデント（障害5件と障害なしの対照ケース）について、Claude Codeをヘッドレスで実行し、各ケースを5回ずつ、公式のVictoriaMetrics MCPサーバーのみの場合とSpoorを追加した場合で比較します。 Claude Haikuで、分離された60のセッションを実施しました。

	公式Victoria MCPサーバー	＋ Spoor
根本原因を正しく特定、障害シナリオ	19/25	25/25
正解、障害なしを含む全シナリオ	23/30	30/30
調査あたりのツール呼び出し回数の中央値	24	10
所要時間の中央値	55 s	23 s
合計コスト	$0.60	$0.19（−68%）

合成インシデントと小規模なモデルを使った結果のため、最初のデータポイントとしてご覧ください。

実際の本番ログ（約25サービス、形式混在、読み取り専用の再生）では、ダイジェストのサイズは置き換える生の証拠より99.8%小さく、候補はゼロでした（v0.1.1では4件）。ベースラインの件数は独立したクエリと完全に一致しました。手書きのクエリ4件より速くはなく（28 s 対 26 s）、実際のインシデントに対する精度はまだ測定されていません。

手法、シナリオごとの結果、本番環境での再生、注意事項については、docs/benchmark.mdをご覧ください。

クイックスタート

Go 1.25+、Docker、jqが必要です。所要時間は約5分です。

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）	ログイベント	スパンイベント

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

セットアップとバックエンドごとの違い（Tempoの統計情報はサンプリングされます。New Relicのスパンの変更は、サービスのメトリクスとの一致が必要です）：バックエンド。

ツール

ツール	戻り値
what_changed	原因／波及の帰属情報を含む、全シグナルにわたる変更のランキング。単一サービスまたは全サービスが対象です。まずはこちらを実行してください。
new_errors	新たに発生した、または急増しているエラーログのパターン。件数、初回検出時刻、マスキング済みの例を含みます。
trace_diff	遅延が増加した、または失敗し始めたスパン名と、トレース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

対象期間とベースライン（デフォルトでは、その直前の6つの期間）について、Spoorはすべてのメトリクスをロバストzスコアで評価し、エラーログのパターンをポアソン検定で比較し、スパンのエラー率とp95を比較します。さらに、失敗したトレースをたどって各失敗が始まったスパンを特定し、複数のシグナルで裏付けられた変更を加点したうえで、結果をトークン予算に収まるように調整します。詳細：アーキテクチャ · スコアリングと帰属。

チームで実行する

spoor serve --http :8080 --auth-token …は、ベアラートークン認証、/healthz、Prometheusの/metricsを備えたストリーミング可能なHTTP経由のMCPを提供します。セキュリティ強化済みのマニフェストをすぐに利用できます。

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

セキュリティ、サイジング、監視、アップグレードについては、**本番環境ガイド**をご覧ください。

OpenTelemetry Demo での検証

OpenTelemetry Demo v3.1.0（実際のサービス約20個）では、決済失敗率が50％のケースで「payment: failures start here, in charge」と返され、checkout と frontend のエラーには「originates in payment」と表示されました（732トークン）。adHighCpu 障害では、単一の調査結果「ad: CPU up 0.07 → 3.97 cores」が返されました（192トークン）。再現するには、deploy/demo/ をご覧ください。

ドキュメント

はじめに	インストール、試用、エージェントの接続
本番環境	Kubernetes、Docker、systemd、セキュリティ、監視
バックエンド	VictoriaMetrics スタック、Prometheus、Loki、Tempo、New Relic
設定	すべてのオプションと一般的な構成例
ツール	入力と応答形式
アーキテクチャ · 仕組み	設計とスコアリング
ベンチマーク · 比較	利用する理由と、ほかの選択肢
トラブルシューティング · FAQ	問題が発生した場合

ステータスと制限事項

初期段階（1.0 未満）です。ツールの出力フィールドはマイナーバージョン間で変更される場合があります。変更履歴をご覧ください。

• スコアリングは VictoriaMetrics スタック上で開発し、ベンチマークを実施しました。Prometheus、Loki、Tempo は実コンテナに対する同じシナリオテストに合格しており、New Relic は実際のアカウント1つで確認済みです。Tempo の統計情報はサンプリングされ、New Relic のスパン変更はサービスメトリクスが一致する場合にのみ報告されます。詳しくはバックエンドをご覧ください。
• 原因／波及の帰属にはトレースが必要です。トレースがない場合でも、Spoor はメトリクスとログの変化を順位付けします。
• 帰属分析では、1回の読み取りあたり最大50,000件のスパン行を読み取ります。非常に高負荷なシステムでは、トレースが途中で切れることがあります。
• ベンチマークでは、著者が作成した合成インシデントと1つのモデルを使用しています。最初のデータポイントとして捉え、これを信頼する前に、bench/replay.py で過去のインシデントを再生してください。
• メトリクスとトレースはサービスごとにクエリされます。大規模な環境では、対象がわかっている場合は service を指定してください。

詳細はhow-it-works.mdをご覧ください。

ロードマップ

次の予定：ラベル付き実インシデントでの精度向上、「最後のデプロイ以降」の時間範囲、Datadog と Elasticsearch のバックエンド、TraceQL メトリクスによる正確な Tempo 統計情報。全項目と、意図的に対象外としている内容については、docs/roadmap.md をご覧ください。

貢献

Issue とプルリクエストを歓迎します。make test の実行に必要なのは Go だけです。CONTRIBUTING.mdをご覧ください。セキュリティ上の問題については、SECURITY.mdをご覧ください。

ライセンス

Apache-2.0。LICENSEをご覧ください。