opik-explain

Explain — Root-Cause an Opik Trace and Ground It in the Code

Definition of done: a grounded root cause for the requested trace (or pattern), tied to specific evidence spans and paired with exactly one suggested next step. "Grounded" means the explanation names the failing/anomalous span and connects it to the code or data that produced it — not a restatement of the trace. If the target can't be fetched or read, stop at the first genuine blocker and return one concrete next step. A trace dump is not an explanation.

Operate: investigate over the real trace data, reason against the repo, commit to a single most-likely root cause with its evidence — and change no code. This skill is read-only by design.

Inputs

The entry point is /opik-explain <trace-id> (one trace) or /opik-explain <describe the behavior> (a pattern to find and explain). Infer the rest; treat these as optional overrides:

• project name (default: inferred from config/repo) · time window for a pattern (default: recent) · a known-good trace to compare against.

Ask only at a genuine, non-inferable blocker (see Blockers).

Activation — the only in-scope work

1. Resolve the target

• A trace id (uuid-shaped): explain that one trace.
• A behavior/pattern ("hallucinations since the prompt change", "slow responses"): search for the matching set (below), then explain the shared cause.
• Confirm Opik is reachable: if ~/.opik.config exists or OPIK_API_KEY is set, use it. Otherwise → Blocker ("run opik configure, then rerun").

2. Fetch the trace and spans — MCP first, SDK fallback

Check whether the hosted Opik MCP is connected and prefer it; fall back to SDK scripting when it isn't.

• MCP connected: use the MCP to read the trace and list/read its spans.
• No MCP: fall back to the SDK.

Either way, read every span's input/output/error/duration.

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.