public/grafana
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

added a separate annotations doc

Browse Source
This commit is contained in:
Larissa Wandzura
2026-01-12 11:56:09 -06:00
parent 6f1d840222
commit c830948255
4 changed files with 183 additions and 67 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/sources/datasources/mysql/_index.md
+7 -4
View File
@@ -52,6 +52,11 @@ refs:
destination: /docs/grafana/<GRAFANA_VERSION>/datasources/mysql/alerting/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/datasources/mysql/alerting/
mysql-annotations:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/datasources/mysql/annotations/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/datasources/mysql/annotations/
transformations:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/query-transform-data/transform-data/
@@ -72,13 +77,11 @@ The following documents will help you get started with the MySQL data source in
- [Configure the MySQL data source](ref:configure-mysql-data-source)
- [MySQL query editor](ref:mysql-query-editor)
- [MySQL template variables](ref:mysql-template-variables)
- [MySQL annotations](ref:mysql-annotations)
- [MySQL alerting](ref:mysql-alerting)
- [Troubleshoot MySQL data source issues](ref:troubleshoot-mysql)
Once you have configured the data source you can also:
- Add [annotations](ref:annotate-visualizations)
- Add [transformations](ref:transformations)
Once you have configured the data source you can also add [transformations](ref:transformations) to your queries.
View a MySQL overview on Grafana Play:
docs/sources/datasources/mysql/annotations/index.md
+163
View File
@@ -0,0 +1,163 @@
---
description: Using annotations with MySQL in Grafana
keywords:
- grafana
- mysql
- annotations
- events
labels:
products:
- cloud
- enterprise
- oss
menuTitle: Annotations
title: MySQL annotations
weight: 400
refs:
annotate-visualizations:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/build-dashboards/annotate-visualizations/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/build-dashboards/annotate-visualizations/
---
# MySQL annotations
Annotations overlay event data on your dashboard graphs, helping you correlate events with metrics.
You can use MySQL as a data source for annotations to display events such as deployments, alerts, or other significant occurrences on your visualizations.
For general information about annotations, refer to [Annotate visualizations](ref:annotate-visualizations).
## Before you begin
Before creating MySQL annotations, ensure you have:
- A MySQL data source configured in Grafana.
- Tables containing event data with timestamp fields.
- Read access to the tables containing your events.
## Create an annotation query
To add a MySQL annotation to your dashboard:
1. Navigate to your dashboard and click **Dashboard settings** (gear icon).
1. Select **Annotations** in the left menu.
1. Click **Add annotation query**.
1. Enter a **Name** for the annotation.
1. Select your **MySQL** data source from the **Data source** drop-down.
1. Write a SQL query that returns the required columns.
1. Click **Save dashboard**.
## Query columns
Your annotation query must return a `time` column and can optionally include `timeend`, `text`, and `tags` columns.
| Column | Required | Description |
| --------- | -------- | -------------------------------------------------------------------------------------------------------- |
| `time` | Yes | The timestamp for the annotation. Can be a SQL datetime or UNIX epoch value. |
| `timeend` | No | The end timestamp for range annotations. Creates a shaded region instead of a vertical line. |
| `text` | No | The annotation description displayed when you hover over the annotation. |
| `tags` | No | Tags for the annotation as a comma-separated string. Helps categorize and filter annotations. |
## Example queries
The following examples show common annotation query patterns.
### Basic annotation with epoch time
Display events using UNIX epoch timestamps:
```sql
SELECT
epoch_time as time,
description as text,
CONCAT(tag1, ',', tag2) as tags
FROM events
WHERE $__unixEpochFilter(epoch_time)
```
### Annotation with a single tag
Display events with a single tag value:
```sql
SELECT
epoch_time as time,
message as text,
category as tags
FROM event_log
WHERE $__unixEpochFilter(epoch_time)
```
### Range annotation with start and end time
Display events with duration as shaded regions:
```sql
SELECT
start_time as time,
end_time as timeend,
description as text,
CONCAT(type, ',', severity) as tags
FROM incidents
WHERE $__unixEpochFilter(start_time)
```
### Annotation with native SQL datetime
Display events using native MySQL datetime columns:
```sql
SELECT
event_date as time,
message as text,
CONCAT(category, ',', priority) as tags
FROM system_events
WHERE $__timeFilter(event_date)
```
### Deployment annotations
Display deployment events:
```sql
SELECT
deployed_at as time,
CONCAT('Deployed ', version, ' to ', environment) as text,
environment as tags
FROM deployments
WHERE $__timeFilter(deployed_at)
```
### Maintenance window annotations
Display maintenance windows as range annotations:
```sql
SELECT
start_time as time,
end_time as timeend,
CONCAT('Maintenance: ', description) as text,
'maintenance' as tags
FROM maintenance_windows
WHERE $__timeFilter(start_time)
```
## Macros
Use these macros in your annotation queries to filter by the dashboard time range:
| Macro | Description |
| ------------------------------ | -------------------------------------------------------------------------------- |
| `$__timeFilter(column)` | Filters by time range using a native SQL datetime column. |
| `$__unixEpochFilter(column)` | Filters by time range using a column with UNIX epoch timestamps. |
## Best practices
Follow these best practices when creating MySQL annotations:
- **Use time filters:** Always include `$__timeFilter()` or `$__unixEpochFilter()` to limit results to the dashboard time range.
- **Keep queries efficient:** Add indexes on time columns and filter columns to improve query performance.
- **Use meaningful text:** Include descriptive information in the `text` column to make annotations useful.
- **Organize with tags:** Use consistent tag values to categorize annotations and enable filtering.
- **Test queries first:** Verify your query returns expected results in Explore before adding it as an annotation.
docs/sources/datasources/mysql/configure/_index.md
+6 -1
View File
@@ -56,6 +56,11 @@ refs:
destination: /docs/grafana/<GRAFANA_VERSION>/datasources/mysql/alerting/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/datasources/mysql/alerting/
mysql-annotations:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/datasources/mysql/annotations/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/datasources/mysql/annotations/
mysql-troubleshoot:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/datasources/mysql/troubleshooting/
@@ -296,6 +301,6 @@ After configuring your MySQL data source, you can:
- [Write queries](ref:mysql-query-editor) using the query editor to explore and visualize your data.
- [Use template variables](ref:mysql-template-variables) to create dynamic, reusable dashboards.
- [Add annotations](ref:annotate-visualizations) to overlay MySQL events on your graphs.
- [Add annotations](ref:mysql-annotations) to overlay MySQL events on your graphs.
- [Set up alerting](ref:mysql-alerting) to create alert rules based on your MySQL data.
- [Troubleshoot issues](ref:mysql-troubleshoot) if you encounter problems with your data source.
docs/sources/datasources/mysql/query-editor/_index.md
+7 -62
View File
@@ -71,6 +71,11 @@ refs:
destination: /docs/grafana/<GRAFANA_VERSION>/datasources/mysql/alerting/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/datasources/mysql/alerting/
mysql-annotations:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/datasources/mysql/annotations/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/datasources/mysql/annotations/
---
# MySQL query editor
@@ -323,69 +328,9 @@ For detailed information on using template variables with MySQL, refer to [MySQL
## Annotations
[Annotations](ref:annotate-visualizations) allow you to overlay rich event information on top of graphs. You add annotation queries via the **Dashboard settings > Annotations view**.
Annotations allow you to overlay event information on your graphs, helping you correlate events with metrics. You can write SQL queries that return event data to display as annotations on your dashboards.
**Example query using a `time` column with epoch values:**
```sql
SELECT
epoch_time as time,
metric1 as text,
CONCAT(tag1, ',', tag2) as tags
FROM
public.test_data
WHERE
$__unixEpochFilter(epoch_time)
```
You may use one or more tags to show them as annotations in a common-separated string.
**Example query using a `time` column with epoch values for a single tag:**
```sql
SELECT
epoch_time as time,
metric1 as text,
tag1 as tag
FROM
my_data
WHERE
$__unixEpochFilter(epoch_time)
```
**Example region query using `time` and `timeend` columns with epoch values:**
```sql
SELECT
epoch_time as time,
epoch_timeend as timeend,
metric1 as text,
CONCAT(tag1, ',', tag2) as tags
FROM
public.test_data
WHERE
$__unixEpochFilter(epoch_time)
```
**Example query using a `time` column with a native SQL date/time data type:**
```sql
SELECT
native_date_time as time,
metric1 as text,
CONCAT(tag1, ',', tag2) as tags
FROM
public.test_data
WHERE
$__timeFilter(native_date_time)
```
| Name | Description |
| --------- | --------------------------------------------------------------------------------------------------------------------- |
| `time` | The name of the date/time field, which can be a column with a native SQL date/time data type or epoch value. |
| `timeend` | Optional name of the end date/time field, which can be a column with a native SQL date/time data type or epoch value. |
| `text` | Event description field. |
| `tags` | Optional field name to use for event tags as a comma separated string. |
For detailed information on creating annotations with MySQL, refer to [MySQL annotations](ref:mysql-annotations).
## Alerting