opik-diagnose

Diagnose — 注目すべきトレースを見つける

完了の定義： 注目すべきオンライン／本番環境のトレース（および Diagnostics の問題）の優先順位付き候補リストを提示します。各項目には、検出のきっかけとなったシグナルとトレース IDを含め、プロジェクトと直近の期間に絞り込み、/opik-explain にそのまま引き継げる状態にします。「注目すべき」とは、エラー、低速化、性能低下、または低いオンライン評価スコアを意味します。すべてのトレースを列挙することではなく、オフライン実験の結果は決して含めません。プロジェクトを読み取れない場合は、最初の実際のブロッカーで停止し、次に行う手順を1つだけ提示してください。

操作：実際のシグナルに基づいてライブデータを順位付けし、確認すべき少数の項目を提示して、最上位の項目を /opik-explain に引き継ぎます。コードは変更しません。 このスキルは設計上、読み取り専用です。

入力

エントリーポイントは /opik-diagnose（現在のプロジェクト）、/opik-diagnose <project>、または /opik-diagnose <what to look for>（例：「低速なトレース」、「今日のエラー」）です。それ以外は推定します。次の項目は任意のオーバーライドとして扱います。

• project（デフォルト：設定／リポジトリから推定） · window（デフォルト：直近） · signal focus（デフォルト：すべて — エラー、レイテンシ、性能低下、低スコア） · shortlist size（デフォルト：数件）

実際に推定できないブロッカーに遭遇した場合のみ確認してください（「ブロッカー」を参照）。

有効化 — 対象となる作業はこれだけです

1. スコープを決める

プロジェクト（設定／リポジトリから）と直近の期間を指定します。Opik に接続できることを確認してください。~/.opik.config が存在するか、OPIK_API_KEY が設定されていれば、それを使用します。どちらもない場合 → ブロッカー（「opik configure を実行してから、もう一度実行してください」）。

2. その週の状況を把握するため、プロジェクトを一度読み取る

Opik MCP が接続されている場合、read('project', <name or id>) は1回の呼び出しで次の3点を確認できます。いずれも、このスキルで推測する必要がなくなります。現時点で問題があるか（過去7日間と比較したエラー率とレイテンシ — 週を通して変化がなければ、その旨を伝えて停止します）、プロジェクトで実際に記録されているスコア名（後で絞り込みに使えるスコア名です。名前を推測すると空の結果が返り、問題がないように見えてしまいます）、そしてプロジェクトに含まれるデータです。

レートが null と報告された場合、その期間内にトレースが存在しないことを意味し、正常なゼロではありません。該当期間にデータがほとんどない場合は、結論を出す前に since="30d" を指定して期間を広げてください。

3. Diagnostics の課題から始める

Opik の Diagnostics では、プロジェクトで繰り返し発生している失敗が、重要度、発生回数、原因、推奨される修正方法、サンプルトレースとともに、優先順位順の課題としてすでにまとめられています。まずその一覧を確認してください。これは「何が問題なのか」に対する、UI がすでに算出した答えです。生のトレースから再構築しないでください。

Opik MCP が接続されている場合、agent_insights_issue エンティティが主な手段です。

list('agent_insights_issue', project_name='<project>')        # open issues, ranked as the Diagnostics page ranks them
read('agent_insights_issue', '<issue id>', project_name='<project>')
#  → {issue: {name, cause, suggested_fix, severity, status, …}, example_trace_ids: [...], details: [...],
#     url: '<the issue's Diagnostics page>', trace_url_template: '<…/logs?trace={trace_id}>'}

未解決の課題はそれぞれ、signal=diagnostics を持つ候補項目になります。trace_id は最初の example_trace_ids のエントリから取得し（取得するには上位数件の課題を読み取ります）、trace_url はその ID を埋め込んだ trace_url_template から取得します。ユーザーが Diagnostics ページ自体を開けるよう、課題の url も伝えてください。サーバーが UI のベース URL またはワークスペースを特定できない場合、リンクフィールドはありません。その場合は、セッションの指示にあるトレースリンクテンプレートを使用します（ステップ 6）。一覧の順序は変えないでください。Diagnostics ページのランキング（最後に確認されたものが先、次に発生回数の多いもの）です。件数は UI と一致するよう全期間の値です。対象期間を絞り込むには since（例："7d"）を渡します。

一覧が空でも、問題がないとは限りません。 どの状態なのか、何をすべきかが示されています。表示された説明に従ってください。

