Annotations & Correlations
Relevant source files
The following files were used as context for generating this wiki page:
Annotations and correlations within Grafana serve as critical mechanisms for contextualizing data and linking disparate system events. Annotations allow users to overlay rich event metadata—such as deployments, outages, or specific system changes—directly onto time-series graphs. This provides immediate visual correlation between system behavior and external events.
Correlations further extend this by linking specific data points or plugin insights (e.g., Zabbix triggers or Redshift queries) to broader system monitoring contexts. These systems are integrated into the core dashboarding experience, enabling features like automated event tagging and cross-datasource navigation.
Sources: public/app/features/alerting/unified/AGENTS.md, public/app/features/plugins/admin/mocks/catalogPlugin.mock.ts
Annotation Architecture and Data Flow
Annotations can be created manually through the UI or automatically via queries. When using automated annotations, Grafana executes a query against a data source and maps the returned columns to internal annotation fields.
Automated Annotation Mapping
For data sources such as SQL-based ones (e.g., Redshift), specific columns must be identified to define the annotation's temporal and descriptive properties.
| Field Name | Description | Required |
|---|---|---|
time | The start date/time of the event (Native SQL type or epoch). | Yes |
timeend | The end date/time for duration-based events. | No |
text | The descriptive content or message of the event. | Yes |
tags | Comma-separated string used for event categorization. | No |
Sources: public/app/features/plugins/admin/mocks/catalogPlugin.mock.ts, devenv/dev-dashboards/panel-table/table_markdown.json
Visual Representation Flow
The following diagram illustrates how raw data from a source is transformed into a visual annotation on a dashboard panel.
This flow ensures that events like high humidity alerts or Zabbix triggers are accurately placed on the timeline.
Sources: public/app/features/plugins/admin/mocks/catalogPlugin.mock.ts, devenv/dev-dashboards/panel-table/table_markdown.json
Integration with Alerting and Plugins
Annotations are deeply coupled with the alerting system and external plugins. For instance, the Zabbix plugin utilizes annotations to show events on graphs, providing a bridge between Zabbix triggers and Grafana's visualization layer.
Unified Alerting Annotations
In the context of Unified Alerting, annotations are used to store metadata about alert rules. This metadata is often consumed by notification templates to provide context in alert messages.
- Mocking for Tests: Development teams use factories like
mockPromAlert()andmockAlertmanagerAlert()to simulate alert-driven annotations during testing. - Permissions: Access to viewing or creating annotations is governed by RBAC actions such as
AlertingRuleRead.
Sources: public/app/features/alerting/unified/AGENTS.md:121-135, public/app/features/plugins/admin/mocks/catalogPlugin.mock.ts
Issue Triage and Correlation
The project uses automated systems to correlate incoming GitHub issues with specific functional areas or data sources. This acts as a meta-correlation layer for project maintenance.
This process uses commands.json and GitHub Actions to ensure that bugs reported in areas like "Alerting" or "Dashboard" are immediately associated with the correct sub-teams.
Sources: contribute/ISSUE_TRIAGE.md:1-25
Implementation Standards
When developing features related to annotations or correlations, developers must follow specific frontend guidelines:
- Redux for State: Do not contain backend calls directly from components; use actions and Redux for state management related to annotation fetching.
- Formatting: Pull request titles must include the area (e.g.,
Dashboard:,Alerting:) to ensure proper correlation in the generated changelogs. - Testing: Use
userEventandmsw(Mock Service Worker) to test the interaction between annotation overlays and the underlying data services.
Sources: contribute/create-pull-request.md:44-55, public/app/features/alerting/unified/AGENTS.md:215-230
Conclusion
Annotations and correlations are fundamental to the Grafana experience, transforming static metrics into actionable narratives. By mapping data source columns to visual events and utilizing automated triaging for project management, Grafana maintains a consistent link between raw data, system alerts, and developer workflows.