convex-insights

自然言語でログとヘルスを照会する

デプロイではすでに何が起きたかが記録されています。エージェントに必要なのは、適切に質問することだけです。この機能は、公式 Convex MCP の読み取りツール（logs、insights、functionSpec、status）を規律ある形でラップし、運用上の質問を範囲を絞った証拠付きのクエリに変換して、人間がダッシュボードでワンクリック検証できる回答を返します。この規律は、実際の現場で最も効果を発揮しているオブザーバビリティ MCP の仕組みを取り入れたものです。クエリの前にフィールドを確認し、15 個のツールではなく 3 つのビューを用い、トークンを節約した出力にし、すべての回答にダッシュボードへのディープリンクを付けます。

ワークフロー

1. GUARD：deploy-guard のステップ 0-1 — 読み取り対象のデプロイを特定し、明示します。ログ／インサイトの読み取りは読み取り専用です。インサイトの確認では、本番環境の変更フラグを有効にしてはいけません。
2. クエリの前に DISCOVER — 識別子を推測してはいけません。functionSpec で実際の関数名を一覧表示し、status でデプロイ／バージョンを確認します。ツールの制限を事前に把握します。logs が受け付けるのは --history <n>（時間範囲ではなく件数）、--success、--jsonl、--prod、--deployment のみです。サーバー側でステータス／関数／requestId／時間によるフィルタリングはできません。insights には関数フィルターがなく、クラウドの開発環境／本番環境とユーザー認証でのみ利用できます。そのため、直近の範囲を取得し、クライアント側でフィルタリングします。
3. 3 つのビューから 1 つを選び、未加工のログ範囲を取得してからローカルでフィルタリングします。
   • 失敗ビュー → logs --history <n> --jsonl を実行し、失敗をローカルで抽出して、関数とエラーメッセージごとにグループ化し、件数と各グループの最初のスタックを返します。「何でエラーが発生しているか」「デプロイ後に何が失敗したか」に回答します。
   • ヘルスビュー → insights（クラウドのみ）：型付きの 72 時間分の読み取り制限／OCC イベントです。提示して順位付けしますが、パフォーマンス／コストの根本原因と修正は convex-advisor に引き継ぎます。ここでは、それらをポインター所見として出力し、パフォーマンス修正の枠組みを担いません。
   • トレースビュー → logs --history <n> --jsonl を実行し、特定の requestId／関数でローカルにフィルタリングして、実行全体を確認します。「この呼び出しが失敗した理由」に回答します。
4. 対象を絞るには、上限を設けた直近のログ範囲（妥当な --history 件数）を取得し、質問された関数／ステータス／requestId に応じてクライアント側でフィルタリングします。範囲が大きい場合は、行をそのまま大量に出力するのではなく、関数／メッセージ別に件数を集計します。
5. 回答には、（a）一行での所見、（b）証拠（件数と代表的なスタック／ログ行を 1 つ）、（c）可能な場合は、エージェントが組み立てたダッシュボードへのディープリンク（dashboard.convex.dev の、そのデプロイの Logs／Functions ビュー）を含め、人間が検証できるようにします。リンクを返すツールはないため、デプロイ名と関数名から組み立てます。未加工のログをそのまま回答にしてはいけません。
6. 「デプロイでこれが壊れたか」と尋ねられた場合は、ログのタイムスタンプから失敗の発生時点を確認し、status で得たデプロイバージョンと照合して、デプロイとの因果関係をクロスチェックします。相関を確認するのであり、因果関係を断定してはいけません。
7. ここでは修正せず、HAND OFF します。パフォーマンス／コストの原因 → それらの修正を担当する convex-advisor。コードの不具合 → convex-reviewer／convex-authz。今後対応すべき実行中のエラー → monitor／sentinel。バス（specs/finding.schema.json）に所見を出力します。主に observability に出力し、パフォーマンス／コストについては advisor へのポインター所見として出力します。これにより、複合パスで所見を取り込めます。

ルール

• フィルタリングする前に、実際の関数名／フィールド名（functionSpec/status）を確認してください。識別子を推測してはならず、アプリに存在しない名前に対して紛らわしい空の結果を返してはなりません。
• logs と insights には、サーバー側の status／function／requestId／時間範囲によるフィルター機能はありません（logs が受け取るのは --history COUNT のみで、insights はクラウド専用です）。直近の範囲を限定して取得し、クライアント側でフィルタリングしてください。存在しないパラメーターがあるかのように示すのではなく、その旨を伝えてください。
• 質問ごとに3種類のビュー（failures／health／trace）のうち1つを選んでください。推測に基づいて多数のツール呼び出しに分散させてはなりません。
• ダッシュボードへのリンクを返すツールはありません。可能であれば、デプロイ名と関数名からリンクを組み立て、人が確認できるようにしてください。生のログをそのまま回答してはなりません。
• 常に読み取り専用にしてください。insights の処理では変更を一切行わず、本番環境への変更を許可するフラグを有効にしてはなりません（deploy-guard の規律）。
• 読み取り専用に徹し、パフォーマンス／コストの修正は convex-advisor に委ねてください。主に observability を出力し、パフォーマンス／コストは POINTER の調査結果として振り分け、パフォーマンス修正の方針を決める役割は advisor のみに担わせてください。今後の対応は monitor/sentinel に委ねてください。