ratel-observability-assessment

/ratel-observability-assessment — エージェントのコードベースでネイティブ OTLP テレメトリーを有効にする

Ratel チームが行う方法で、お客様のコードベースにオブザーバビリティを導入します。スタックを検出し、エージェントのメンタルモデルを把握し、一貫した命名・タグ付けの語彙を決め、価値を証明するダッシュボードを選び、Ratel のネイティブ OTLP テレメトリーを有効にして、チームがすでにエクスポート先としている OTel バックエンドを選び、お客様が実行に移せる提案書を作成します。成果物は提案書です。エージェントのコードは編集せず、バックエンド API も呼び出さないでください。

Ratel のテレメトリーは、OpenTelemetry そのものです。SDK は取得とツールのファネルを、gen_ai.* スパン（semconv v1.42.0）と ratel.* オーバーレイとしてネイティブに出力し、標準の OTLP としてエクスポートします。そのため、連携方法は特定のベンダーに依存しません。ネイティブテレメトリーを一度有効にし、それらのスパンを、チームがすでに使用している任意の OTel バックエンド（Langfuse、LangSmith、自社のコレクター、または Ratel Cloud — Coming Soon）にエクスポートします。このスキルは、トレーシングを導入する場所、Ratel のファネルと併せて追加するエージェントレベルのスパン、エクスポート先のバックエンド、価値を証明するダッシュボードについて、一連の判断を担います。これはオブザーバビリティのファネルの入口であり、通常は /ratel-assessment でオブザーバビリティの評価項目が「弱い」または「未対応」と判定されたときに利用します。

ここで決定した語彙とダッシュボードのセットは、チームがエクスポート先のバックエンドで構築する際の規約となるため、ここで定義したスパン名や属性名が実際にダッシュボードに表示されます。

考え方：呼び出しグラフではなく、メンタルモデルをトレースする

よくある失敗は「すべての関数をスパンで囲む」ことです。これではコードの呼び出しグラフに沿ったデータが生成されますが、エージェントが何をしようとしていたのかは分かりません。提案書では、ソースファイルの構成ではなく、ターンの概念的な形、つまり作業単位、ステップ、セッションを軸にオブザーバビリティを構成する必要があります。全体的なガイダンスと、見つけた場合に必ず指摘するべき 2 つのアンチパターン（セッション境界がないこと、ツール呼び出しが型なしイベントとして記録されていること）については、references/instrumentation-philosophy.md を参照してください。

ワークフロー

ステップ 1 — スタックを検出する

マニフェストファイルを読み、言語とフレームワークを特定します。Ratel のネイティブテレメトリーは TypeScript と Python に対応しているため、スタックプロファイルを使って主に、どの SDK（@ratel-ai/sdk と ratel-ai のどちらか）を使うか、また連携にどのフレームワークフックを使うかを判断します。

# TypeScript / Node detection
test -f package.json && jq -r '.dependencies // {}, .devDependencies // {} | keys[]' package.json | sort -u

# Python detection
test -f pyproject.toml && grep -A 200 '^\[' pyproject.toml || true
test -f requirements.txt && cat requirements.txt
test -f uv.lock && head -50 uv.lock

依存関係を次のスタックプロファイルのいずれかに対応付けます。

