---
title: "Loki annotations | Grafana documentation"
description: "Use annotations with the Loki data source in Grafana"
---

> For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt).

# Loki annotations

[Annotations](/docs/grafana/latest/dashboards/build-dashboards/annotate-visualizations/) 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](/docs/grafana/latest/datasources/loki/configure/).
- A [LogQL](/docs/loki/latest/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:

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:

Expand table

| 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:

Expand table

| 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:

logql ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```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](/docs/grafana/latest/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.

## Related resources

- [Annotate visualizations](/docs/grafana/latest/dashboards/build-dashboards/annotate-visualizations/)
- [Loki query editor](/docs/grafana/latest/datasources/loki/query-editor/)
- [Configure the Loki data source](/docs/grafana/latest/datasources/loki/configure/)