Annotation Timelines

Grafana annotations explain why a chart changed. GrafanaSight can bring annotation context into Confluence so runbooks and incident reviews can show deployments, maintenance windows, and investigation notes alongside panel snapshots.

When To Use Annotation Macros

Use annotations when a page needs to answer:

• What changed before this alert fired?
• Was there a deployment during this metric spike?
• Did a maintenance window explain the outage pattern?
• Which operational events should the incident review mention?

Configuration Requirements

The Grafana service account token needs annotation read access. GrafanaSight reads annotations from Grafana and caches them for Confluence use.

Verified Supabase Example

The Supabase Production Health Runbook uses an annotation timeline scoped to the Supabase Project dashboard and the CPU Busy panel. During documentation verification, a realistic Grafana annotation was added for a capacity review so the macro could be documented in its working state.

The macro shows:

• GRAFANA ANNOTATIONS to identify the content source.
• 1 EVENTS to show the number of matching annotations.
• Change event timeline as the macro heading.
• Range for the selected annotation time window.
• Snapshot for when GrafanaSight fetched annotation data.
• Time, Event, and Scope columns for each annotation.
• Tags such as SUPABASE, CAPACITY-REVIEW, and INCIDENT-RUNBOOK.
• Refresh annotations to refresh the cached annotation summary.

Configuration Fields

Use the macro configuration dialog to control the annotation scope.

Fields and buttons:

• Optional Grafana dashboard or panel URL scopes annotations from a Grafana dashboard or panel URL.
• Dashboard scope lets the author select a cached dashboard.
• Time range switches between relative and absolute windows.
• Relative preset uses a named range such as Last 7d.
• Absolute range locks the annotation window to specific timestamps.
• Annotation tags (comma separated) filters events by tag.
• Max events limits how many rows the macro shows.
• Save configuration stores the scope and filters.
• Close exits without saving.

Empty States Are Useful

If no annotations match the selected time range or dashboard context, GrafanaSight should show that no annotations were found. That empty state is still useful because it tells responders that the runbook checked for change markers instead of forgetting them.

Good Page Pattern

Place annotation context near the panel snapshots it explains. For example, a database runbook can show CPU, memory, and disk panels, then an annotation section for deployments and maintenance events from the same time window.