opik-explain

Explain — Opik のトレースを根本原因まで調査し、コードと照合する

完了の定義： 要求されたトレース（またはパターン）の根拠に基づく根本原因を、具体的なエビデンススパンに結び付け、提案する次のステップを1 つだけ添えます。「根拠に基づく」とは、失敗または異常のあるスパンを特定し、それを生成したコードやデータと結び付けて説明することであり、トレースを言い換えることではありません。対象を取得または読み取れない場合は、実際に発生した最初の阻害要因で停止し、具体的な次のステップを 1 つ返します。トレースのダンプは説明ではありません。

操作方針：実際のトレースデータを調査し、リポジトリを踏まえて推論し、エビデンスに基づいて最も可能性の高い根本原因を 1 つに絞ります。コードは変更しません。 このスキルは、設計上読み取り専用です。

入力

エントリポイントは /opik-explain <trace-id>（単一のトレース）または /opik-explain <describe the behavior>（見つけて説明するパターン）です。残りは推測し、以下は任意の上書き項目として扱います。

• プロジェクト名（デフォルト：設定／リポジトリから推測）・パターンの時間範囲（デフォルト：最近）・比較対象となる既知の正常なトレース。

本当に推測できない阻害要因がある場合に限り、質問してください（阻害要因を参照）。

アクティベーション — 対象範囲内の作業のみ

1. 対象を特定する

• トレース ID（UUID 形式）：そのトレースを説明します。
• 動作／パターン（「プロンプト変更後のハルシネーション」「応答が遅い」など）：該当する一連のトレースを検索し（下記参照）、共通する原因を説明します。
• Opik に接続できることを確認します。~/.opik.config が存在するか OPIK_API_KEY が設定されている場合は、それを使用します。どちらもない場合 → 阻害要因（「opik configure を実行してから再実行してください」）。

2. トレースとスパンを取得する — まず MCP、SDK はフォールバック

ホスト型 Opik MCP が接続されているか確認し、接続されていれば優先して使用します。接続されていない場合は SDK スクリプトにフォールバックします。

• MCP 接続済み： MCP を使ってトレースを read し、そのスパンを list／read します。
• MCP なし： SDK にフォールバックします。

どちらの場合も、すべてのスパンの入力／出力／エラー／所要時間を読み取ります。

import opik
client = opik.Opik()

tid = "<trace_id>"
trace = client.get_trace_content(tid)       # TracePublic: exposes project_id, input, output, error info — NOT project_name (accessing .project_name raises)
project = client.rest_client.projects.get_project_by_id(trace.project_id).name
spans = client.search_spans(project_name=project, trace_id=tid)   # spans come from a SEPARATE call, not from the trace object
# ALWAYS pass project_name: without it the SDK searches the configured default project, which
# returns an empty list (or a 404 if that project doesn't exist) even for a valid trace id.
# Reconstruct the tree via each span's parent_span_id (the root span has none).
# Your anchor is the first span that errored, returned wrong output, or dominates the duration.

パターンの場合は、プロジェクトの範囲内で該当する一連のトレースを取得し、共通して失敗しているスパンを探します。MCP では、1 回の list 呼び出しでサーバー側のフィルタリングと並べ替えが行われます。filters は OQL 文字列、sort は "<field> [asc|desc]"、since は "1h"／"7d" を指定します。

list(entity_type="trace", project_name="<project>", since="7d",
     filters="error_info is_not_empty", sort="start_time desc")        # error traces
list(entity_type="trace", project_name="<project>", since="7d",
     sort="duration desc")                                             # slow traces (duration in ms)
list(entity_type="trace", project_name="<project>", since="7d",
     filters="feedback_scores.hallucination > 0.5")                    # low-scored traces
list(entity_type="span",  project_name="<project>", since="7d",
     filters='name = "<span name>" AND error_info is_not_empty')       # the shared failing span, across traces

適用されたフィルターは最初の行に表示されます。フィルターが拒否された場合は、修正方法も返されます（schema("list.trace") にすべてのフィールドが記載されています）。MCP を使わない場合も、SDK では同じ文法を使います。

traces = client.search_traces(project_name="<project>", filter_string="error_info is_not_empty")

トレースは非同期です。トレースを生成したばかりの場合は、数秒待ってからフラッシュが実行されたことを確認してください。

3. 根本原因を特定する

