Working with Annotations

1. Creating Manual Annotations

Field	Description	Example
dashboardId	Dashboard ID where the annotation will be created	`12345`
panelId	Panel ID to which the annotation is linked (optional)	`67890`
time	Timestamp in milliseconds (ISO 8601 format)	`1678886400000`
timeEnd	End timestamp for time range annotations (optional)	`1678890000000`
text	Annotation text content	`Deployment completed`
tags	Array of tags to categorize the annotation	`["deployment", "prod"]`

Example: Creating a Manual Annotation via API

const annotation = {
  dashboardId: 12345,
  panelId: 67890,
  time: 1678886400000,
  text: "Deployment completed",
  tags: ["deployment", "prod"]
};

fetch("/api/annotations", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(annotation)
});

2. Creating Query-Based Annotations

Property	Value	Description
dashboardId	`12345`	ID of the dashboard where annotation will be created
name	`"Deployment Events"`	Name of the annotation
datasourceUid	`"grafana-annotations-datasource"`	UID of the data source used for querying annotations
enable	`true`	Enables or disables the annotation
query	`{ "target": "deployments", "expr": "count(deployments) by (environment)" }`	Query expression to fetch annotation data

Example: Creating a Query-Based Annotation via API

const annotation = {
  dashboardId: 12345,
  name: "Deployment Events",
  datasourceUid: "grafana-annotations-datasource",
  enable: true,
  query: {
    target: "deployments",
    expr: "count(deployments) by (environment)"
  }
};

fetch('/api/annotations', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer <your-api-token>'
  },
  body: JSON.stringify(annotation)
});

3. Configuring Annotation Queries

Property	Description	Values	Notes
datasource	Specifies the data source to query for annotations	`__dashboard__`, `__team__`, or a data source name	Use `__dashboard__` to use dashboard variables, `__team__` for team-level annotations
enable	Enables or disables the annotation query	`true`, `false`	Default is `true`
name	Unique name for the annotation query	String	Used in the UI to identify the query
iconColor	Color of the annotation icon in the dashboard	Hex color code or `auto`	Defaults to `#808080` if not specified
hide	Hides the annotation from display in the dashboard	`true`, `false`	Default is `false`

Example: Annotation Query Configuration

{
  "datasource": "__dashboard__",
  "enable": true,
  "name": "Deployment Events",
  "iconColor": "#FF5733",
  "hide": false
}

Note: Annotation queries can be configured to use variables from the dashboard, allowing dynamic filtering and display of annotations based on user input or dashboard context.

4. Setting Annotation Display

Property	Description	Values	Notes
annotations	Defines the list of annotations to display	`[]`	Each annotation is an object with properties like `name`, `datasource`, and `enable`
enable	Enables or disables the annotation	`true` \| `false`	Default: `true`
datasource	Specifies the data source for annotations	`string`	Can be a data source UID or `-- Grafana --` for internal annotations
name	Unique name for the annotation	`string`	Used in the UI to identify the annotation
iconColor	Color of the annotation icon	`string`	Hex color code or named color (e.g., `#ff0000`)
fillOpacity	Opacity of the annotation fill	`number`	Value between 0 and 100. Default: `20`
lineColor	Color of the annotation line	`string`	Hex color code or named color (e.g., `#00ff00`)
showLine	Whether to show a line for the annotation	`true` \| `false`	Default: `true`

Example: Annotation Configuration

{
  "annotations": [
    {
      "name": "Deployment Events",
      "datasource": "-- Grafana --",
      "enable": true,
      "iconColor": "#ff0000",
      "fillOpacity": 30,
      "lineColor": "#ff0000",
      "showLine": true
    }
  ]
}

Note: Annotation settings can be configured at the dashboard or folder level. Changes to annotation display properties will update in real-time on dashboards where they are enabled.

5. Using Built-in Annotations

Annotation Type	Description	Usage	Notes
Dashboard Annotations	Annotations tied to a specific dashboard.	Configured via the dashboard's annotation settings.	Can be managed and edited directly from the dashboard view.
Template Variables	Annotations that use template variables for dynamic content.	Defined in the dashboard's template variables section.	Allows for filtering and dynamic annotation content based on user input or dashboard context.
Alert Annotations	Annotations created automatically when an alert is triggered.	Generated from the Alerting system and displayed on dashboards.	Useful for tracking alert history and impact over time.
Internal Events	Annotations generated by Grafana's internal systems (e.g., dashboard changes).	Automatically created and managed by Grafana.	Helps in auditing dashboard usage and system events.

