Documentation Plugins DynamoDB Annotations

DynamoDB annotations

The DynamoDB data source supports annotations, which let you overlay event markers on time-series panels. Annotations help you correlate events stored in DynamoDB with changes in your metrics. For general information about annotations, refer to Annotate visualizations.

Before you begin

• Configure the DynamoDB data source.
• Understand Grafana annotations.

Add an annotation query

To add a DynamoDB annotation query to a dashboard:

1. Open the dashboard where you want to add annotations.
2. Click Dashboard settings (gear icon).
3. Select Annotations in the left-side menu.
4. Click Add annotation query.
5. Select the DynamoDB data source.
6. Enter a PartiQL query that returns the required fields.
7. Click Save dashboard.

Query format

Annotation queries must return specific fields so Grafana can render the event markers. The DynamoDB data source uses the standard Grafana annotation format.

The following table describes the supported fields:

Annotation query examples

The following examples demonstrate common annotation patterns with DynamoDB.

Mark deployments on a dashboard

This query returns deployment events with a title, description, and environment tag:

SQL Copy

SELECT deploy_time AS time, version AS title, description AS text, environment AS tags
FROM "deployments"
WHERE customerId = 'myapp'
ORDER BY deploy_time

Each deployment appears as a vertical line on time-series panels. Hovering over it shows the version as a heading and the description as body text.

Track incidents

This query marks incident events on your dashboard:

SQL Copy

SELECT event_time AS time, severity AS title, event_message AS text
FROM "events"
WHERE event_type = 'incident' AND customerId = 'myapp'
ORDER BY event_time

Show maintenance windows with duration

Use timeEnd to create range annotations that highlight a time span rather than a single point:

SQL Copy

SELECT start_time AS time, end_time AS timeEnd, window_name AS title, description AS text
FROM "maintenance-windows"
WHERE systemId = 'prod-cluster'
ORDER BY start_time

Range annotations appear as shaded regions on time-series panels.

Filter by time range

Since the DynamoDB data source doesn’t support time-range macros, include explicit time boundaries in your query to avoid scanning the entire table:

SQL Copy

SELECT event_time AS time, message AS text, category AS tags
FROM "application-events"
WHERE event_time BETWEEN '2024-01-01T00:00:00Z' AND '2024-12-31T23:59:59Z'
  AND appId = 'frontend'
ORDER BY event_time

You can use template variables for dynamic filtering:

SQL Copy

SELECT event_time AS time, message AS text
FROM "application-events"
WHERE appId = '$app'
ORDER BY event_time

Simple time-only annotations

If you only need markers without text, a single time column is sufficient:

SQL Copy

SELECT restart_time AS time
FROM "service-restarts"
WHERE serviceId = 'api-gateway'
ORDER BY restart_time

Next steps

• Learn how to write queries in the DynamoDB query editor.
• Set up alerting based on DynamoDB data.
• Refer to Annotate visualizations for full annotation configuration options.