Skip to content

Create and Manage Annotations

Use annotations in Custom Dashboards to provide rich contextual information about single points in time.

Overview

Annotations in Custom Dashboards allow you to spotlight crucial events by adding an agnostic query that runs parallel to the query underlying your widget. Represented as vertical lines cutting across your line and bar charts, you may hover over an annotation to uncover event details and tags, adding an extra layer of context. The text message field even lets you embed dynamic label values for comprehensive insights. When two or more events occur simultaneously on an annotation, toggle between events on the same timestamp.

Utilize annotations strategically — mark the deployment time of a new software release for instant correlation with system changes, or, during an incident response, create annotations to pinpoint critical events revealed by logs, metrics, or spans. This creates a precise chronological record of investigative steps for swift and effective resolution.

When an annotation is created, it applies to all time-based widgets in your dashboard.

Easily edit or delete the annotation at any time.

Create an annotation

To add an annotation:

1

Click annotate-icon Manage Annotations.

2

In the ANNOTATIONS panel that opens, click + Annotation.

3

Enter the annotation details.

Annotation name

Select a name that will be easily recognizable.

Data source

Annotations can be extracted from any of the following data sources:

  • Logs
  • Spans
  • Metrics. When you select metrics, you may choose a predefined metric in the Metric to Annotation field or use a free-text PromQL query in the Query field.

Annotations can be extracted from metrics. When you select metrics, you may choose a predefined metric in the Metric to Annotation field or use a free-text PromQL query in the Query field.

Query

If you haven’t chosen to use a DataPrime syntax query, logs and traces are queried with Lucene and metrics with PromQL. An annotation will be automatically generated on your widgets when query results are met.

Annotation type

Select a singular event (Single) or a time range (Range) with a start and end time.

Note

Annotation type configuration is available for log-based widgets and span-based widgets only. It doesn't appear for metrics-based widgets.

  • Single. From the drop-down menu, choose the field that represents the start timestamp.
  • Range. From the drop-down menu, choose the fields that represent the start and end timestamps. Alternatively, select the field representing the timestamp duration from the available options.

Settings

  • Text Message. Use free text with dynamic field placeholders enclosed in curly brackets, which become visible upon hovering over the annotation. For instance: 'Service {{service name}} experienced deployment at {{deployment.timestamp}}'. Replace the field placeholders accordingly.
  • Labels. Select label keys - such as pod name, node name, or environment - to be displayed in the annotation.
4

If you are satisfied with the annotation displayed in the Preview, click SAVE.

Hide annotations

When an annotation is created, it applies to all time-based widgets in your dashboard. Toggle your annotation on and off for all widgets in the dashboard toolbar.

Toggle an annotation on and off in a specific widget by clicking on the annotation name in the widget legend.

Modify or delete annotations

1

Click on the annotation at the top of the dashboard.

2

In the Update Annotation modal that opens, modify the configuration settings, and click SAVE to update, or trash-icon remove to delete the annotation.

Additional resources

DocumentationCustom Dashboards