一覧の表示	対応
未解決の課題はなく、最終スキャンは <time>	Diagnostics は正常に動作しており、問題は見つかりませんでした。ステップ 3 に進んでください。
有効だが、まだスキャンされていない、または最終スキャンから 1 日以上経過している	write('agent_insights_job.trigger', {"project_name": "<project>"}) を実行し、Diagnostics ページのリンクを伝えてから、ステップ 3 に進んでください。データは変更されないため、確認を求める必要はありません。
このプロジェクトでは有効になっていない、または無効になっている	ユーザーに一度だけ、一文で尋ねます。「<project> の Diagnostics を毎日有効にしますか？最初の結果が出るまで数分かかります。」はいの場合は enable、続けて trigger を実行し、リンクを伝えてから続行します。いいえの場合は、そのまま進み、Diagnostics を使わずに候補一覧を作成したことを伝えてください。
このデプロイ環境では利用できない	続行し、このデプロイ環境では Diagnostics を利用できないことを一度伝えてください。有効化を提案しないでください。

スキャンが終わるのを待ったり、ポーリングしたりしないでください。ページのリンクを返し、トレースからトリアージを完了して、グループ化されたレポートは数分後に表示されると伝えてください。開始したスキャンがまだ実行中の間に作成された候補一覧では、source=diagnostics_pending が報告されます。

一覧に課題があっても、それが答えのすべてではありません。 最後にレポートの対象範囲が Report covers data through <time> と記載されています。課題は、最後のスキャンでグループ化されたものです。毎日スキャンする場合、通常は今日のデータは含まれません。この行に未対象の期間が続けて記載されている場合、ユーザーが指定した期間はレポートの対象範囲を超えており、その不足分が回答から漏れています。

対象範囲の表示	対応
Report covers data through <time> のみ	レポートは最新です。通常どおりステップ 3 に進んでください。
The last <N> are not in it: write('agent_insights_job.trigger', …)	トリガーを実行してから、行に記載された since を指定して不足分についてステップ 3 に進みます。再スキャンを待たず、課題がその期間全体をカバーしているかのように提示しないでください。source=diagnostics_pending を報告します。
… a trigger rescans the last 24 hours, so it cannot close this gap	トリガーは実行せず、行に記載された since を指定してステップ 3 に進みます。再スキャンしても期間の中間部分が欠けたままなのに、修正できたように見えてしまいます。

必要に応じて、レポートには基準日を記載してください。1 週間分を依頼したユーザーに、昨日までの課題が返されたなら、そのことはユーザー自身が気づく前に伝えてください。

トリアージによって課題のステータスが変更されることはありません。agent_insights_issue.resolve、.close、.reopen は存在しますが、ユーザーから依頼された場合に使用するものです。失敗に対処済みかどうかを決めるのはユーザーであり、課題を解決済みにすると、ほかの人が見る一覧から外れます。課題を見つけて提示するのがこのスキルの役割であり、課題を一覧から取り下げることではありません。

MCP がない場合、SDK REST クライアントで同じ課題を読み取ります。

import opik
client = opik.Opik()
# Needs the project_id (a uuid), not the name — read it off any trace from
# search_traces (trace.project_id), or resolve it from the project name first.
issues = client.rest_client.agent_insights.find_agent_insights_issues(project_id=project_id)

4. 候補トレースを取得して不足分を補う — MCP を優先し、SDK を代替手段として使用

Diagnostics は、前回の実行でグループ化された項目を報告します。それより新しい項目や、グループ化のしきい値に達しなかった項目（単一のレイテンシ外れ値、オンライン評価スコアの低下、前の期間と比べたリグレッションなど）は、引き続きスキャンが必要です。issue の example_trace_ids ですでに取り上げられているトレースはスキップしてください。その issue の候補リストに含まれています。

