Skip to main content
A finding is a silent failure Zespan found by checking a trace against what is stored for it: an answer that is not valid JSON, a tool that was called but is not defined, a total that does not add up. Nothing threw, so nothing showed in your logs.
Findings are on by default in the dashboard. Self-hosted: build the dashboard with NEXT_PUBLIC_FINDINGS_UI=0 to hide them. What each person may see is decided as described in Who sees findings.

Findings on a trace

When a trace has findings, a Findings on this trace card sits under the verdict. Each finding is a card with the same parts, top to bottom: A part is left out when Zespan has nothing to say for it. Nothing is filled in. A trace with no findings shows no card.

Tiers

Only a Proven finding is described as a fact. A tier this version does not know is shown as Signal. A finding marked Needs review is one Zespan held back for a person to look at. Only owners and admins see that queue.

The Findings page

Findings in the sidebar lists the project’s findings. The summary. The top of the page says in one sentence how much needs action, for example “12 open findings. 3 need action now.” Needs action means the finding is both Proven and High severity, and not waiting for review. Under it are the counts by severity and by trust level; click a count to filter the list (a count of zero is greyed out, the one you picked is highlighted, and clicking it again turns it off). A Needs review count appears when the list holds findings that need review. The counts follow the filters below them, and the page says so when a filter is on. When the list is cut at 100, the sentence says “The latest 100 findings” instead of a total. When most findings come from one agent, the summary names it. The list. The list is a table with one row per problem. Findings that say the same thing (same check, same agent, same cause and fix) are folded into one row that says how often it happened, for example “23 times”, so a problem that repeats does not bury the others. Each row shows how serious it is, what the problem is with one plain line of cause, how sure Zespan is, the agent, the layer where it broke, how often, and when it was last seen. On a phone the trust and the count sit under the problem title. By default the table is Needs action first: ranked by severity, then trust level, then how recent, and grouped by what broke (for example “Claims against effects”, or a domain pack such as “Customer support”). With a handful of problems every group is open; with many, the first group is open and so is every group that holds something that needs action, and you can open or close any group. Choose Newest first for one flat table in the order the findings were found. Opening a finding. Click a row to open its detail beside the table: what happened, why it happened, what to do next, the path through the layers, a link to the trace at the failing step, Prevent when it is on, and Details. A problem that repeated also has Happened N times. See each one., which lists every occurrence with its own numbers and its own trace link. Nothing is dropped by the folding. Filters. Time range (24 hours, 7 days, 30 days), Trust and State (open or needs review) are always visible. Agent (exact name) and Check family (D1 to D7 and the domain packs, named as on Silent-failure coverage) are under More filters, which opens by itself when one is set. Clear filters resets everything, including a count you clicked. The page shows up to 100 findings at a time and says so; narrow the filters to see others. Each finding links to its trace, with the failing span selected.

Simple and Technical

The switch at the top right chooses how much the table and each opened finding show. Your choice is remembered in this browser.
  • Simple (the default) shows the plain columns, and Details stays closed when you open a finding. Use it to triage, and to share with someone who does not work with traces every day.
  • Technical adds the check id and the trace id to the table, shows the full path through the layers, and opens Details when you open a finding, so the evidence, ids and reasons are visible without a click.
Both views show the same findings in the same order; only the depth differs.

Who sees findings

Findings are recorded from the first trace, but they are shown only when the project’s detectors are on. While they run in preview, owners and admins see them marked Preview and everyone else sees nothing. When the detectors are off, nobody sees any.

Free and paid

Every finding shows its cause, fix and written prevention advice on every plan. Drafting a policy that Zespan tests on your own recorded traffic needs the Pro plan; below it the Prevent section shows what kinds of prevention exist, with no draft content.

Checks that could not run, and why

A check that needs an input your SDK did not record reports that it could not run and names the input, instead of passing. Readiness is on by default (self-hosted: CAPTURE_READINESS=off turns it off), and GET /v1/projects/{id}/traces/{traceId}/functional/unchecked lists the checks that could not run on a trace, and GET /v1/projects/{id}/functional/readiness?days=7 shows, for the project, the share of checks that could run (readiness, not a quality score), the missing inputs that cost the most, whether capture can fix each one, and what to do. Neither route holds any content. The reasons and what each input needs are listed in Capture fields.

Traces from before setup

Detectors read new traces as they arrive. To check traces sent earlier, an Owner or Admin can use Re-check recent traces in Settings → Detectors: see Re-check recent traces.

Next steps

  • Issues — recurring failures grouped from failed and degraded traces
  • Traces — the verdict and where it broke
  • Silent-failure coverage — which failures are checked and the check families
  • Stack layers — what the layer chip means
  • Policies — where a drafted policy shows its test results