---
title: "Grafana Annotations"
---

Correlate incidents with **deployments and config changes** from any source. OpenSRE reads
[Grafana annotations](https://grafana.com/docs/grafana/latest/dashboards/build-dashboards/annotate-visualizations/) —
the standard, source-agnostic "what changed and when" marker — so the agent can answer
_"did a deploy or config change precede this alert?"_ even when the change did **not** come
from a GitHub push (ArgoCD/Flux syncs, `helm upgrade`, Jenkins/CircleCI jobs, Terraform
applies, manual hotfixes).

This complements the GitHub deploy timeline, which only sees GitHub-originated deploys.

## Requirements

No new setup or credentials — it reuses your existing **Grafana** integration. If Grafana is
connected (see [Grafana](/grafana)), the annotations tool is available automatically during
investigations.

## Parameters

| Parameter            | Description                                                                 |
| -------------------- | --------------------------------------------------------------------------- |
| `from`               | ISO 8601 window start (e.g. `2026-05-30T14:00:00Z`). Overrides the default. |
| `to`                 | ISO 8601 window end. Overrides the default.                                 |
| `tags`               | Optional list of annotation tags to filter by (e.g. `["deployment"]`).      |
| `time_range_minutes` | Window size when `from`/`to` are omitted (default `60`, ending now).        |
| `limit`              | Maximum annotations to return (default `100`).                              |

## Example

```text
query_grafana_annotations(from="2026-05-30T14:00:00Z", to="2026-05-30T15:00:00Z", tags=["deployment"])
```

```json
{
  "source": "grafana_annotations",
  "total": 1,
  "annotations": [
    {
      "time": "2026-05-30T14:41:09Z",
      "time_end": null,
      "text": "deploy checkout-api v2.8.1",
      "tags": ["deployment", "checkout-api"],
      "dashboard_uid": null
    }
  ]
}
```

Each annotation also carries `time_end` (set only for region annotations) and `dashboard_uid`
(set only when the annotation is attached to a dashboard); both are `null` otherwise.

The agent uses results like this to flag a likely change-induced regression and tie the
suspected root cause to a specific deploy.

## Emitting annotations

Make your deploys visible by writing a Grafana annotation when you ship. Most CD tools can
post to Grafana's annotations API, for example:

```bash
curl -s -X POST "$GRAFANA_URL/api/annotations" \
  -H "Authorization: Bearer $GRAFANA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"time": 1717079669000, "text": "deploy checkout-api v2.8.1", "tags": ["deployment", "checkout-api"]}'
```

Tagging deploy annotations consistently (e.g. `deployment`) lets the agent filter precisely
during an investigation.