Annotations

Annotations are event markers overlaid on your time series — vertical lines (or shaded bands) that pin a moment in your operational history onto the chart. They answer the question every incident review eventually asks: what changed right before this? A deploy at 14:02 sitting next to a latency spike at 14:03 makes the cause self-evident.

Annotations are scoped to your organization and stored separately from your metrics, so they appear on any chart in the time range they cover — including incident charts.

The `name` and prefix convention

Each annotation has a free-form name. By convention names use a prefix/detail shape so they can be grouped and filtered:

infra/deploy
app/release-v2.3
incident/outage-db

The prefix (infra/, app/, incident/) is what filtering keys off — see below.

Point-in-time or duration

An annotation can mark a single instant (a deploy completing) or span a range (a maintenance window, the duration of an incident). Range annotations are drawn as a shaded band across the affected time, so you can see not just when something started but how long it lasted.

Creating annotations

Manually, from the dashboard UI — handy for one-off notes like a maintenance window or a known incident.
Automatically, via the public API — the intended path for CI/CD. Have your pipeline post an annotation when it deploys or releases, and every chart gains a deploy marker for free, with no manual step. See the Annotations API for the endpoint and payload.

Filtering on widgets

Dashboard widgets filter annotations by prefix: set a widget to show infra/ and it draws every annotation whose name starts with infra/. Prefixes are comma-separated to combine several (for example infra/,incident/), so a widget can show deploys and incidents together while ignoring everything else. This keeps a busy chart readable — you overlay only the events relevant to that view. See Dashboards for adding widgets and configuring their annotation filter.

Retention

Annotations are retained for 90 days.