​

Dashboards and monitors

Dashboards turn EvalGate’s authoritative evidence into reusable, versioned metric contracts. A dashboard never stores a hand-entered result: every widget references an approved metric definition, every query returns completeness metadata, and every alert transition links back to the metric-cache evidence that caused it. Status: Beta · Owner: Evidence & Reporting · Last verified: 3.7.0-rc (2026-07-13)

​

Start in the control room

Open /dashboards. The control room has four work areas:

• Overview renders the selected published dashboard. A failed widget stays isolated; healthy sibling widgets remain usable.
• Dashboard builder creates a dashboard and its first immutable version from an approved metric.
• Metric definitions previews, saves, versions, and approves authoritative metric contracts.
• Alert rules creates and manually evaluates stateful thresholds using the same evaluator used by scheduled execution.

Creating or changing definitions, dashboards, shares, or alerts requires the corresponding write scope. Metric approval requires an admin. A personal dashboard is visible only to its owner; project and organization dashboards are visible to organization members, but non-owners see published versions only.

​

Define an authoritative metric

A metric definition is an immutable, content-hashed contract with a stable metricKey and monotonically increasing version. Define all of the following before saving: Supported sources and measures are intentionally finite:

​

Understand query completeness

Every metric query has one of three statuses:

• success: all selected records were comparable under the metric contract.
• partial: a valid value exists, but unknown records or another disclosed completeness condition remains.
• failed: the source, filter, comparability rule, limit, or query could not produce a valid result.

Results include the value, known count, unknown count, warnings, time series or grouped values when requested, and exact source evidence identifiers. Cached results retain the metric-definition version and query hash; bypassing cache creates a new append-only result rather than mutating old evidence. Queries are bounded to 10,000 selected source rows. Exceeding that boundary returns a failed result with an explicit query-limit code. It is never represented as a complete aggregate.

​

Build and publish a dashboard

A dashboard snapshot contains a 12-column layout, up to 20 global filters, a manual or interval refresh policy, and 1–40 widgets. Each widget declares:

• a unique stable key and one of 13 supported visualization types;
• an approved metric-definition ID;
• position and size on the 12-column grid;
• manual or interval refresh, with intervals from 30 seconds to 24 hours;
• a relative drilldown path to Logs, Experiments, Evaluations, Online Eval, Review, or Costs.

Overlapping positions are normalized deterministically. Publishing freezes the version, layout, widget references, and content hash. Adding, updating, or removing a widget creates a new draft version; it does not change the published version in place. When a dashboard renders, each widget executes independently. The overall render becomes partial if one widget fails while another succeeds. The UI keeps valid values and their evidence links visible and labels the failed widget with its actual error.

​

Share a pinned view safely

The dashboard owner can create an expiring view-only link for a published version. The copied URL opens /dashboards/shared/{token} and renders the exact version captured by the link—not the owner’s latest draft or a later publication. Share tokens are stored as hashes, expire between five minutes and one year, and can be revoked. They do not grant anonymous or cross-organization access: the viewer must authenticate as a member of the same organization and hold evaluation-read permission. A revoked, expired, malformed, or cross-organization token returns not found or forbidden without disclosing the dashboard.

​

Configure stateful alerts

An alert rule references an approved metric definition and an immutable rule version. Operators are gt, gte, lt, lte, eq, and outside. An outside-range rule requires both lower and upper values. Use forConsecutive to require repeated breaches before firing and resolveAfterConsecutive to require repeated healthy evaluations before resolution. The evaluator uses these states: Transitions are deduplicated by rule version, transition state, and configured time bucket. A durable event retains the metric-cache ID, observed value, prior/new state, threshold contract, and reason. Enabled delivery channels write in-app notifications and webhook delivery attempts; attempts remain inspectable even when delivery fails.

​

API workflow

The TypeScript SDK, Python SDK, and CLI do not yet provide a complete dashboard-and-alert convenience workflow. Use the authenticated REST contract; do not depend on undocumented web-app calls.

​

Failure and recovery

​

Verification evidence

The release-candidate acceptance evidence covers:

• metric and alert unit contracts for rates, percentiles, timezones, unknowns, comparability, partial composition, state transitions, and deduplication;
• authenticated API tests for scope enforcement, validation, exact-version rendering, and explicit failures;
• real PostgreSQL invariants for tenant isolation, immutable definitions/versions, authoritative queries, cache history, sharing, alert events, notifications, and delivery attempts;
• accessible control-room tests for partial rendering, metric authoring, no-code dashboard creation, alert evaluation, and pinned shared views; and
• authenticated golden path from source trace and saved Logs view through approved metrics, dashboard publication, evidence rendering, threshold firing, and durable delivery.