ratel-langfuse-analyze

/ratel-langfuse-analyze — ライブトレースを読み取り、改善策を提案する

Langfuse MCP サーバーから集計データと外れ値のトレースを取得し、既知のエージェント障害モードのカタログと照合して、顧客が今週取り組める調査結果レポートを作成します。出力は2つのグループに分けます。Ratel関連の機会（Ratelを統合または強化できる箇所）と、一般的な手を付けやすい改善点（誰でも修正できるもの）です。

一般的な調査結果は埋め草ではありません。顧客の信頼を得るためのものです。自社製品ばかりを勧めるコンサルタントは、営業担当者のように見えます。私たちはそうではありません。

良い出力とは

次の条件を満たす調査結果は、良い調査結果です。

1. 顧客が自分で確認できるよう、少なくとも1つのトレースIDまたは保存済みのフィルターURLを示している。
2. 問題点を述べるだけでなく、何をすべきかを示している。曖昧な調査結果（「エラー率が高い」）はパートナーの時間を無駄にします。
3. 修正がなぜ重要なのかを、顧客のPMが読める1文で説明している。
4. Ratelまたは一般のタグが付いている。混在させると、価値の説明が伝わりにくくなります。
5. Ratel関連の調査結果の場合、解決に役立つRatelのバージョンを示している（現在：v0.1.6 系列、今後：ratel-observability-assessment/references/ratel-value-map.mdから取得）。

次のような調査結果は、良くありません。

• ダッシュボードの内容を言い換えている（「p95レイテンシは4.2s」）。ダッシュボードを見れば分かります。
• 「改善できる可能性がある」「調査する価値があるかもしれない」などの表現を使っている。調査結果と言えるか、そうでないかのどちらかです。
• 枠を埋めるために作り上げられている。

ワークフロー

ステップ1 — MCPが利用可能か確認する

Langfuse MCP サーバーが登録され、接続可能であることを確認します。

# Inspect Claude Code's MCP config OR use the ratel-mcp gateway's search_capabilities
# to confirm Langfuse tools are present.

接続できない場合は、すぐに処理を中断します。

Langfuse MCP server が検出されませんでした。最初に /ratel-langfuse-integrate を実行するか、セットアップセクションに従って手動で接続してください。

MCPにアクセスできない状態では先に進まないでください。このスキルはライブデータなしでは役に立ちません。

ステップ2 — 対象期間を設定する

ユーザーに確認するか、呼び出し時に指定された内容を使用します。

• 期間（デフォルト：直近24時間、または直近100件のトレースのうち、少ない方）。
• 任意のフィルター（user_id、session_id、trace_name、env）。
• 対象とするRatel機能フラグのアーム（任意）（例：feature_flag=tool_pool=ratel）。A/B形式の取り組みを実施する場合に役立ちます。

選択した対象範囲をチャットに表示し、顧客が分析対象を把握できるようにします。

ステップ3 — 集計データを取得する

references/mcp-query-patterns.mdのクエリを使い、次の順に取得します。

1. 対象期間のトレース数、p50/p95/p99レイテンシ、合計コスト、エラー率。
2. レイテンシ、コスト、オブザベーション数別の上位10件のトレース。
3. 呼び出し回数が多いツール上位10件、エラーが発生しているツール上位10件。
4. 使用中のスコア名があれば、そのスコア分布。
5. 機能フラグのタグが設定されていれば、feature_flagごとの内訳。

これにより、以降の分析の枠組みができます。また、「トレースの80%でsession_idが欠落している」といった、単純でも重要な調査結果も明らかになります。これは1回の集計で見つけられます。

ステップ4 — 外れ値を詳しく調べる

次のトレースの完全な内容を取得します。

• 最も遅いトレース。
• 最もコストの高いトレース。
• 「トレースごとのエラー数」リストの上位にあるトレース。
• 最も低いスコアのセッション（スコアがある場合）。
• 代表的なレイテンシの範囲から、対照用にランダムに選んだ2件のトレース。

入力と出力を読みます。構造を見るだけではいけません。エージェントは実際に何をしたのでしょうか。最も価値のある調査結果は、トランスクリプトを読むことで得られます。

ステップ5 — 調査結果カタログと照合する