• MCP に接続済み： シグナルごとに list を 1 回呼び出します。バックエンドがフィルタリングと並べ替えを行うため、各呼び出しで、すでに順位付けされた短いページが返されます。SDK もクライアント側の並べ替えも不要です。since には "1h"、"24h"、"7d" を指定します。filters は OQL 文字列、sort は "<field> [asc|desc]" です（デフォルトは desc）。トレースの一覧では、source を指定しない限り、評価器／プレイグラウンド／実験のトレース（source = "sdk"）は非表示になります。

  list(entity_type="trace", project_name="<project>", since="24h",
       filters="error_info is_not_empty", sort="start_time desc")         # errored
  list(entity_type="span",  project_name="<project>", since="24h",
       filters='type = "tool" AND error_info is_not_empty', sort="start_time desc")  # failed tool calls
  list(entity_type="trace", project_name="<project>", since="24h",
       sort="duration desc")                                              # latency outliers (ms)
  list(entity_type="trace", project_name="<project>", since="24h",
       filters="feedback_scores.<metric> < 0.5", sort="feedback_scores.<metric> asc")  # low online-eval score
  list(entity_type="trace", project_name="<project>", since="7d", until="24h",
       sort="duration desc")                                              # prior window, for regressions
  

  テーブルには、デフォルトで duration、error_type、コストに加え、並べ替えやフィルタリングに使用したすべてのフィールドが含まれます。フィルターが拒否された場合は、修正方法とともに返されます。schema("list.trace") は全フィールドのリファレンスです。

• MCP なし： SDK を代替手段として使用します。

  traces = client.search_traces(project_name="<project>", max_results=200)  # recent window
  # Narrow server-side with filter_string='error_info is_not_empty' when the volume is
  # large; otherwise rank client-side (step 5). Each trace carries the fields you rank
  # on: error info, duration, feedback_scores.
  

issue の example_trace_ids ですでに取り上げられているトレースはスキップしてください。その issue の候補リストに含まれています。

5. 残りのトレースをシグナルで順位付けする

残りの候補をそれぞれスコアリングし、上位数件を残します。優先順位は次のとおりです。

1. エラー発生 — トレースまたはスパンで例外が記録されています。
2. ツール呼び出しの失敗 — tool スパンでエラーが発生した、エラー形式の結果が返された、または同じ呼び出しが繰り返されています（リトライループ）。エージェントはここで失敗することが多いため、独立したシグナルとして提示します。has_tool_spans を使って候補を見つけ、該当する tool スパンをスキャンし、空でないエラー、エラーや拒否を示す出力、または連続して重複する呼び出しがないか確認します。
3. レイテンシの外れ値 — 所要時間がプロジェクトの通常値を大きく上回っています（基準には p90／p99 を使用します）。
4. オンライン評価スコアの低下 — フィードバックスコアがしきい値を下回っています（回答の関連性、ハルシネーションなど）。
5. リグレッション — 前の期間と比べてシグナルが悪化しています。

これらを、上記のシグナルの順に Diagnostics の項目の後ろに追加します。候補リストに入れた各項目には、そのトレースを検出したシグナルを 1 つと、短い理由を記載します。トレースごとに 1 項目にしてください。複数のシグナルに該当する場合（エラーが発生した tool スパンによってトレースにもエラーが発生している場合など）は、最も優先順位の高いシグナルを採用し、残りは理由に記載します。長いリストより、短く順位付けされたリストを優先してください。

6. 対象範囲を守る

対象はオンライン／本番環境の trace シグナルのみです。オフライン実験の結果は提示しないでください。これらは /opik-evaluate と /opik-compare の出力であり、ここで再検出するものではありません。

7. 報告する

順位付けされた候補リストと次のステップを 1 つ返します。各項目は クリック可能な Opik UI リンクとして提示し、ID のみを記載しないでください。ユーザーが開いて詳しく調べられるようにします。URL の形式を推測して作らないでください。推測したリンクは正しそうに見えても 404 になり、ID のみを記載するより問題です。サーバーから渡された情報を使用してください。issue の trace_url_template、または MCP がセッションの指示で指定するトレースリンクのテンプレート（<opik>/api/v1/session/redirect/projects/?trace_id={trace_id}&path=…）を使います。このテンプレートは ID からプロジェクトとワークスペースを解決するため、ID を埋め込むだけで使えます。SDK を使う場合は、opik.url_helpers.get_project_url_by_trace_id(trace_id, url_override) で同じリンクを生成できます。各項目は /opik-explain に引き継げる状態です。自然な次のステップは「最上位のトレースを説明する」です（Output を参照）。このスキルは項目を見つけて引き継ぐものであり、根本原因の分析（これは /opik-explain が行います）はせず、コードも変更しません。

ブロッカー

最初に発生したブロッカーで停止し、次のステップを必ず 1 つだけ返します。

• "opik configure を実行し、その後 /opik-diagnose を再実行してください。"
• "どのプロジェクトをスキャンしますか？/opik-diagnose <project> を指定するか、Opik の設定でプロジェクトを設定してください。"
• "この環境から Opik に接続できません。プロジェクトのトレースビューを開いてエラー／所要時間で並べ替えるか、Opik が設定されている環境で実行してください。"

