Documentation Plugins Looker data source Annotations

Looker annotations

Annotations overlay event data on your time series graphs, which makes it easier to correlate metrics with specific events such as deployments, releases, or incidents. The Looker data source supports annotations through the standard Looker query editor, so you can turn any LookML query or saved Look that returns a time field into annotation markers. For an overview of annotations, refer to Annotate visualizations.

Before you begin

Before you create an annotation query, ensure you have:

• Configured the Looker data source.
• A saved dashboard. You must save the dashboard before you can add an annotation query.
• A LookML query or saved Look that returns a time field, plus optional fields for the annotation title, description, and tags.

Annotation query format

An annotation query runs like any other Looker query and returns rows. Grafana maps the returned columns to annotation fields. Provide at least a time field so Grafana can place each annotation on the graph.

Because Looker field names are fully qualified, such as orders.created_date, use the field mapping controls in the annotation editor to map each returned column to the correct annotation field. The data source returns date and time dimensions as time-typed columns, so they map cleanly to the Time and Time end fields.

Use the $__timeFilter(<field>) macro in your annotation query so it returns only events within the visible dashboard time range. Without it, the query can return events outside the selected window.

Create an annotation query

To add a Looker annotation query to a dashboard:

1. Open your dashboard and click Edit, then open Options.
2. Select Annotations.
3. Click Add annotation query.
4. Enter a name for the annotation.
5. Click Open query editor.
6. Select your Looker data source in the Data source field.
7. Build the query using the Looker query editor. Choose the LookML query type to build a query against a model and explore, or the Run Look query type to use a saved Look.
8. Map the returned columns to the annotation Time, Title, Text, and Tags fields.
9. Click Save dashboard.

Annotation examples

The following examples show common annotation patterns for Looker.

Track events over time

Build a LookML query that returns an event timestamp with a label, and bound it to the dashboard time range with $__timeFilter(). In LookML JSON mode, the query body resembles the following:

JSON Copy

{
  "model": "ecommerce",
  "view": "orders",
  "fields": ["orders.created_time", "orders.status"],
  "filter_expression": "$__timeFilter(orders.created_time)",
  "sorts": ["orders.created_time"]
}

Map orders.created_time to the Time field and orders.status to the Text field in the annotation editor.

Build the query with the builder

You can build the same query with the visual builder instead of raw JSON, which is the default query mode:

1. Choose the LookML query type in Builder mode.
2. Select the Model and Explore Name, such as ecommerce and orders.
3. In Dimensions & Measures, add a timestamp dimension and a label field, such as orders.created_time and orders.status.
4. In the Filter Expression field, enter $__timeFilter(orders.created_time).
5. Map orders.created_time to the Time field and orders.status to the Text field.

Reuse a saved Look

If you already have a Look that returns events with a timestamp, select the Run Look query type and enter the Look ID. Then map the Look’s timestamp column to the Time field and a descriptive column to the Text field.

Next steps

• Refer to the Looker query editor for more on building LookML and Run Look queries.
• Refer to Annotate visualizations for more annotation options.