Health & Troubleshooting

The KPI catalog and each definition detail page show a live health badge for every definition, fed by the engine's own run ledger. This page explains what the badges mean and how to resolve the errors you can encounter while authoring, installing, and enabling KPIs.

Health badges

Hovering a badge shows the last run time and status, the run counts (ok, error, and partial) over the window it names, and the last error message, if any.

The health window

The badge counts the definition's last 12 runs, not a fixed stretch of calendar time. That window means the same thing at every cadence: 12 runs of a 5m definition is about an hour of behaviour, 12 runs of a daily definition is about twelve days — and in both cases a single transient failure ages out of the badge after 12 clean runs.

The tooltip always names the window it actually covers. It reads Last 12 runs once a definition has run at least that many times, and Last 3 runs for a definition that has only run three times so far — the counts are never padded.

Lag

Active badges also show lag — the time since the engine's committed progress point for that definition. Everything up to that point has been computed and persisted.

Lag is judged against the cadence rather than in absolute terms. While the definition is less than one cadence interval behind, the badge reads on schedule; the raw lag appears only once it reaches a full interval, which is the point at which the engine has actually missed a window.

This matters most for daily definitions: their window closes once per day, at the end of the site-timezone calendar day, so mid-afternoon they legitimately sit many hours behind the current time. That is on schedule, not a backlog. A daily definition showing lag 25.0h, on the other hand, has missed a day.

Run statuses

Each engine run for a definition ends in one of three statuses, visible in the badge tooltip's run counts:

• ok — the run computed all matched assets.
• partial — the run completed, but some matched assets were excluded — for example assets still missing a required per-asset parameter value. The engine computes the rest rather than silently skipping the run.
• error — the run failed; the error is recorded and shown verbatim.

Enable and disable

Enabling is the activation gate: it resolves the population, creates a KPI variable on every matched asset, and starts scheduling. Two conditions block it, with the reason shown verbatim:

Disabling stops computation at the next engine tick. Already-computed values are retained, and the definition can be re-enabled at any time from the catalog's toggle.

Preview issues

• The preview returned no values for this range — either no input data exists in the range, or every window in the range was not computable (for example a ratio whose denominator was zero throughout). Widen the range or check that the input variables carry data.
• Preview errors (for example range limits) come from the engine and are shown verbatim.
• The computed on the … tier note tells you which storage tier served the computation: clickhouse for recent history, trino for older history, or mixed when the range spans both. Results are the same either way; older ranges can take longer.

Backfills

The Backfills panel on the definition detail page computes history for ranges before the definition was enabled — or recomputes a range after fixing data.

1. Pick a range under Compute history from / to.
2. Click Queue backfill.

Backfill jobs split the range into chunks and drain after live computation ticks, so live results always take priority. The panel lists each job's range, status (queued, running, done, error, cancelled), requester, and last update; job errors are shown verbatim. Backfilled values are computed by the same engine path as live values.

Pack install errors

Both cases block the whole pack and write nothing — see KPI Packs for the full install flow.