This is documentation for the next version of Grafana documentation. For the latest stable release, go to the latest version.

Documentationbreadcrumb arrow Grafana documentationbreadcrumb arrow Data sourcesbreadcrumb arrow Lokibreadcrumb arrow Annotations
Grafana Cloud Enterprise Open source
Last reviewed: July 29, 2026

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:

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:

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

The annotation query editor provides the following fields:

FieldDescription
QueryThe LogQL log query that selects the log lines to annotate.
TitleOptional. A literal name or a template for the annotation title. Reference labels with {{label}}, for example {{level}}.
TagsOptional. 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.
TextOptional. 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:

FieldValue
Query{app="deploy-bot"} |= "deployed"
Title{{app}} deployed
Tagsapp,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:

logql 
{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.

Too many annotations appear

  • Add label filters or a line filter to your LogQL query to narrow the returned log lines.
  • Reduce the maximum number of lines the query returns.