出力

ユーザー向け： 短い人間向けメッセージです。ランク付けされた候補リスト（各トレースにクリック可能な Opik UI リンク、そのシグナル、理由を一行で記載。最悪のものから順に）、続いて次のステップを一つだけ示します。全トレースの生データをそのまま並べたり、JSON を出力したりしないでください。

内部（構成／評価用）では、次の形式を一つ使用します。

• status：found | empty | blocked
• scope：project、window
• shortlist：{trace_id, trace_url (the Opik UI link), signal (error|tool_call|latency|low_score|regression|diagnostics), why, rank} のリスト
• source：sdk | mcp | diagnostics_pending（この実行でスキャンがトリガーされた状態。候補リストはトレースから作成されます）
• next_step：一つだけ（通常は「上位のトレースを説明する」）

不変条件：found には空でない shortlist が含まれ、各項目に signal、trace_id、クリック可能な trace_url が含まれます。empty は読み取りに成功したものの、しきい値を超えたものがなかった状態です。blocked には next_step が一つだけ含まれます。候補リストにオフライン実験の結果を含めてはいけません。どの経路でもコードベースは変更されません。

例

MCP に接続してプロジェクトをトリアージする場合。 /opik-diagnose。list('agent_insights_issue', project_name=…) は、重大度の高いツール呼び出しループ（昨日 12 回発生）と、重大度の低い空の回答の問題という、未解決の問題を二つ返します。最初の問題に対する read で原因、トレース ID の例三つ、およびリンクが得られます。続いて list('trace', since="24h", sort="duration desc") を実行すると、どの問題にも該当しない、p90 の 5 倍のトレースが一つ見つかります。候補リスト = ツール呼び出しループ（ランク 1、diagnostics、最初のトレース例）、レイテンシの外れ値（2、latency）、空の回答の問題（3、diagnostics）。次のステップ = 「上位のトレースを説明する」。source=mcp。→ found。

SDK のみでプロジェクトをトリアージする場合。 /opik-diagnose。find_agent_insights_issues はまだ何も返しません。プロジェクトに対する search_traces では、エラーが発生したトレースが二つ、期間が p90 の 5 倍のトレースが一つ、Hallucination のスコアが 0.2 のトレースが一つ見つかります。候補リスト = エラーが発生した二つのトレース（ランク 1～2）、レイテンシの外れ値（3）、低スコアのトレース（4）。それぞれにシグナルを付けます。次のステップ = 「上位のトレースを説明する」。source=sdk。→ found。

問題がない場合。 /opik-diagnose。読み取りには問題ありませんが、エラーが発生したトレース、処理が遅かったトレース、スコアが低かったトレースはありません。→ empty：「最近の期間では、しきい値を超えたトレースはありません。」

ブロック — 設定なし。 /opik-diagnose。~/.opik.config も OPIK_API_KEY もありません。→ blocked：「opik configure を実行してから、/opik-diagnose を再実行してください。」（コードには触れません。）

アンチパターン

ランク付けされた候補リストではなく全トレースを列挙すること。agent_insights_issue（または SDK の agent_insights クライアント）に問題の一覧があるのに、生のトレースから Diagnostics のランキングを再構築すること。オフラインの実験／evaluate の結果を提示すること（対象範囲外）。MCP を必須にすること（SDK の agent_insights 経由なら不要です）。ここでトレースの根本原因を特定すること（/opik-explain に引き継いでください）。コードを編集すること（このスキルは問題を提示するだけです）。シグナルではなく新しさでランク付けすること。

参考資料

SDK とオブザーバビリティの詳細は、隣にインストールされている opik スキルにあります。ファイルを直接読んでください。パスはこのファイルからの相対パスです。../opik/SKILL.md（トレースの検索 — MCP の list ツールと search_traces で共有される OQL フィルター文法）、../opik/references/production.md（search_traces、Diagnostics、オンライン評価スコア、エラー／レイテンシ分析）、../opik/references/tracing-python.md（SDK の読み取り API）、../opik/references/observability.md（スパン／スコアモデル）。ホストのスキル配置が異なる場合は、opik スキルの references/ ディレクトリを探してください。

opik スキルがインストールされていない場合は、レポートにその旨を記載し、記憶を頼りにせず https://www.comet.com/docs/opik/ を参照してください。