analytics

LangWatch でエージェントのパフォーマンスを分析する

このスキルは分析データを取得して提示します。コードは作成しません。

ステップ 1：LangWatch CLI を設定する

langwatch docs <path> を使って、ドキュメントを Markdown 形式で読みます。便利なエントリーポイントをいくつか紹介します。

langwatch docs                                    # Docs index
langwatch docs integration/python/guide           # Python integration
langwatch docs integration/typescript/guide       # TypeScript integration
langwatch docs prompt-management/cli              # Prompts CLI
langwatch scenario-docs                           # Scenario docs index

langwatch --help と langwatch <subcommand> --help でコマンドを確認します。list コマンドと get コマンドでは、機械可読な出力を得るために --format json を指定できます。SDK の API や CLI のフラグを推測するのではなく、まずドキュメントを読んでください。

シェルが使えない場合は、プレーン HTTP 経由で同じ Markdown を取得できます。任意のドキュメントパスに .md を追加してください（例：https://langwatch.ai/docs/integration/python/guide.md）。インデックス：https://langwatch.ai/docs/llms.txt。シナリオのインデックス：https://langwatch.ai/scenario/llms.txt

プロジェクトと API キー：個人用ではなく、実際のプロジェクトを対象にしてください。

LangWatch のプロジェクトには 2 種類あります。

• チーム／共有プロジェクト：組織内の実際のプロジェクトです。評価、実験、プロンプト、データセット、シミュレーション、インストルメンテーションでは、必ずこれらのいずれかを対象にしてください。
• 個人用プロジェクト：単一のユーザーに紐づく、非公開の「My Workspace」スクラッチスペースです。ユーザーの評価、実験、本番環境のトレースをここに送信しないでください。個人的な試用のためのものであり、実際のプロジェクトと混同しやすいためです。

認証方法も 2 種類あります。

• .env 内のプロジェクト API キー（LANGWATCH_API_KEY）：これらのスキルで使用するすべての認証情報です。1 つの実際のプロジェクトにスコープが限定されています。これがデフォルトです。ユーザーから明示的な依頼がない限り、こちらを優先してください。
• langwatch login --device（AI ツール／SSO）：コーディングアシスタント（langwatch claude、langwatch codex など）をラップするための、個人用デバイスセッションです。評価、プロンプト、データセット、シナリオ、SDK のインストルメンテーションには使用しません。また、個人用ワークスペースを参照します。これらのスキルで作業を設定するために実行しないでください。

したがって、これらのスキルで作業する際は、実際の共有プロジェクトの LANGWATCH_API_KEY がプロジェクトの .env に設定されていることを確認してください。設定されていない場合は、ユーザーにキーを尋ねてください（https://app.langwatch.ai/authorize で特定のプロジェクト用のキーを発行できます）。プロジェクトを選ぶために langwatch login を実行しないでください。また、個人用プロジェクトをデフォルトにしないでください。LANGWATCH_ENDPOINT が設定されている場合はセルフホスト環境なので、app.langwatch.ai ではなく、そのエンドポイントを使用してください。

ステップ 2：プロジェクトの概要を取得する

langwatch status

リソース数（トレース、評価器、シナリオ、データセットなど）が表示され、利用できるサブコマンドも確認できます。

ステップ 3：傾向と集計データを取得する

時系列データや集計メトリクスには langwatch analytics query を使用します。まずプリセットから始めてください。

langwatch analytics query --metric trace-count        # Total traces over the last 7 days
langwatch analytics query --metric total-cost         # Total LLM cost
langwatch analytics query --metric avg-latency        # Average completion latency
langwatch analytics query --metric p95-latency        # P95 completion latency
langwatch analytics query --metric eval-pass-rate     # Evaluation pass rate

--start-date、--end-date、--group-by、--time-scale、--aggregation を使って絞り込みます。すべてのフラグを確認するには langwatch analytics query --help を実行し、出力を他のツールに渡すには --format json を指定してください。

使用可能なプリセット名がわからない場合や、プリセット以外のメトリクスパスが必要な場合：

langwatch analytics query --help                       # Lists presets and flags
langwatch docs analytics/custom-metrics                # Background on the metric model

ステップ 4：特定のトレースを見つける

langwatch trace search -q "error" --limit 10           # Find error traces by keyword
langwatch trace search --start-date 2026-01-01         # Custom date range
langwatch trace search --format json                   # Machine-readable output

ステップ 5：個々のトレースを調べる

langwatch trace get <traceId>                          # Human-readable digest (default)
langwatch trace get <traceId> -f json                  # Raw JSON for full detail
langwatch trace export --format csv -o traces.csv      # Bulk export as CSV
langwatch trace export --format jsonl --limit 500      # Bulk export as JSONL

興味深いトレースごとに、次の項目を確認してください。

• リクエストとレスポンスの全体
• スパンごとのトークン数とコスト
• エラーメッセージとスタックトレース
• 複数のステップから成るエージェント内の個々の LLM 呼び出し

ステップ 6：調査結果を提示する

データを明確に要約してユーザーに伝えてください。

• ユーザーが尋ねた重要な数値から説明を始めます
• 異常値や懸念すべき傾向（コストの急増、レイテンシの増加、エラー率の変化）を強調します
• 必要に応じて、前の期間と比較して状況を説明します
• 問題が見つかった場合は、次の対応を提案します（例：「火曜日に p95 レイテンシが急増しました。その日の最も遅いトレースはこちらです」）

よくある間違い

• コードを書こうとしないでください。このスキルは既存のデータを照会するもので、SDK のインストールやコードの変更は不要です
• langwatch analytics query --metric ... ではプリセット名（trace-count、total-cost、avg-latency など）を使用してください。必要なものがプリセットの一覧にない場合を除き、生のメトリクスパスを直接指定しないでください
• ここでは langwatch evaluator create や langwatch monitor create を使用しないでください。このスキルは読み取り専用の分析機能です
• 生の JSON をユーザーに提示しないでください。データは明確で人が読みやすい形式で要約してください
• CLI がエラーを返した場合は、言い換えずに正確なメッセージを返信に含めてください。API キー、プロジェクト、日付範囲に関する問題のデバッグでは、ユーザーが生のエラーメッセージを必要とすることがよくあります