Graphite annotations

Annotations overlay event data on your dashboard graphs, helping you correlate events with metrics. You can use Graphite as a data source for annotations to display events such as deployments, incidents, or maintenance windows on your visualizations.

For general information about annotations in Grafana, refer to Annotate visualizations.

Common use cases

Graphite annotations help you explain changes in your metrics by marking when related events happened. Common use cases include:

Deployments: Mark each release so you can see whether a deployment changed latency, error rate, or throughput.
Incidents and outages: Mark when incidents start and resolve to correlate them with metric anomalies.
Maintenance windows: Mark planned maintenance so expected dips aren’t mistaken for problems.
Configuration changes: Mark when you change a feature flag or setting to track its effect over time.
Scaling events: Mark when you add or remove capacity to explain shifts in load or performance.

Each use case maps to one of the two query modes described in this page: a metric query when an existing metric already marks the event, or an events query when you record discrete events in Graphite.

Before you begin

Before creating Graphite annotations, ensure you have:

A configured Graphite data source in Grafana.
Metrics or events in Graphite that represent the events you want to annotate.
Read access to the Graphite instance.

Annotation query modes

Graphite supports two ways to query annotations. You configure both in the annotation query editor:

Mode	Field	Description
Metric query	Graphite Query	Runs a standard Graphite metric query. Each returned data point with a non-zero value becomes an annotation, and the series name becomes the title.
Events query	Graphite events tags	Queries the Graphite events API and filters by one or more event tags. Each matching event becomes an annotation.

Use the metric query mode when a metric is non-zero only at the moments you want to mark. A counter that stays above zero after the first event marks every interval, because Grafana creates an annotation for every non-zero point. Use the events query mode when you record discrete events in Graphite and tag them.

Create an annotation query

To add a Graphite annotation to your dashboard:

Navigate to the dashboard you want to update and click Edit.
Click the Add new element icon (blue plus sign).
Click Annotation query.
Enter a name for the annotation query.
If you don’t want to use the annotation query right away, clear the Enabled checkbox.
Select a color for the annotation event markers.
Select an option in the Show annotation controls in drop-down list to control where on the dashboard the annotation is displayed.
Select an option in the Show in drop-down list to control the panels in which the annotation is displayed.
Click Open query editor to open the Annotation Query dialog box.
Select the Graphite data source from the Data source drop-down list.
Configure one of the annotation query modes:
- In the Graphite Query field, enter a metric query, for example statsd.application.counters.*.count.
- In the Graphite events tags field, enter one or more event tags, for example deploy.
(Optional) Click Test annotation query to ensure that the query is working properly.
Click Close when you’ve completed the query setup.
Click Save.
(Optional) Enter a description of the changes you’ve made.
Click Save.
Click Exit edit.