Loki annotations

Annotations overlay rich event information on top of graphs. With the Loki data source, annotations are built from log queries: each log line that a LogQL query returns within the dashboard time range becomes an annotation, so you can correlate log events with the rest of your dashboard data.

Before you begin

Before you create Loki annotations, ensure you have:

A configured Loki data source.
A LogQL log query that returns the events you want to annotate.

How Loki annotations work

Unlike data sources that build annotations from a separate query language, Loki annotations use the same LogQL log queries you use elsewhere. Grafana runs your log query for the dashboard time range and turns each returned log line into an annotation. By default, Grafana uses the log content as the annotation text and the log stream labels as tags, so you don’t need to create any additional mapping.

You can only use log queries as a source for annotations. Metric queries aren’t supported.

Create an annotation query

To add a Loki annotation to a dashboard:

Open the dashboard where you want to add annotations.
Click Edit, then click Settings in the top navigation.
Select the Annotations tab.
Click Add annotation query.
Enter a Name for the annotation, for example, Deploy events.
Select your Loki data source.
Enter a LogQL log query and configure the optional fields described in the following table.
Click Save dashboard.

The annotation query editor provides the following fields:

Field	Description
Query	The LogQL log query that selects the log lines to annotate.
Title	Optional. A literal name or a template for the annotation title. Reference labels with `{{label}}`, for example `{{level}}`.
Tags	Optional. A comma-separated list of label keys to use as annotation tags, for example `app,level`. When empty, Grafana uses the log stream labels as tags.
Text	Optional. A literal string or a template for the annotation text. Reference labels with `{{label}}`. When empty, Grafana uses the log line content as the text.

Template fields resolve against the labels on each returned log line, including parsed fields. To reference a value that isn’t an indexed label, add a parser such as logfmt or json to your query so the field is available.

Example

To annotate deployment events, configure the annotation query with the following values:

Field	Value
Query	`{app="deploy-bot"} \|= "deployed"`
Title	`{{app}} deployed`
Tags	`app,env`
Text	`{{message}}`

Each matching log line becomes an annotation titled with the deploying app, tagged with the app and env labels, and described with the parsed message field. Because the Text template references a parsed field, the query needs a parser, for example:

{app="deploy-bot"} |= `deployed` | logfmt

Troubleshoot annotations

If annotations don’t appear as expected, try the following solutions.

Annotations don’t appear

Verify the log query returns results in Explore for the same time range. Annotations come from returned log lines, so a query that returns no logs produces no annotations.
Confirm the query is a log query, not a metric query.
Widen the dashboard time range to include the log events you expect.