Before your first trace
System Health is available on every plan, including Free.
- A wait pill at the top reads “No traces yet” until your SDK sends its first event, then “First trace received,” then “N traces · warming up” as data accumulates.
- The verdict slot stays blank with an explanation — “No verdict yet” — until there’s enough traffic to judge. One trace alone isn’t enough to compute an error rate, so the page says so rather than guessing.
- Every KPI slot (error rate, P95 latency, spend today, requests) renders as an empty, dashed placeholder with a
—value and a WAITING badge instead of a fake number.
Product tour
The product tour is three steps: this Overview, the cause and fix on an issue, and ZespanPilot. It skips anything your plan or project doesn’t have (for example an issue when you have none yet; on the shared demo all three steps run, and ZespanPilot answers its starter questions there), and gives up on a step after 3 seconds if what it points at never appears, so it can’t get stuck. If every step is skipped it simply closes. Zespan offers the tour once per browser, as a small toast after your first trace. It never starts on its own. On the shared demo that offer is replaced by the demo story, a side panel that follows one silent failure from the Overview to its fix. If a project has ingested traces before but the currently selected time range has none, you get a different, narrower empty state: a “quiet window” message if the gap is under 48 hours (with a one-click jump to a wider range), or a “we haven’t heard from your agents” warning with likely causes (rotated API key, SDK not initializing, network/firewall blocking ingest) if the gap is longer.When a page can’t load
Every dashboard page shows the same panel when its data fails to load: “We couldn’t load …” (for example, “We couldn’t load traces”), a plain-language reason, and a Retry button. Raw server messages such as “Internal error” are never shown.Setting your health thresholds
Before any traffic flows, you can tell Zespan what “broken” means for this specific project. A 20% error rate is a crisis for a payments agent and a normal Tuesday for a research prototype — only you know which applies here.
These values are saved per project and used automatically once real data starts arriving — you don’t have to touch them again. The System Health verdict banner judges your live metrics against these numbers, not a generic fixed threshold.
The verdict banner
The banner at the top of the page appears only when something needs attention, so a healthy project opens straight onto its key metrics:- System degraded — names exactly which threshold was breached and by how much (e.g. “Error rate 12.0% is above your 5% limit”), with the number of open alerts or threshold breaches beside it.
- Some data unavailable — a source the verdict depends on, such as active alerts or agent operations, didn’t load. The banner says which one and doesn’t claim the system is healthy, because it can’t confirm that.
Key metrics and Needs attention
A strip of up to five tiles sits below the banner: Requests, Spend, Error rate, P95 latency, and Tool success. Each tile shows its value, the change against the prior period, a sparkline, and your threshold as a caption. A project with no tool calls has no Tool success tile. The order follows the verdict — reliability metrics come first while the system is degraded, volume and spend first when it isn’t. If you customised the widgets, your selection and order are used instead. Beside the chart, a ranked Needs attention list shows what to look at next, ordered by the cost of leaving it. It merges open alerts with concrete problems such as the agent with the worst error rate, an operation exceeding its latency target, or a cost spike, each with a direct link to investigate. All incidents at the bottom opens the incident list. The ZespanPilot digest — an AI-generated summary of what changed, with quick-action links into the relevant page — opens from the sparkle button in the verdict banner. The digest is generated once per project and time range and then reused for a short while, so reloading the page or several teammates opening it doesn’t generate it again. If the AI can’t produce a digest right now (for example the AI provider is unavailable), Zespan shows a simpler summary built from the same numbers instead, and tries the AI again after about a minute; the next successful digest replaces it. An AI-written digest carries the notice AI-generated by <model> — may be inaccurate; check important figures.Changes on the chart
The chart under the key metrics marks changes as thin dashed lines on the bucket they happened in: deploys and other changes you report from your CI, prompt deploys, agent promotions, and configuration and policy edits. Hover a marker for its title; several changes in one bucket become one marker named “3 changes”, and a busy chart shows at most 12. The Changes button above the chart hides or shows them and remembers your choice in this browser. The Changes page lists every one.Failures by layer
When failures have been analysed, Failures by layer under the key metrics shows where they started: a bar per stack layer for the range you picked, counting only Caused by and Likely claims. Claims that rest on a guess (for example a tool whose name looks like a retriever) are their own series, and failures where two layers fit equally are one Either / or bar, never split between the layers. Every number is repeated in a list under the chart. Lower-confidence claims are not charted; a note says how many there are. The card is absent, not empty, when nothing has been analysed or when attributions are not shown to your role. In shadow mode only owners and admins see it, with a Shadow tag: those counts are not shown to the rest of the team yet. See Stack layers.Drill-down tabs
The collapsed Breakdown section at the bottom of the page holds tabs that let you go deeper without leaving the page:Customizing your dashboard
Click Customise in the page header to open a panel where you can toggle which KPI widgets are tracked for your project — grouped into Essentials, Cost & Usage, Performance, Health, and Explore — or apply a starting layout (Engineering, Operations, or Leadership). Your selection is saved to your project’s dashboard preferences. The first time you complete onboarding you’re also prompted to pick one of these starting layouts.Finding your way around
The sidebar groups the project’s pages by the job you are doing: AI (ZespanPilot), Observe (Overview, Traces, Agents, Sessions, Tools, Models, Users, Performance), Fix (Issues, Incidents, Errors, Alerts, Changes), Evaluate (Evaluations, Guardrails, Policies, Simulations, Datasets, Annotations), Cost (Costs, Cost attribution, Value, Forecasts), Build (Prompts, Playground) and Govern (Compliance, Audit log, Instrumentation, Settings). AI, Observe and Fix start open and the others start collapsed; the group that holds the current page is always open. Settings also has a gear link next to your profile at the bottom of the sidebar. Instrumentation appears in the new interface only. In the classic sidebar the groups are AI, Observe, Evaluate, Build and Monitor (the cost pages, Errors, Issues, Performance, Alerts, Incidents, Changes and Compliance), with Settings at the bottom. To keep the pages you use most within reach, pin them: hover a sidebar item and click the bookmark that appears, or focus the item and press P. Pinned items move to a Pinned group at the top of the sidebar. Click the filled bookmark (or press P again) to unpin. You can pin up to five items, and pins are remembered in the browser you pinned them in, so they don’t follow you to another device. Settings opens a page with its own navigation on the left, grouped by what you’re changing, with each section on its own page: Project (General, Environments, API keys, LLM connections, HTTP targets), Organization (Model pricing, Team, Billing), and Account (Profile, MCP keys, Privacy). Account pages apply to you personally, not to the project.Time range
The range selector in the top-right controls the window all KPIs, the trend chart, and the breakdown tabs are computed over: 1h, 24h, 7d, or 30d, plus a custom date range from the layout menu. The Overview opens on 24h. Today is no longer a separate choice because it is the same question as 24h; a saved link withrange=today opens as 24h. The overview API’s finest window is 24 hours, so 1h shows the last 24 hours (its tooltip says so). Data refreshes from a 5-minute cache; use the refresh button next to the range selector to force an update (rate-limited to once every 5 seconds).
Range controls on other pages
Live views read the present and offer1h, 24h, 7d, 30d. Analytics and list pages read a past window and offer 24h, 7d, 30d, 90d, and open on 7d. A page whose data can’t be served for a window shows a subset of that set, in the same order.
Today was removed from the Sessions, Guardrails, and organization Analytics controls for the same reason. On Sessions and organization Analytics a saved
range=today link still works and reads as the last 24 hours.
When a range has no data but the project has activity at other times, the page says so — for example “No sessions in the last 24 hours” — and offers a wider range. That is different from the first-run empty state, which means nothing has arrived yet. On pages such as Tools, Simulations, and Compliance, a KPI strip whose tiles are all zero or blank is hidden rather than shown above an empty page.
How time ranges are measured
Every page and API endpoint that takes a range uses the same rule, so the same metric over the same range is the same window everywhere:
For each trailing range the comparison period is the equal-length window immediately before it. Which ranges an endpoint accepts varies (for example the overview takes
today, 24h, 7d, and 30d).
Overview API
GET /projects/{id}/overview takes range (default today) and timezone. An unrecognised time zone returns 400. Fields that are easy to misread:
If your weekly spend more than doubles versus the prior week, a cost-spike banner appears above the checklist with a direct link to the Costs page.