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). Traces that land in the same group become occurrences of one Issue. 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.

​
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, and error code) 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 hands those findings to ZespanPilot to write a short markdown suggestion — the likely underlying cause and one concrete next step, reasoned over the recurring pattern rather than a single occurrence.
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