|
| 1 | +--- |
| 2 | +title: "Project health report" |
| 3 | +sidebarTitle: "Health report" |
| 4 | +description: "Get a deterministic verdict on your project's health — split into Flow, Execution, and Liveness — from the CLI, an MCP tool or prompt, or the HTTP API." |
| 5 | +--- |
| 6 | + |
| 7 | +**The health report answers one question — "is my project healthy, and if not, is the problem my code or the platform?" — with a deterministic verdict, not a dashboard.** The server computes the verdict from your telemetry; no LLM interprets it, so the same numbers always produce the same answer. |
| 8 | + |
| 9 | +Every report reads a live window of your project's data and returns a headline verdict, the evidence behind it, and a single suggested next action. The only report today is `health`. |
| 10 | + |
| 11 | +## What the report measures |
| 12 | + |
| 13 | +The report splits a project into three dimensions, each with its own verdict: |
| 14 | + |
| 15 | +| Dimension | Question | What a bad verdict means | |
| 16 | +| --- | --- | --- | |
| 17 | +| **Flow** | Is work starting? | Runs are queuing but not being picked up — a concurrency limit, a throttle, or a trigger spike. | |
| 18 | +| **Execution** | Are the runs that start succeeding? | Runs are failing or slowing more than your baseline — usually your code. | |
| 19 | +| **Liveness** | Is the telemetry fresh? | The data behind the report is stale, so the verdict can't be trusted. | |
| 20 | + |
| 21 | +Splitting Flow from Execution is the point: a project can be failing to _start_ work (Flow) while every run that does start _completes_ fine (Execution), or the reverse. The report names which one, so you know whether to look at your concurrency settings or your task code. |
| 22 | + |
| 23 | +Each dimension carries a severity — healthy, degraded, or failing — and the report leads with the worst one as its headline. The headline finding is expanded with its supporting metrics; the others collapse to a one-line verdict. |
| 24 | + |
| 25 | +## Reading the report |
| 26 | + |
| 27 | +Here is `trigger report health` for a project whose runs are backing up against the environment concurrency limit: |
| 28 | + |
| 29 | +```text |
| 30 | +/report health prod · last 1h · vs 7d normal |
| 31 | +
|
| 32 | +✕ Flow stalled — at your env concurrency limit for the last 40 min |
| 33 | +
|
| 34 | + concurrency 100/100 ▄▅▆▇████ 40 min at limit |
| 35 | + pending 1,240 ↑ 6× ▁▂▄▅▆▇██ (normal ~120) |
| 36 | + start latency p95 8.2s ↑ 4× ▁▂▃▄▆▇██ (normal ~2s) |
| 37 | +
|
| 38 | + why: runs are finishing at ~90/min |
| 39 | + nothing dead-lettered |
| 40 | +
|
| 41 | +✓ EXECUTION runs are executing normally |
| 42 | +
|
| 43 | +✓ LIVENESS fresh — telemetry current, updated 12s ago |
| 44 | +
|
| 45 | + read: limit saturated → incoming work exceeds capacity → backlog grows |
| 46 | +
|
| 47 | +→ Raise the env concurrency limit |
| 48 | + Read concurrency docs |
| 49 | + or do nothing — backlog drains in ~26.7 min once triggers ease |
| 50 | +``` |
| 51 | + |
| 52 | +The verdict reads top to bottom: |
| 53 | + |
| 54 | +- **Headline** — the worst finding, stated as a verdict with the breach window. Here Flow is stalled because concurrency has been pinned at its limit for 40 minutes. |
| 55 | +- **Evidence** — the metrics behind the headline, each with a sparkline over the window, its movement against your baseline (`↑ 6×` means six times normal), and an annotation (`40 min at limit`) or baseline (`normal ~120`). |
| 56 | +- **`why:`** — the facts that support the verdict, including what the problem _isn't_ (runs are still finishing, nothing is dead-lettered — so it's not your code). |
| 57 | +- **Sibling findings** — Execution and Liveness, each a one-line verdict. |
| 58 | +- **`read:`** — the causal chain in one line. |
| 59 | +- **Next steps** — the primary action first (`→`), then any alternatives. |
| 60 | + |
| 61 | +### The verdict vocabulary |
| 62 | + |
| 63 | +Every surface carries meaning in glyphs, never color alone, so the report is legible in a monochrome terminal or a plain-text MCP host: |
| 64 | + |
| 65 | +| Glyph | Meaning | |
| 66 | +| --- | --- | |
| 67 | +| `✓` | Healthy | |
| 68 | +| `⚠` | Degraded | |
| 69 | +| `✕` | Failing | |
| 70 | +| `○` | Genuinely unknown — neither good nor bad | |
| 71 | +| `⚑` | The data behind the report can't be trusted | |
| 72 | +| `↑` `↓` `→` | Above, below, or flat against the baseline | |
| 73 | + |
| 74 | +<Note> |
| 75 | + The markdown surface swaps the status glyphs for traffic-light emoji (`🟢` `🟡` `🔴` `⚪` `🚩`) — the one color cue a chat host that renders neither ANSI nor HTML can show. The glyph and the emoji mean the same thing. |
| 76 | +</Note> |
| 77 | + |
| 78 | +## Surfaces |
| 79 | + |
| 80 | +The same report renders four ways. |
| 81 | + |
| 82 | +### CLI: `trigger report` |
| 83 | + |
| 84 | +Print an interpreted report for an environment. The command defaults to the `health` report and the `prod` environment — a manual production check. |
| 85 | + |
| 86 | +```bash |
| 87 | +npx trigger.dev@latest report health --env prod --period 24h |
| 88 | +``` |
| 89 | + |
| 90 | +| Flag | Default | Description | |
| 91 | +| --- | --- | --- | |
| 92 | +| `[key]` | `health` | The report to render (positional argument). | |
| 93 | +| `-e, --env` | `prod` | The environment: `dev`, `staging`, `prod`, or `preview`. | |
| 94 | +| `-b, --branch` | — | The preview branch. Required when `--env preview`. | |
| 95 | +| `--period` | `1h` | The live window: `30m`, `1h`, `24h`, `7d`. Minutes to weeks, max 90 days. | |
| 96 | +| `-p, --project-ref` | from config | The project ref (`proj_…`). Required if there is no `trigger.config.ts`. | |
| 97 | +| `-c, --config` | — | Path to the config file. | |
| 98 | + |
| 99 | +The command prints only the report — no banner — so it pipes cleanly. Output is ANSI-colored in a real terminal and plain markdown when piped: |
| 100 | + |
| 101 | +```bash |
| 102 | +trigger report health > health.md # markdown, no escape codes |
| 103 | +``` |
| 104 | + |
| 105 | +Color follows the [supports-color](https://github.com/chalk/supports-color) convention: `NO_COLOR` (any value) or `FORCE_COLOR=0` disables color outright; `FORCE_COLOR` set to anything else force-enables it. Both win over TTY detection — which matters for agents spawned on a PTY, where `isTTY` is `true` but escape codes would be garbled. |
| 106 | + |
| 107 | +### MCP tool: `get_report` |
| 108 | + |
| 109 | +Fetch the report from an AI coding tool through the [Trigger.dev MCP server](/mcp-introduction). The tool returns plain markdown by default, or ANSI when `color` is set (for hosts that display escapes in tool output). It is read-only. |
| 110 | + |
| 111 | +| Parameter | Default | Description | |
| 112 | +| --- | --- | --- | |
| 113 | +| `key` | — | The report to render. Currently only `health`. | |
| 114 | +| `environment` | `dev` | The environment. The MCP server is dev-centric, so an unspecified environment reports on `dev` — pass `environment` explicitly to report on production. | |
| 115 | +| `period` | `1h` | Time window shorthand, e.g. `1h`, `24h`, `7d`. | |
| 116 | +| `color` | `false` | Return ANSI-colored text instead of markdown. | |
| 117 | +| `projectRef` | auto-detected | The project ref. Detected from `trigger.config.ts` if present. | |
| 118 | +| `branch` | — | The preview branch, for preview or branchable dev environments. | |
| 119 | + |
| 120 | +### MCP prompt: `/report` |
| 121 | + |
| 122 | +The MCP server also registers a `report` prompt, which hosts that support MCP prompts surface as a slash command (Claude Code renders it as `/mcp__trigger__report`). Running `/report health` calls `get_report` for you and shows the result verbatim in a fenced code block, preserving the monospace alignment and sparklines. |
| 123 | + |
| 124 | +### HTTP API: `GET /api/v1/reports/:key` |
| 125 | + |
| 126 | +The endpoint behind every surface. It accepts a `period` and a `format`, and authenticates with a token scoped to read the report's query tables (`read:query`). |
| 127 | + |
| 128 | +| Query param | Default | Description | |
| 129 | +| --- | --- | --- | |
| 130 | +| `period` | `1h` | The live window, same grammar as the CLI. | |
| 131 | +| `format` | `markdown` | `markdown`, `ansi`, or `json`. | |
| 132 | + |
| 133 | +`format=markdown` and `format=ansi` return the rendered text. `format=json` returns the `ReportViewModel` — the semantic payload behind the render, where verdicts are codes rather than prose, for building your own surface on top of the report. |
| 134 | + |
| 135 | +```bash |
| 136 | +curl "https://api.trigger.dev/api/v1/reports/health?period=24h&format=json" \ |
| 137 | + -H "Authorization: Bearer $TRIGGER_ACCESS_TOKEN" |
| 138 | +``` |
| 139 | + |
| 140 | +An unknown report key returns `404` with the list of available keys. |
| 141 | + |
| 142 | +## Next steps |
| 143 | + |
| 144 | +<CardGroup cols={2}> |
| 145 | + <Card title="MCP server" icon="plug" href="/mcp-introduction"> |
| 146 | + Connect your AI coding tool to Trigger.dev. |
| 147 | + </Card> |
| 148 | + <Card title="MCP tools" icon="wrench" href="/mcp-tools"> |
| 149 | + Every tool the MCP server exposes, including `get_report`. |
| 150 | + </Card> |
| 151 | + <Card title="Concurrency & queues" icon="layer-group" href="/queue-concurrency"> |
| 152 | + Configure the concurrency limits the Flow verdict checks against. |
| 153 | + </Card> |
| 154 | + <Card title="Query your data" icon="magnifying-glass" href="/observability/query"> |
| 155 | + Run TRQL queries against the same telemetry the report reads. |
| 156 | + </Card> |
| 157 | +</CardGroup> |
0 commit comments