> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onepatch.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Monitors and dashboards

> How the agent authors them, and how they go live.

Monitors and dashboards are the two things the agent builds for you. You do not write either by hand — you describe what you want in chat, and the agent writes the code. This page explains what each one is and how it goes live, so the agent's output is legible to you.

## Dashboards

A dashboard is a live view of your telemetry. You ask for one in plain language:

```text theme={null}
Build a dashboard showing request rate, p95 latency by route,
and error count over the last 24 hours.
```

The agent queries your telemetry to confirm the data exists, then writes a `Dashboard.tsx` file in your workspace. It appears in the side pane next to the chat and reloads as you refine it. Each panel refreshes on its own as new telemetry lands, so an open dashboard stays current without a manual refresh.

To change a dashboard, ask. The agent edits the existing file rather than starting over:

```text theme={null}
Drop the CPU panel and add a table of the 20 slowest requests this hour.
```

## Monitors

A monitor is a small program that watches a window of your telemetry on a schedule and returns one of three states: `healthy`, `firing`, or `unknown`. Because it's code, a monitor isn't limited to a single query: in one evaluation it can read traces, metrics, and logs, check your repo's latest commit, remember what it saw last tick, and decide.

Each monitor runs with a context that reaches well beyond a single metric: your full telemetry over ClickHouse (traces, metrics, and logs in one SQL surface), your connected GitHub repo (its latest commit, and how stale any file is), its own memory from prior ticks — and new sources as the need arises. That's enough to ask questions a threshold can't, like "did errors climb after the deploy that landed four minutes ago?"

You ask for one in plain language:

```text theme={null}
Alert me if the error rate over the last 5 minutes goes above 10 per minute.
```

The agent writes the monitor as a small program in your workspace. A monitor the agent produces for that request looks like this:

```ts theme={null}
import type { Monitor } from "@1patch/monitor-api";

const THRESHOLD_PER_MIN = 10;
const WINDOW_MIN = 5;

const monitor: Monitor = {
  id: "error-log-rate-5m",
  cron: "*/30 * * * * *", // evaluate every 30 seconds
  description: "Fires when the error-log rate over the last 5 minutes exceeds 10/min.",
  async evaluate(ctx) {
    const rows = await ctx.queryOtel(`
      SELECT count() AS n
      FROM otel.logs
      WHERE severity_text = 'ERROR'
        AND ts >= now() - INTERVAL ${WINDOW_MIN} MINUTE
    `);
    const rate = Number(rows[0]?.n ?? 0) / WINDOW_MIN;
    if (rate > THRESHOLD_PER_MIN) {
      return { state: "firing", reason: `error rate ${rate.toFixed(1)}/min > ${THRESHOLD_PER_MIN}/min` };
    }
    return { state: "healthy" };
  },
};

export default monitor;
```

You can read every monitor on the **Monitors** screen, with its schedule and latest state. Because monitors are plain code, a teammate can read exactly what each one checks and adjust a threshold without rebuilding it.

<Note>
  The three states are distinct on purpose. `healthy` means the thing being watched is fine. `firing` means the condition tripped, and it always carries a short, specific reason. `unknown` means the check could not run — a failed query or missing data — so a broken monitor is surfaced rather than silently passing.
</Note>

## How a monitor goes live

A monitor goes live when the agent **commits** it to your workspace — there is no separate publish step. Within about half a minute it appears on the **Monitors** screen and begins evaluating on its schedule. Edits work the same way: the agent commits the change and the new version takes over.

## Arming a monitor

A monitor can post to Slack whenever it fires. On its own, that is the extent of what it does: it records its state and, if you want, pings your channel. Arming it goes further. An armed monitor turns a firing into an incident and hands it to an agent, which investigates against live telemetry to find the cause. If the alert is a false alarm, the agent tunes the monitor itself. If it is real, it proposes a patch — a pull request that fixes the underlying issue. The agent runs the investigation and drafts the fix; your team reviews, iterates, and approves what ships.

You arm a monitor by asking:

```text theme={null}
Arm the error-rate monitor so it opens an incident and investigates when it fires.
```

[Incidents and Slack](/incidents-and-slack) covers what happens after a firing becomes an incident.