マニフェスト内のシグナル	スタック
ai、@ai-sdk/*	Vercel AI SDK
@mastra/core、または openai / @anthropic-ai/sdk を直接呼び出す独自実装のループ	TypeScript 汎用
openai / anthropic / langchain / llama_index（エージェントフレームワークなし）	Python 汎用
langgraph、crewai、agno、autogen	Python エージェント型

シグナルが重複する場合（たとえば、LangGraph のスーパーバイザーと、その内部での OpenAI への直接呼び出しの両方がある場合）は、エージェント型を主なプロファイルとして選び、提案書で混在スタックに関する注意事項を記載します。どのプロファイルにも当てはまる具体的な連携方法（TS + Python）については、references/native-telemetry-setup.md を参照してください。

エージェントの実装箇所をまったく特定できない場合（LLM クライアントのインポート、エージェントフレームワーク、モデル呼び出しがない場合）は、正直にスキップする方法を使用します。

ステップ 2 — エージェントのトポロジーを把握する

Explore エージェントを 1 つ起動するか（ごく小規模なリポジトリでは直接調査して）、ファイルパスを示しながら次の 4 つの質問に答えます。

1. ターンはどこから始まりますか？ — エントリーポイント：HTTP ハンドラー、CLI の動詞、キューコンシューマー、チャットプラットフォームの Webhook などです。ここに session_id があります。
2. 作業の単位は何ですか？ — スーパーバイザー関数、サブエージェントのファクトリー、役割に特化したループなどです。ユーザーメッセージを受け取り、応答を返すものはすべて該当します。これらが最上位の境界になります。
3. ツールはどこで定義され、呼び出されていますか？ — ツールレジストリ（tools: [...]）、@tool デコレーター、MCP サーバーの配線などです。各ツール呼び出しは、型付きのツール呼び出しステップとして表面化する必要があります。
4. サブエージェント同士はどこで処理を引き継ぎますか？ — スーパーバイザー → ワーカー、並列ファンアウト、グラフノードの遷移などです。これらの箇所では、セッション／ユーザー／タグのコンテキストを境界を越えて保持する必要があります。

提案書には、これを簡潔なトポロジー図（ASCII または Mermaid）として記載します。網羅的である必要はありません。実装時にお客様が指し示せる全体像を 1 つ示すことが重要です。

ステップ 3 — エクスポート先の OTel バックエンドを特定する

Ratel は標準の OTLP を出力するため、バックエンドについて確認するのは、スパンの送信先だけです。references/vendor-detection.md を読み、チームがすでに使っている可能性のある各バックエンド（Langfuse、LangSmith、PostHog、Arize Phoenix、Helicone、OpenLLMetry/OTel GenAI、Braintrust）について、マニフェストの依存関係、環境変数、初期化／インポート箇所を調べます。いずれも OTLP を取り込みます。利用可能であれば、ratel-assessment がすでに収集した可観測性シグナルを再利用します。同リファレンスのルールに従い、検出したバックエンドと確信度（高／中／低）を記録します。マニフェストの依存関係や初期化箇所は強いシグナルで、環境変数だけの場合は弱いシグナルです。

ステップ 4 — バックエンドが見つからない場合は、1 つ推奨する

ステップ 3 でシグナルが見つからない場合（または弱く曖昧なシグナルしかない場合）は、推測せずに AskUserQuestion を使って、チームが使用している OTel 対応バックエンドを尋ねます。選択肢として、Langfuse、LangSmith、独自の OTel コレクター、その他、まだないを提示します。

• バックエンドが指定された場合は、それをエクスポート先として処理を進めます（確信度：申告あり）。
• その他が選択された場合は、その名前を記録します。OTLP バックエンドならどれでも使えるため、それをエクスポート先として記録します。
• まだないが選択された場合は、導入を推奨します（Langfuse と LangSmith は OTLP ネイティブの導入先として最も手早く、セルフホストのコレクターも利用できます）。将来的なファーストパーティの選択肢として Ratel Cloud（近日公開）も記載します。いずれの場合も、提案書を完全な形で提出します。

ステップ 5 — ネイティブテレメトリを有効にし、エージェントレベルのスパンを提案する

Ratel は、取得とツールのファネルをネイティブに OTel スパンとして出力します。提案のインストルメンテーションセクションは、次の 2 つで構成されます。

1. Ratel のネイティブ OTLP テレメトリを有効にする — references/native-telemetry-setup.md を参照してください。セットアップ方法を選びます。新規構築の場合は configureTelemetry() / configure_telemetry()（Ratel が OTel プロバイダーを管理し、RATEL_URL にエクスポートします）、またはデュアルエクスポートの場合は ratelSpanProcessor() / ratel_span_processor() をチーム既存のプロバイダーに追加します。コードベースにどちらの方法が適しているか、その理由とともに記述してください。これで接続は完了です。下流のスキルで「描画」するものは残っていません。
2. Ratel が出力しないエージェントレベルのスパンを追加する — references/instrumentation-philosophy.md（メンタルモデル、コールグラフではないこと、2 つのアンチパターン）と references/semantic-conventions.md（作業単位の命名、ステップの種類、セッション／スレッドの情報源、タグ、属性キー）を、ステップ 2 で作成したトポロジーに適用します。Ratel の ratel.* ファネルスパンは、顧客独自の LLM 呼び出しスパンやエージェントスパンと同じトレースに加わります。Ratel は chat <model> スパンを出力しないため、セッション境界、エージェントステップとモデル呼び出しのスパン、およびセッション ID の情報源に名前を付けてください。何を記録するか、その理由とともに記述してください。

提案に追加するすべてのスパン／タグ／属性キーを、顧客が共有ドキュメントに貼り付けられるよう、1 つの表にまとめてください。これにより、以下のダッシュボードでグループ化する名前が決まります。

ステップ 6 — ダッシュボードを提案する

references/general-agent-dashboards.md から、インストルメンテーションで対応できるエージェントの健全性ダッシュボードを選びます。レイテンシとコストの概要、エラーの状況、ツールの使用状況、セッション品質、モデルとプロンプトのドリフトです。これらは Ratel の有無にかかわらず役立ちます。ステップ 3 でチームが選んだ OTel バックエンドで表示してください。

Ratel 価値グループは条件付きで追加します。マニフェストに Ratel が存在する場合、または顧客が導入に同意している場合に限ります。ダッシュボードには references/ratel-value-map.md にある名前（トークンコストと削減額、取得品質、オリジンの内訳、スキル取得の健全性、上流の健全性）を使用し、ロードマップ上の条件があるものには脚注を付けてください。Ratel が存在せず、導入する予定もない場合は、このグループ全体を省略してください。顧客所有のドキュメントに Ratel の提案をあらかじめ盛り込まないでください。

どのダッシュボードを選ぶか、それぞれが重要な理由を記載してください（ダッシュボードごとに、平易な言葉で 1 行）。各ダッシュボードでグループ化に使用する具体的なスパン名／属性名は、references/semantic-conventions.md と references/ratel-value-map.md に記載されています。ウィジェットは、顧客がバックエンドの UI で作成します。

ステップ 7 — 提案書を作成する

<repo>/.ratel/ratel-observability-assessment.md に書き込みます。日付を付けない、更新し続ける単一のファイルです。.ratel/ ディレクトリが存在しない場合は作成します。リポジトリですでに別のドキュメント規約を採用している場合は、パスをユーザーに確認してください。再実行時は上書きします。

提案書には、次の内容をこの順序で含めます。

1. 概要 — 検出されたスタック、エージェントのトポロジー、すでに計装されている内容（あれば）、この提案で追加する内容を、1つの段落にまとめます。
2. エクスポート先 — OTel バックエンドと確信度、またはステップ 4 でユーザーが回答した内容。
3. トポロジー — ステップ 2 の図。
4. 計装戦略 — Ratel のネイティブテレメトリーを有効にする方法（ステップ 5 のどのセットアップ手順を使うか）、エージェントレベルのスパン／タグ／属性の表、セッション境界の計画を記載します。見つかったアンチパターンがあれば、どちらかを指摘します。
5. 推奨ダッシュボード — エージェント健全性グループと、該当する場合は Ratel の価値グループ（ステップ 6 の内容）を、それぞれ1行の「理由」とともに記載します。
6. Ratel の観点（条件付き。Ratel が導入済みまたは導入予定の場合のみ）— references/ratel-value-map.md に基づき、どの調査結果がどの Ratel の機能に対応するかを記載します。
7. 推奨する次のステップ — 以下のルーティング表から、該当する独立した次のステップを案内します。

目次、エクスポート先、推奨する次のステップをチャット内にインラインで表示します。目次は最大7項目です。提案書の本文全体をチャットに貼り付けないでください。成果物はファイルです。

ステップ 8 — 独立した次のステップを案内する

提案書とインラインの要約の末尾に、次のルートを記載します。

状況	案内先
テレメトリーを有効にする	references/native-telemetry-setup.md — 具体的な TS + Python の配線（新規構築時の configureTelemetry／デュアルエクスポート用の ratelSpanProcessor）、コンテンツ取得のオプトイン、ローカルのトレースストリーム
Ratel 経由でエージェントのツールとスキルを読み込む	/ratel-integrate — SDK またはフレームワークアダプターの配線を実装し、各エージェントの機能境界を検証します。オブザーバビリティは前提条件ではありません。

正直にスキップする場合

ステップ 1 の後、コードベース内に LLM クライアントのインポート、エージェントループ、モデル呼び出しが1つも見つからない場合は、そこで終了します。提案書は作成しません。ユーザーには次のように伝えてください。

エージェントのコードは見つかりませんでした。確認したのは <files looked at> のみです。このコードベースのエージェントコードが標準的でない場所にある場合は、その場所を教えてください。再度確認します。

エージェントのないコードベースに無理にオブザーバビリティの提案を作成すると、役に立たない文書が生まれ、パートナーからの信頼を損ねます。スキップして尋ねるほうが適切です。

Ratel のネイティブテレメトリーは TypeScript と Python に対応しています。エージェントが別の言語（Ruby、Go、またはニッチなフレームワークなど）で実装されている場合も、提案書は作成してください。計装戦略とダッシュボードの構成はスタックに依存せず、チームは TS/Python 製の Ratel Local サイドカーから Ratel の OTLP スパンをエクスポートできます。ただし、インプロセスの SDK 配線には「TS/Python のみ」と明記し、そのスタックに Ratel Local（MCP）が適切な統合モードかどうかを確認してください。確信度を偽ってはいけません。

リファレンスファイル

• references/instrumentation-philosophy.md — 「コールグラフではなく、メンタルモデルをトレースする」＋ 2 つのアンチパターン
• references/native-telemetry-setup.md — Ratel のネイティブ OTLP テレメトリーを有効にする方法（TS + Python）：スパンの語彙、グリーンフィールドとデュアルエクスポート、コンテンツキャプチャーのオプトイン、ローカルトレースストリーム
• references/semantic-conventions.md — ファネルとエージェントのスパンで共有する OTel のスパン／属性の語彙
• references/general-agent-dashboards.md — スタックに依存しないエージェント健全性ダッシュボードのカタログ
• references/ratel-value-map.md — Ratel が提供する機能から観測可能なシグナルへの対応を示す唯一の信頼できる情報源。スイート全体を通して参照してください
• references/vendor-detection.md — バックエンドごとの検出シグナルと、Ratel の OTLP スパンを各バックエンドにエクスポートする方法
• references/finding-catalog.md — バックエンドでトレースを確認する際に探すべき、エージェントの失敗モードのカタログ