Skip to main content
The Issues page turns N separate failing traces that are really the same underlying problem into one row: a recurring Issue with an occurrence count, a first/last-seen timestamp, and a link to a real sample trace.
Issue clustering runs automatically in the background — there’s nothing to configure. It requires the Pro plan or higher.

​
How clustering works

A background worker re-runs the same deterministic verdict classifier used on every trace detail page (the one that decides whether a trace is healthy, degraded, or failed) against recent candidate traces, then groups matches by (verdict level, primary operation, error code, signal). Traces that land in the same group become occurrences of one Issue.

​
What counts as a candidate

Clustering used to consider only traces where a span errored. It now also considers traces that failed without erroring:
  • an evaluator scored the trace below its configured threshold — or above it, for evaluators like toxicity and pii_leakage where a high score is the bad one
  • an evaluator returned a non-passing verdict outright, which is how categorical rubrics (safe / borderline / unsafe) are judged
  • a behavioural signal fired — see below
  • a tool call was retried, or ran far slower than its siblings
This is the class of failure where nothing throws: the agent returns a confident wrong answer, or takes a wrong action, and no log line says so. Because it’s the same classifier your trace detail page already shows you — not a second, fuzzier system guessing from raw scores — an Issue’s grouping key means exactly what it says: these traces failed the same way, for the same reason, on the same operation.

​
The Issues list

Each row shows: Click View details to open the Issue detail page for the full sample-trace list and the remediation suggestion feature. View sample trace jumps straight to one real occurrence in the normal flame graph view, so you can investigate the actual failure without leaving the list.

​
Signals

When a trace fails without erroring, the Cause column names the signal that identified it rather than an error code.
user_retry and agent_loop are behavioural signals: observations about how a conversation went, not judgements of what the agent said. A person may rephrase a question for their own reasons, and some agents legitimately call one tool repeatedly. Treat them as evidence worth reviewing, not as proof the agent was wrong. Trace detail labels them Evidence for exactly this reason, and never shows them a pass/fail threshold — there is no rubric they were scored against.
Two issues on the same operation with different signals stay separate. A toxicity failure and a user_retry observation on chat are different problems and get their own rows, their own occurrence counts, and their own regression datasets.

​
Resolved vs. dismissed

Both actions remove an issue from the open Issues list — the difference is what they communicate, the same distinction Sentry-style issue trackers draw between the two: Neither is permanent: if the aggregator detects a fresh occurrence of the same cluster (same verdict level, operation, error code, and signal) after an issue was resolved or dismissed, the issue reopens and reappears in the open Issues list. Resolving an issue you haven’t actually fixed just means it comes back sooner.
An issue with a rapidly climbing occurrence count is usually a better place to start than sorting the Traces log by timestamp — it’s already told you this isn’t a one-off.

​
Issue detail page

Clicking into an Issue (/{orgSlug}/{projectId}/issues/{issueId}) shows:
  • The verdict level, current status, occurrence count, and first/last-seen timestamps
  • A link to the associated prompt, if this issue’s traces share one
  • Mark resolved / Dismiss actions (same semantics as the list — see above)
  • A Sample traces table — up to 10 representative traces from the cluster, each linking out to its full trace detail view
  • The Generate suggestion remediation feature, described below

​
Generate suggestion (remediation)

Requires the Pro plan or higher, same as the rest of the Issues feature.
Click Generate suggestion on the Issue detail page to have Zespan investigate the pattern for you: it runs the same root cause analysis used on individual traces against up to 5 representative sample traces from the cluster, then writes a short suggestion — the likely underlying cause and one concrete next step, reasoned over the recurring pattern rather than a single occurrence. Every statement in that suggestion is checked against the record it refers to before you see it, and each one shows what it rests on — the trace, prompt, policy or metric behind it — linking through where that record has a page.
Two things follow from that check, and both are deliberate:Suggestions are shorter and more specific than they used to be. Statements that cannot be tied to a record in your project are not shown, so text that previously read as confident but rested on nothing no longer appears.Sometimes there is no suggestion at all. Where nothing could be checked against your data you will see “No suggestion: nothing here could be checked against your data” rather than a plausible-sounding guess. A suggestion you cannot verify is worse than none — it costs you the time to act on it and the trust you would have placed in the next one. If a run stops early it is labelled incomplete alongside whatever was verified.
This is a markdown suggestion only. Generating it never opens a pull request, proposes a code diff, or touches any source repository — Zespan has no repo-connection integration today. Treat it as a starting point for your own investigation, not an automated fix.
The suggestion is cached per issue, so regenerating it (e.g. after revisiting the page) is instant and doesn’t re-run the analysis or incur additional cost. If none of the sampled traces can be analyzed — for example, they’ve aged out of trace retention — you’ll see an error instead of a suggestion; try again once the issue has recurred and produced fresher samples.

​
Automatic remediation suggestions

Requires the Pro plan or higher, same as manual Generate suggestion. Free and Solo plan Issues are not auto-analyzed, but you can still generate a suggestion yourself at any time using the manual button above.
Once an Issue has recurred three or more times, Zespan generates a remediation suggestion for it on its own — you don’t have to ask. The suggestion appears on the Issue detail page labelled with the time it was generated, so opening a recurring failure usually means reading the analysis rather than requesting it. The analysis reasons across the Issue’s sample traces rather than about one of them, and says which situation it found:
Suggestions are text only. Zespan never opens a pull request, edits your prompts, or changes your configuration as part of generating one — you decide what to act on.
You can still press Generate suggestion yourself on an Issue that hasn’t reached three occurrences, or ask ZespanPilot directly: “investigate the rate limit issue on chat.completions.create.”

​
Issues feed regression tests

Once an issue has recurred 3 or more times, it’s automatically captured as a test case in a Production Failures dataset — turning your own incident history into a regression suite your CI can replay against a candidate change. See Regression testing from production failures.

​
Next steps

  • Traces — the underlying root-cause analysis that powers remediation suggestions
  • ZespanPilot — the AI copilot that writes remediation suggestions
  • Guardrails — if an issue’s error code traces back to a guardrail violation, promote that violation into a permanent rule
  • Datasets — replay recurring issues as regression tests
  • Incidents — for anomaly-driven correlation across metrics, rather than verdict-based trace clustering