Google Cloud Monitoring annotations

Annotations overlay rich event information on top of graphs. You can use annotations to mark important events, deployments, or incidents on your dashboards.

Before you begin

Before you configure annotations, ensure you have the following:

• A configured Google Cloud Monitoring data source.
• A dashboard where you want to add annotations.

Annotation limitations

Keep the following limitations in mind when using annotations:

• Performance: Rendering annotations is expensive. Limit the number of rows returned to maintain dashboard performance.
• Native events: There's no support for displaying Google Cloud Monitoring's native annotations and events. However, annotations work well with custom metrics in Google Cloud Monitoring.

Add an annotation query

To add an annotation query to a dashboard:

1. Open the dashboard where you want to add annotations.
2. Click Dashboard settings (gear icon).
3. Select Annotations in the left menu.
4. Click Add annotation query.
5. Select your Google Cloud Monitoring data source.
6. Configure the annotation query using the query editor.

Configure the annotation query

With the query editor for annotations, you can select a metric and filters to define which data points create annotations.

The Title and Text fields support templating and can use data returned from the query.

For example, the Title field could have the following text:

{{metric.type}} has value: {{metric.value}}

Example result: monitoring.googleapis.com/uptime_check/http_status has this value: 502

Annotation patterns

Use the following patterns in the Title and Text fields to display metric data in your annotations:

Pattern format	Description	Example	Result
{{metric.value}}	Value of the metric/point.	{{metric.value}}	555
{{metric.type}}	Returns the full Metric Type.	{{metric.type}}	compute.googleapis.com/instance/cpu/utilization
{{metric.name}}	Returns the metric name part.	{{metric.name}}	instance/cpu/utilization
{{metric.service}}	Returns the service part.	{{metric.service}}	compute
{{metric.label.xxx}}	Returns the metric label value.	{{metric.label.instance_name}}	grafana-1-prod
{{resource.label.xxx}}	Returns the resource label value.	{{resource.label.zone}}	us-east1-b

Example: Annotate uptime check failures

To create annotations for uptime check failures:

1. Add an annotation query using the Google Cloud Monitoring data source.
2. Select the monitoring.googleapis.com/uptime_check/check_passed metric.
3. Add a filter for check_passed = false.
4. Set the Title to: Uptime check failed: {{metric.label.check_id}}
5. Set the Text to: Region: {{resource.label.zone}}

This creates an annotation marker on your graph each time an uptime check fails.