Documentation Plugins Yugabyte Annotations

Yugabyte annotations

Annotations overlay event markers on time-series panels, which lets you correlate the events stored in YugabyteDB, such as deployments, incidents, or maintenance windows, with the metrics on your dashboards. For general information about annotations, refer to Annotate visualizations.

Before you begin

• Configure the Yugabyte data source.
• Store event data in YugabyteDB with a timestamp column that marks when each event occurred.

How annotations work

The Yugabyte data source uses the standard Grafana annotation query format. You write a SQL query that returns a row for each event, and Grafana maps the columns to annotation properties by name, matched case-insensitively.

Grafana recognizes the following columns:

An annotation only renders when the query produces both a time value and a text value. Use the $__timeFilter(column) macro so the annotation query only returns events within the dashboard time range.

Create an annotation query

To add an annotation query to a dashboard:

1. Open Dashboard settings > Annotations.
2. Click Add annotation query.
3. Enter a name for the annotation.
4. Select the Yugabyte data source.
5. Enter a SQL query that returns time and text values, plus any of the optional columns.
6. Click Save dashboard.

The annotations appear as markers on every time-series panel in the dashboard.

Examples

The following examples show annotation queries for common event types. Adapt the table and column names to match your schema.

Mark point-in-time events

This query marks deployment events on the timeline. Each row becomes a single marker at its time value, with the version shown as the title:

SQL Copy

SELECT
  deployed_at AS time,
  version AS title,
  description AS text,
  environment AS tags
FROM deployments
WHERE $__timeFilter(deployed_at)
ORDER BY time

Highlight a time range

Return a timeEnd column to draw a region annotation that spans a period, such as a maintenance window or an incident:

SQL Copy

SELECT
  started_at AS time,
  resolved_at AS timeEnd,
  description AS text,
  severity AS tags
FROM incidents
WHERE $__timeFilter(started_at)
ORDER BY time

If an event hasn’t ended, return NULL for timeEnd so Grafana renders it as a point-in-time marker instead of a region.

Combine multiple tags

The tags column accepts a comma-separated string, so you can build it from several columns to make annotations easier to filter:

SQL Copy

SELECT
  created_at AS time,
  summary AS text,
  concat(environment, ',', service) AS tags
FROM change_events
WHERE $__timeFilter(created_at)
ORDER BY time

Filter events with a template variable

You can reference template variables in an annotation query to scope events to the current dashboard selection:

SQL Copy

SELECT
  deployed_at AS time,
  description AS text
FROM deployments
WHERE environment = '$environment' AND $__timeFilter(deployed_at)
ORDER BY time

Next steps

• Learn how to write queries in the Yugabyte query editor.
• Use template variables to build dynamic dashboards.