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 ishealthy, 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
toxicityandpii_leakagewhere 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
The Issues list
A project with no open issues shows an empty state that explains issues are grouped every 10 minutes from failed and degraded traces, with a link to Traces.
24h, 7d, 30d, and 90d and opens on 7d. When issues need attention, the verdict band sits above the strip of key figures, so the headline is the first thing you read.
Each row shows:
Filter the list with the chips above it: search, Verdict, Type (only the types that have issues in the selected range are offered, each with its count) and, when attribution is on, Layer.
The Agent column appears only when at least one issue has an agent recorded, so you never see a column of dashes. Row actions stay out of the way until you need them: Generate fix (shown only for an issue with no suggestion yet, it opens the issue so you can generate one), Resolve, and Dismiss appear when you hover a row, select it, or tab to it with the keyboard.
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.
Titles
An issue reads cause · operation, for exampleserver_error · chat. A failing built-in evaluator or a failed SDK score reads <name> failed (for example toxicity failed · chat, or refund_accuracy failed · chat for the score rule refund_accuracy).
Possible issues
Some checks cannot prove a problem from the spans alone but see signs of it. Zespan raises those as issues too, labelled Possible issue, not confirmed, with the line “Zespan saw signs of this but has not proven it. It will not alert.”- They are listed after every proven issue, then by last seen.
- They never open an incident, send an alert or escalate on their own. Escalate to incident stays available, so you can still do it by hand.
- They have no derived cause and no automatic fix. When a detector finding can be proven later, the same issue upgrades in place to a proven one and then behaves like any other. “Repeated tool calls” issues stay possible: a real loop shows up as a separate “Agent loop” issue.
- ZespanPilot and MCP name them as possible issues, and they are left out of regression capture and the value (ROI) figures.
- The label also shows on the older Issues list and issue page, in Issues on this trace on a trace, and under compliance (Possible issue (not confirmed)). Their automatic fix suggestion reads “Possible issue — Zespan will suggest a fix once it is proven.”
Kinds of issue
An issue has a Type (a column in the list, a small tag on the issue page) that says what kind of problem it is, so you can tell a provider outage from an agent that quietly did the wrong thing. Zespan works the kind out from the issue itself; nothing is configured and no extra data is stored, so it is the same on every project. When the issue itself does not say which kind it is, it gets no tag rather than a guess: an issue keyed on a custom evaluator (a custom check could be about quality, speed or cost), on the built-in cost budget evaluator, or an older degraded issue with no signal.Issues raised from a functional check or a domain pack’s check appear for every project whose functional detectors are on (the default is shadow, where findings stay visible to owners and admins only and never become issues; your operator turns the detectors on per deployment or per project). Zespan raises one issue per check and agent, from findings it proved from the stored spans after the detectors were turned on (when a project is first turned on, findings from the hour before are included; older ones still show on their traces but are not raised as issues): its cause reads Verified from spans, and the fix and prevention are the check’s own wording. A finding the check marks “likely” is raised as a possible issue; a “signal” is not turned into an issue. The issue counts the traces the check fired on, moves its last seen time forward as new traces are found, and an issue you resolved or dismissed comes back only when a new trace shows the problem again. Turning the detectors back to shadow or off hides these issues everywhere (list, issue page, counts, ZespanPilot) without deleting them. No AI model is called to raise one, Zespan does not open an incident from them automatically, and it does not queue an automatic AI remediation for them, because the cause and fix are already on the page (you can still generate a suggestion from the issue page). The shared demo shows them too: see Quickstart → What you see in the demo.
Signals
When a trace fails without erroring, the Cause column names the signal that identified it rather than an error code.user_retry, agent_loop and repeated_tool_calls 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.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.
Where it started
When an issue’s cause has been proven from its spans, the issue page shows where it started under the root cause: a chip such as Caused by Retrieval or Likely Tool, how sure Zespan is, why, the role that owns a fix for that layer (for example Fix owner: Data and search), and the line Failed at: Tool step. A weaker claim reads Possibly …, muted and always with its evidence. When two layers fit equally it reads Either … or … with the step that would settle it. See Stack layers for the layers, the tiers and when a claim is shown. Under the chip, Was it Retrieval? Yes / No, it was… records your answer so Zespan can measure how often it is right, see Confirm or correct the layer. On the list, a Layer filter keeps the issues that started in one layer, and a line above the table says how many issues it covers, for example 9 analysed issues, 6 in Retrieval. Each analysed issue’s row carries a small tag with its layer next to the cause.The layer filter covers analysed issues only: those whose cause has been proven and whose origin is shown at Likely or better. An issue that has not been analysed yet is not counted in any layer, and the list says so. The filter appears once at least one issue has a layer.
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.
Issue detail page
Clicking into an Issue (/{orgSlug}/{projectId}/issues/{issueId}) shows:
- The verdict level, current status, occurrence count, and first and last seen. Times read as relative (“4h ago”); hover one for the exact local time. A link to the associated prompt appears when this issue’s traces share one. The agent shows when the traces recorded one, and nothing shows when they did not
- Escalate to incident, Mark resolved and Dismiss actions (same semantics as the list — see above)
- The Root cause card, then Where it failed (evaluator and score-rule Issues only), then the Suggested remediation card when it has something to add, then the Sample traces table (up to 10 representative traces from the cluster, each linking to its full trace)
Root cause, Fix and Prevent
The Root cause card is computed from the issue’s own spans with no AI, so it is there with AI processing off and before any suggestion exists. It has:- A badge: Verified from spans (proven) or Auto-detected (matched by a rule from the recorded error, not proven)
- One paragraph saying what happened. Times inside it read as relative times, never raw timestamps
- An evidence line that reconciles the numbers on the page, for example: “12 occurrences. Found 2 matching failures in 2 retained traces; 3 are needed to confirm, so this cause is not confirmed yet.” Occurrences are how often the pattern happened; the traces are the ones still retained. A cause is confirmed only once enough matching failures show it; when it is not confirmed for another reason, the line quotes that reason. For an agent loop it says how many of the retained traces checked showed the loop
- Fix and Prevent, each a numbered list of steps. Fix has Open sample trace. A Prevent step that sets up an alert on a metric Zespan alerts on (error rate, tool error rate, latency, cost, guardrail block rate, blocked, truncated or empty-response rate) has Add alert, which opens the new alert dialog on the Alerts page with that metric and the step as its name, for you to review and save. A step whose subject has no alert metric (token counts, stream finish signals, evaluator pass rates) has no button. A step that adds a guardrail has Create guardrail, which opens the guardrail builder. On the shared demo these two ask you to sign up instead
Issues from evaluators and score rules
An Issue raised by an evaluator, or by a score rule on a score your code sends, has a Root cause card too, once its sampled traces hold scores below the bar. A score counts when its verdict is not pass: a fail or a warning. The card is Auto-detected with medium confidence and titled with the evaluator’s name (a score rule reads “Score rule csat”). It says how many of the sampled traces scored below the bar, with the warnings counted, then one judge reason:- When the same reason repeats, it reads, for example, “Correctness scored below the bar on 3 of 5 sampled traces. The judge said most often: “Quoted the wrong refund amount””.
- When every trace has a different reason, it quotes the newest one and says so: “Latest judge reason: “…””. One trace’s reason is never presented as the reason for all of them.
- Reasons are trimmed to 300 characters.
- For a score rule, your code sent the number and Zespan has no judge reason to quote, so it reads “Score rule csat tripped on 2 of 4 sampled traces. Your code sent csat = 0.1 most often (rule: below 0.5)”, or “The latest value your code sent was …” when the values differ.
The Suggested remediation card
The card appears only when it adds something beyond the Root cause card:
A card that would only say “pending” for something that will not come is not shown. On the shared demo, Zespan never generates a remediation for a visitor; an issue shows one only when a saved suggestion was generated beforehand, labelled “Generated by ZespanPilot on from N sample traces”.
When the failing tool is one that moves money, sends a message, publishes or deletes (by its role), a timeout, network, server-error or rate-limit cause does not say “retry”. The fix says a timed-out call may already have succeeded, to check the call’s status (for a payment, look it up) before trying again, and to send an idempotency key so a retry cannot apply twice. The same applies to the cause Zespan proves from spans, and a suggested remediation follows the rule too (a suggestion written earlier is hidden, and nothing is regenerated automatically: click Generate suggested remediation for a new one). Three things count, in this order: a role you confirmed in Settings > Detectors (it always wins), the default role of a detector pack that is on for the project, and, when neither names the tool, a guess from its name. A guessed role is worded as a guess (“This tool looks like it moves money (not confirmed in Settings > Detectors)”): the careful steps stay, but nothing is stated as fact, so confirm the role to make the advice firm. Names that only look up or read something (for example
fund_lookup, charge_battery) are not guessed as payments.Generate suggestion (remediation)
Available on every plan. Automatic analysis (below) needs Pro or higher; generating one by hand does not.
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.
Automatic remediation suggestions
Requires the Pro plan or higher. 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.
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.
Prevent
When an issue has a cause proven from its spans, its detail page can show a Prevent section (on by default; see Policies). It always starts with the written advice for that cause, whatever your plan. Below it:- No draft yet. Zespan can build a policy from the agent’s own recorded traces and test it. Create draft needs the Pro plan and permission to draft.
- Proven on your traffic. For example “Caught 12 of 12 similar traces, 0 false hits, over 14 days.” Review opens the drafted policy on the review screen. Apply… explains that applying starts at dryrun, where nothing is blocked, and sends you to the same review and apply screen. Nothing is applied from the issue page.
- Not proven. The plain reason with its counts and next step, for example “It would also have stopped 7 normal traces (at most 5 allowed).” See How a prevention draft gets proven. No policy is offered and the advice above still applies.
- Confirm before a destructive call. For a finding where a tool you declared destructive ran with no confirmation step, the draft reads Waiting for confirmation data until your SDK sends confirmations (with code to copy and a link to Confirmations), then Would have stopped N of M calls in shadow (dryrun logs only) and how many of those followed a plain request, where a missing confirmation is a judgement call. This version can only warn; it cannot block a call, and it checks that your app recorded a confirmation, not that the end user agreed. See Policies.
- Below the Pro plan. You see the advice, a line that drafting is on the Pro plan and above, and the kinds of prevention that exist for that cause. No draft is built or shown.
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
- Stack layers — what the layer chip means and when it is shown
- Policies — where a drafted policy shows its proof, and how it is applied
- Instrumentation — see what Zespan can observe, set who gets each layer, and confirm or correct a layer
- How a prevention draft gets proven — clean traces, the counts behind “not proven”, back-dated traffic and multi-agent pipelines
- Detectors — choose which detector packs run (Off, Preview or On) and confirm what your tools do