../ratel-observability-assessment/references/finding-catalog.md（ratel-langsmith-analyzeと共有しているベンダー中立のカタログ）を開きます。各パターンについて、顧客が出力したデータが検出ヒューリスティックに一致するか確認します。一致する場合は、そのパターンのテンプレートを使って調査結果を出力します。

カタログを機械的に一通り確認してはいけません。システムにRatelが導入されていなければ、Ratelのセクション全体を省略します。スコアがなければ、スコア関連のパターンを省略します。カタログはふるいであり、チェックリストではありません。

ステップ 6 — 調査結果を生成する

各調査結果には、次のテンプレートを使用します。

### F<N>. <one-line title>

- **Severity**: high | medium | low
- **Category**: ratel | generic
- **Evidence**: trace ids / filter URL / aggregate value
- **Why this matters**: <one sentence>
- **Recommended action**: <concrete next step the customer can take this week>
- **Solved by Ratel?**: <no | yes, v0.1.X — feature name> (only for ratel category)

重大度の基準：

• high — トラフィックの 10% 超に影響する、またはダッシュボードを破損させるデータ品質の問題。
• medium — 意味のある範囲に影響するものの、不可欠ではない。
• low — 観測された影響は小さいものの、一度は記載する価値がある。

各カテゴリ（ratel、generic）内で、重大度の高い順に調査結果をまとめます。レポートを実用的な内容に保つため、カテゴリごとに最大 10 件までとします。10 件を超える場合は、「（残り N 件の調査結果は後続バッチにまとめました）」と記載し、残りは付録にまとめます。

ステップ 7 — レポートを作成する

<repo>/.ratel/langfuse-analysis-<YYYY-MM-DD>.md に出力します。レポートは実行ごとに 1 つずつ蓄積し、前回のレポートを上書きしないでください。/ratel-langfuse-integrate が書き込むディレクトリと同じ場所にしてください。

構成：

# Langfuse analysis — <date>

## Scope
- Window: <range>
- Filters: <list>
- Traces analysed: <n>
- Findings: <n total>, <n ratel>, <n generic>

## Aggregates at a glance
<3-5 bullets with the headline numbers>

## Findings — Ratel-flavored
<F1, F2, ... in severity order>

## Findings — Generic
<G1, G2, ... in severity order>

## Honest skip (if applicable)
<see honest skip path below>

## Appendix — raw query results
<the aggregates from step 3, formatted as tables>

両カテゴリを通じた重大度の高い調査結果の上位 3 件を、1 行の概要とともにチャット内に表示します。残りの調査結果が記載されたファイルのパスをユーザーに伝えます。

該当なしの場合の正直な対応

データが本当に健全な場合 — エラー率が 1% 未満で、レイテンシの外れ値がなく、セッション ID の欠落もスコアリングの悪化もツールのドリフトもない場合 — は、その旨を記載した短いレポートを作成します。

今週、対応すべき調査結果はありません。 内の 件のトレースを分析した結果、全体の健全性は正常範囲内です。トラフィックが を超えるか、新しいエージェントバージョンがデプロイされたときに、再度実行するとよいでしょう。

これは失敗ではなく、有益な情報です。何も修正する必要がないときにそう伝えるコンサルタントは、パートナーから信頼されます。調査結果を捏造しないでください。 ノイズの多いレポートを一度出すだけで、顧客は以後のレポートをずっと無視するようになります。

同様に、結論を出すにはトラフィックが少なすぎる場合（対象期間内のトレースが約 20 件未満）は、その旨を伝えます。

対象期間内のトレースはわずか 件です。顧客が次にトラフィックを伴うリリースを行うか、次のテストキャンペーンを実施した後に、再実行してください。参考として集計結果を含めますが、調査結果は提示しません。

参考ファイル

• ../ratel-observability-assessment/references/finding-catalog.md — 検出パターン、推奨される修正、Ratel の対応関係をまとめた、ベンダーに依存しない正式なカタログです。ratel-langsmith-analyze と共有しています。
• references/mcp-query-patterns.md — 検証済みの Langfuse MCP クエリ形式（集計、詳細調査、サンプル）です。Langfuse 固有のため、このリポジトリ内に置いています。