SpanHound

SpanHound

ローカルエージェントのトレースを記録。何が起きたのかを MCP クライアントに尋ねられます。 SpanHound（旧称 mcp-trace-inspector）は、対応する Python エージェントの呼び出しを記録し、ローカルの OTLP/HTTP 経由で OpenTelemetry を受信して、失敗、承認の判断、トークン使用量、実行の比較に関する読み取り専用の MCP ツールを提供します。ユーザーガイドで説明されている JSONL スパンと OTLP JSON エクスポートを読み込み、agent-harness のトレースにも対応しています。

デモ： 48 秒の動画を見る · 再現可能な事例を読む。これはスクリプトで実行した回帰テストのトレースであり、ライブモデルのベンチマークではありません。

このプロジェクトが生まれた直接のきっかけは、シェル境界の回帰でした。ハーネスは cat ../outside.txt をブロックしていましたが、以前のトレースには run_shell が呼び出されたことしか記録されず、返された診断情報は記録されていませんでした。現在、SpanHound とハーネスはこの制限されたエラーを保持し、検索できるようになっています。

1 つのコマンドで試す

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 クライアントは必要ありません。独自のトレースを調べるには、JSONL スパンまたは保存済みの OTLP JSON エクスポートが入ったディレクトリを SpanHound に指定します。

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 エージェントの場合は、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 エージェントと SpanHound は同じ環境を共有する必要があります。uv プロジェクトでは、uv add 'spanhound[auto]' と uv run spanhound run -- python agent.py を使用してください。Python キャプチャガイドを参照してください。

その他のランタイムや、すでに OpenTelemetry トレースをエクスポートしているエージェントの場合は、まずターミナルでレシーバーを起動します。

uvx spanhound collect --trace-dir ./traces

すでに OpenTelemetry トレースエクスポーターを使用しているエージェントをレシーバーに接続し、エージェントを実行します。

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 を受け付けますが、エージェントに計装機能を追加することはありません。制限事項とプライバシーについては、キャプチャガイドを参照してください。

適した用途

ローカルの Codex／Claude Code セッションと受信した OTLP テレメトリーをターミナルおよびブラウザーでリアルタイムに確認するには、Agent Observatoryをお試しください。SpanHound は、JSONL ファイルと OTLP JSON ファイルを使用し、MCP 経由でトレースを調査できます。

トレースバックエンドを設定せずに、MCP 経由でローカルのトレースを確認したい場合にお使いください。サポート対象の Python ライブラリ呼び出しを 1 つのコマンドでキャプチャする、別のランタイムから OTLP/HTTP を受信する、またはサポート対象の JSONL 形式または OTLP JSON 形式を読み込めます。承認判断の記録、範囲を限定した失敗診断、実行の比較などに特化したクエリを実行できます。

MCP Agent Trace Inspectorは手順をローカルの SQLite データベースに記録し、ダッシュボードとエクスポート機能を提供します。SpanHound は、サポート対象の Python ライブラリを自動計装するか、OTLP/HTTP トレースを受信し、キャプチャしたファイルを MCP 経由でクエリします。任意のエージェント関数や承認を自動的にトレースすることはありません。

Jaeger、Tempo、Traceloop に保存されたトレースには、OpenTelemetry MCP Serverのようなバックエンド接続型ツールをお使いください。トレース UI、計装、評価機能については、Phoenixを参照してください。SpanHound はバックエンド固有の JSON エクスポートを読み込みません。

AI ネイティブなユースケース

エージェントの実行中の質問	MCP ツール	返される証拠
「昨日の実行が停止した原因は何ですか？」	list_runs → slowest_spans	実行 ID と、最長のモデルまたはツールのスパン。
「書き込みを拒否した後、エージェントは動作しましたか？」	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のままです。新しいパッケージでは、spanhoundを明示的にインストールするクライアント向けに、Pythonのインポートパスとコマンドのエイリアスが引き続き維持されています。

クライアントの設定

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	1回の実行の概要をすばやく確認する（トレース ID のプレフィックスを指定可能）
span_tree	「エージェントは実際に何をしたのか？」— 実行のネストされた構造
slowest_spans	「なぜ遅かったのか？」— 所要時間上位 k 件のスパン
approval_log	HITL 監査 — すべての承認／拒否／編集、決定者、その理由
token_usage	コストに関する質問 — 複数の実行を集計、または実行ごとに表示
search_spans	ツール名、ファイルパス、「拒否」などを条件にスパンを検索
failure_report	対応可能で、範囲が限定され、機密情報が除去されたエラーと失敗したツール呼び出しを検索します。
tool_stats	使用回数、エラー率、拒否件数、レイテンシでツールをランク付けします。
security_audit	呼び出し元の ID、テナント、サーバーの来歴、リスク、承認の証拠を監査します。
recent_activity	実行中にカーソルを使って新しいスパンをポーリングします。
compare_runs	選択したトレースを比較し、モデルやバージョン間の性能低下を確認します。

ツールの説明は、単なる機能説明ではなく、いつ使うかを示すプロンプトとして記述されています。説明が、エージェントから呼び出されるツールのインターフェースになります。

セッションの例（実際のトレース用フィクスチャ）

> 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 のプレフィックス：エージェントは 32 文字の 16 進数 ID 全体を扱いにくいため、すべてのツールでプレフィックスを受け付けます。
• 出力の制限：診断情報は切り詰められ、明らかな認証情報は、クエリ結果がサーバーから出る前に秘匿されます。
• 正確なコスト合計：いずれかのモデルスパンでコストが欠落しているか、料金が利用不可と示されている場合、token_usage は cost_known: false と null のコストを返します。不明な料金を $0 として表示することはありません。
• カーソルポーリング：recent_activity により、実行中にスパンが書き込まれている間もスナップショットリーダーを活用できます。
• デモ用フィクスチャ（examples/example_trace.jsonl）は、手書きではなく、実際のエージェントハーネスの実行記録です。

正直な制限事項

• MCP stdio トランスポートのみ（Streamable HTTP と認証済みのリモートアクセスは、次のトランスポート境界で対応予定です）
• ライブポーリングではスナップショットを再読み込みします。プッシュ型のサブスクリプションではありません
• セキュリティ監査で報告できるのは、トレースの生成元が記録した ID／来歴情報に限られます
• 読み取り専用ツールです。トレースの変更（アノテーション）はロードマップ上の項目です
• Python のクエリモジュールとサーバーモジュールは mcp_trace として利用できます。既存のクライアント向けに、以前のインポート名とコマンドエイリアスも引き続き利用できます。

初回利用時のフィードバック

試したときの状況をお知らせください： 使用した MCP クライアントまたはトレース生成元、解決しようとしていた質問、そして不足していた証拠をお知らせください。ファイルの読み込みに失敗した場合は、機密情報を除いた抜粋を共有してください。

ライセンス

MIT