Example: Dashboard Annotation Configuration

{
  "name": "Deployment Events",
  "datasource": "-- Grafana --",
  "enable": true,
  "iconColor": "rgba(255, 96, 96, 1)",
  "query": "select 'Deployment', timestamp from events where event_type = 'deployment'",
  "tags": ["deployment", "release"],
  "titleFormat": "Deployment: {{event.tags}}"
}

Note: Dashboard annotations are useful for marking significant events like deployments, configuration changes, or system outages directly on graphs.

6. Filtering Annotations by Tags

Tag	Description	Usage
tag	Filter annotations by a specific tag	`tag=error`
tag=*	Filter annotations by multiple tags (OR logic)	`tag=error,warning`
tag!=*	Exclude annotations with specific tags (NOT logic)	`tag!=maintenance`

Example: Filtering Annotations by Tags

GET /api/annotations?tag=error,warning&tag!=maintenance

Note: Tags are case-sensitive and must match exactly.

Warning: Using tag=* with many tags can impact performance.

7. Creating Region Annotations

Field	Description	Example
dashboardId	Dashboard ID where the annotation will be created	`12345`
panelId	Panel ID to associate the annotation with (optional)	`67890`
time	Start time of the annotation in milliseconds since epoch	`1634567890000`
timeEnd	End time of the annotation in milliseconds since epoch	`1634571490000`
text	Text content of the annotation	`"Deployment completed"`
tags	Array of tags to categorize the annotation	`["deployment", "prod"]`

Example: Creating a Region Annotation via API

const annotation = {
  dashboardId: 12345,
  panelId: 67890,
  time: 1634567890000,
  timeEnd: 1634571490000,
  text: "Deployment completed",
  tags: ["deployment", "prod"]
};

fetch('/api/annotations', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer <your-api-token>'
  },
  body: JSON.stringify(annotation)
});

Note: Region annotations span a time range, unlike point annotations which occur at a specific moment.

8. Configuring Annotation Colors

Property	Values	Description
color	`#FF0000`, `red`, `blue`	Background color of the annotation
icon	`fa fa-star`, `fa fa-info-circle`	Font Awesome icon to display with annotation
fillOpacity	`0.2`, `0.7`	Opacity of the annotation fill (0 to 1)

Example: Annotation Color Configuration

{
  "color": "#00FF00",
  "icon": "fa fa-check-circle",
  "fillOpacity": 0.3
}

9. Setting Annotation Limit

Property	Value	Description
annotations.limit	`1000`	Maximum number of annotations to display on a panel
annotations.maxCount	`5000`	Maximum number of annotations to fetch from the data source

Example: Configuring Annotation Limits

{
  "annotations": {
    "limit": 1000,
    "maxCount": 5000
  }
}

Note: Setting annotations.limit to a low value can improve performance for panels with many annotations.

10. Managing Annotations via API

Endpoint	Method	Description
/api/annotations	POST	Create a new annotation
/api/annotations	GET	Retrieve annotations
/api/annotations/{id}	PUT	Update an existing annotation
/api/annotations/{id}	DELETE	Delete an annotation

Example: Create Annotation

{
  "time": 1678886400000,
  "timeEnd": 1678886500000,
  "text": "Deployed new feature",
  "tags": [
    "deployment",
    "feature"
  ],
  "dashboardId": 123,
  "panelId": 456
}

Example: Retrieve Annotations

{
  "from": 1678886400000,
  "to": 1678886500000,
  "limit": 100,
  "dashboardId": 123
}

Example: Update Annotation

{
  "id": "12345",
  "text": "Deployed new feature with bug fixes",
  "tags": [
    "deployment",
    "feature",
    "bugfix"
  ]
}

Example: Delete Annotation

curl -X DELETE \
  "http://localhost:3000/api/annotations/12345" \
  -H "Authorization: Bearer <token>"