コーディングエージェントは、取得したデータとリポジトリを照らし合わせて根本原因を特定します。汎用的な推論エンジンにない唯一の要素、コードを参照できるからです。トレースを MCP と SDK のどちらで取得した場合も、分析方法は同じです。アンカースパン（エラー／誤った出力／レイテンシの主因）を見つけ、その入出力を読み取り、コードと結び付けます（リポジトリでスパン名／関数を grep します）。そして、エビデンススパンとともに、最も可能性の高い根本原因を 1 つだけ提示します。可能性のある原因を列挙するより、エビデンスが十分な原因を 1 つ優先してください。

4. 報告する

根本原因、クリック可能な Opik UI リンクとしてのエビデンススパン（Opik が出力するトレースリダイレクト URL。例：.../session/redirect/...?trace_id=THE_ID。ID のみを記載してはいけません）、および次のステップを 1 つ返します（出力を参照）。修正方法が明らかな場合は、次のステップとして示してください。適用はしないでください（このスキルではコードを変更しません。opik-instrument／opik-test または開発者への引き継ぎが次のステップです）。

阻害要因

最も早い阻害要因で停止し、次のステップを必ず 1 つだけ返してください。

• 「opik configure を実行してから、/opik-explain <trace-id> を再実行してください。」
• 「プロジェクト <name> に <id> のトレースが見つかりません。ID とプロジェクトを確認してから再実行してください。」
• 「この環境から Opik に接続できません。UI でトレースを開いてエラー／出力を貼り付けるか、Opik の設定済み環境で実行してください。」
• 「どの動作を説明すればよいですか？トレース ID を指定するか、何が起きたかを説明してください。」

出力

ユーザー向け： 短い自然なメッセージです。根本原因を1〜2文で説明し、根拠となるスパンをクリック可能な Opik UI リンク（名前＋それぞれが重要な理由）として示し、次のステップを1つだけ示します。生のトレースダンプや JSON ではありません。

内部形式（文面の作成／評価用）。MCP 経由でも SDK 経由でも、出力形式は同じです。

• status：explained | blocked | not_found
• target：trace_id + trace_url（Opik UI リンク。パターンの場合は、サンプルの trace_ids + trace_urls）
• root_cause：根拠に基づく説明を1つ
• evidence：spans（各スパンに name、type、利用可能な場合はトレースのディープリンク trace_url、それが根拠となる理由）
• next_step：必ず1つ
• reasoner：agent（コーディングエージェントがトレースデータとリポジトリを調べて根本原因を特定します）

不変条件：explained には root_cause と少なくとも1つの根拠スパンが必要です。blocked／not_found には next_step を必ず1つ指定します。どの経路でもコードベースは変更しません。

例

単一トレース — ツールの失敗。 /opik-explain 019fd8a7-...。トレースとスパンを取得します。retrieve（tool）スパンが空の結果を返し、その後 llm スパンが幻覚を起こしています。リポジトリで retrieve() を開くと、クエリフィルターが誤っています。根本原因＝取得フィルター。根拠＝llm スパンに渡される空の tool スパン。次のステップ＝「retrieve() のフィルターを修正する（または /opik-test でテストする）」。→ explained。

パターン — 遅延。 /opik-explain why responses got slow this week。遅いトレースを対象に list('trace', since="7d", sort="duration desc")（または MCP を使わずに search_traces）を実行します。どのトレースでも同じ外部 tool スパンが大半の時間を占めています。根本原因＝その呼び出しの遅延。根拠＝N 件のトレースに共通する遅いスパン。次のステップ＝「その呼び出しにタイムアウト／キャッシュを追加する」。→ explained。

ブロック — 不正な ID。 /opik-explain 123。get_trace_content で何も見つかりません。→ not_found：「プロジェクト X にトレース 123 はありません。ID／プロジェクトを確認して再実行してください。」（コードは変更していません。）

アンチパターン

原因を示さずにスパンツリーをダンプすること。根拠となるスパンの入力／出力を読まずに原因を推測すること。最も根拠の強い原因を1つ挙げずに、可能性を5つ列挙すること。クリック可能な Opik UI リンクではなく、スパン／トレース ID だけを返すこと。コードを編集すること（このスキルは説明を行います。変更は opik-instrument／opik-test または開発者が行います）。TracePublic に対して .project_name を呼び出すこと（例外が発生します。project_id を使用してください）。project_name を指定せずに search_spans(trace_id=…) を呼び出すこと（デフォルトのプロジェクトが検索され、結果が空になります）。

参考資料

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

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