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

docs: update the technical note for annotation bloat (#115267)

Browse Source
This commit is contained in:
Jacob Valdez
2025-12-16 16:10:49 -06:00
committed by GitHub
parent e21bdbe89a
commit 706468f2b7
4 changed files with 180 additions and 44 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/sources/upgrade-guide/upgrade-v12.0/index.md
+45 -11
View File
@@ -81,24 +81,26 @@ Since Grafana 10.2, the endpoint to check compatible versions when installing a
We _do not_ recommend installing plugins declared as incompatible. However, if you need to force install a plugin despite it being declared as incompatible, refer to the [Installing a plugin from a ZIP](https://grafana.com/docs/grafana/latest/administration/plugin-management/#install-a-plugin-from-a-zip-file) guidance.
### PostgreSQL annotation table migration
### Annotation table migration
**Plan for increased disk usage when upgrading from Grafana v11.x**
Upgrading from Grafana v11.x to Grafana v12.x triggers a full-table rewrite of the PostgreSQL `annotation` table. The migration populates the new `dashboard_uid` column, which causes PostgreSQL to rewrite the entire table and rebuild its indexes.
Upgrading from Grafana v11.x to Grafana v12.x triggers a full-table rewrite of the `annotation` table. The migration populates the new `dashboard_uid` column, which causes the database to rewrite the entire table and rebuild its indexes.
Environments with large annotation datasets can experience significant temporary disk usage increase, which may lead to:
- Rapid disk consumption on the PostgreSQL data volume
- Rapid disk consumption on the database data volume
- Database migration failures (for example, "could not extend file: No space left on device")
- Grafana startup failures
- Extended downtime during the upgrade process
#### How do I know if I'm affected?
You're affected if you're upgrading from Grafana v11.x to v12.x and you have a large `annotation` table in your PostgreSQL database.
You're affected if you're upgrading from Grafana v11.x to v12.x and you have a large `annotation` table in your database.
To check your annotation table size, connect to your PostgreSQL database and run the following query:
To check your annotation table size, connect to your database and check the table size.
For PostgreSQL, run the following query:
```sql
SELECT
@@ -107,26 +109,58 @@ SELECT
pg_size_pretty(pg_total_relation_size('annotation')) AS total_size;
```
For MySQL, run the following query:
```sql
SELECT
ROUND(data_length / 1024 / 1024, 2) AS table_size_mb,
ROUND(index_length / 1024 / 1024, 2) AS indexes_size_mb,
ROUND((data_length + index_length) / 1024 / 1024, 2) AS total_size_mb
FROM information_schema.tables
WHERE table_schema = DATABASE()
AND table_name = 'annotation';
```
For SQLite, check the database file size directly, as SQLite stores all tables in a single file. You can run the following command from your terminal:
```bash
ls -lh <PATH/TO/GRAFANA.DB>
```
If your total size is several gigabytes or more, you should plan accordingly before upgrading.
#### What should I do before upgrading?
Before you upgrade, take the following steps:
1. **Verify available disk space**: Ensure you have at least 2-3 times the current `annotation` table size available as free disk space on your PostgreSQL data volume.
1. **Verify available disk space**: Ensure you have at least 2-3 times the current `annotation` table size available as free disk space on your database data volume.
2. **Review your annotation data**: Consider whether you need to retain all historical annotations.
1. **Review your annotation data**: Consider whether you need to retain all historical annotations.
3. **Clean up old annotations (optional)**: If you have annotations you don't need, remove them before upgrading.
1. **Clean up old annotations (optional)**: If you have annotations you don't need, remove them before upgrading.
4. **Back up your database**: Always back up your Grafana database before performing an upgrade. For more information, refer to [Back up Grafana](#back-up-grafana).
1. **Back up your database**: Always back up your Grafana database before performing an upgrade. For more information, refer to [Back up Grafana](#back-up-grafana).
#### What should I do after upgrading?
After successfully upgrading to Grafana v12.x, you can reclaim disk space by running a `VACUUM FULL` operation on the `annotation` table during a maintenance window:
After successfully upgrading to Grafana v12.x, you can reclaim disk space by performing database maintenance operations during a maintenance window.
For PostgreSQL, run a `VACUUM FULL` operation on the `annotation` table:
```sql
VACUUM FULL annotation;
```
This operation requires a lock on the table and may take significant time depending on the table size. Plan to run this during a low-traffic period.
For MySQL, run an `OPTIMIZE TABLE` operation on the `annotation` table:
```sql
OPTIMIZE TABLE annotation;
```
For SQLite, run a `VACUUM` operation on the database:
```sql
VACUUM;
```
These operations require a lock on the table and may take significant time depending on the table size. Plan to run these during a low-traffic period.
docs/sources/upgrade-guide/upgrade-v12.1/index.md
+45 -11
View File
@@ -21,24 +21,26 @@ weight: 499
## Technical notes
### PostgreSQL annotation table migration
### Annotation table migration
**Plan for increased disk usage when upgrading from Grafana v11.x**
Upgrading from Grafana v11.x to Grafana v12.x triggers a full-table rewrite of the PostgreSQL `annotation` table. The migration populates the new `dashboard_uid` column, which causes PostgreSQL to rewrite the entire table and rebuild its indexes.
Upgrading from Grafana v11.x to Grafana v12.x triggers a full-table rewrite of the `annotation` table. The migration populates the new `dashboard_uid` column, which causes the database to rewrite the entire table and rebuild its indexes.
Environments with large annotation datasets can experience significant temporary disk usage increase, which may lead to:
- Rapid disk consumption on the PostgreSQL data volume
- Rapid disk consumption on the database data volume
- Database migration failures (for example, "could not extend file: No space left on device")
- Grafana startup failures
- Extended downtime during the upgrade process
#### How do I know if I'm affected?
You're affected if you're upgrading from Grafana v11.x to v12.x and you have a large `annotation` table in your PostgreSQL database.
You're affected if you're upgrading from Grafana v11.x to v12.x and you have a large `annotation` table in your database.
To check your annotation table size, connect to your PostgreSQL database and run the following query:
To check your annotation table size, connect to your database and check the table size.
For PostgreSQL, run the following query:
```sql
SELECT
@@ -47,26 +49,58 @@ SELECT
pg_size_pretty(pg_total_relation_size('annotation')) AS total_size;
```
For MySQL, run the following query:
```sql
SELECT
ROUND(data_length / 1024 / 1024, 2) AS table_size_mb,
ROUND(index_length / 1024 / 1024, 2) AS indexes_size_mb,
ROUND((data_length + index_length) / 1024 / 1024, 2) AS total_size_mb
FROM information_schema.tables
WHERE table_schema = DATABASE()
AND table_name = 'annotation';
```
For SQLite, check the database file size directly, as SQLite stores all tables in a single file. You can run the following command from your terminal:
```bash
ls -lh <PATH/TO/GRAFANA.DB>
```
If your total size is several gigabytes or more, you should plan accordingly before upgrading.
#### What should I do before upgrading?
Before you upgrade, take the following steps:
1. **Verify available disk space**: Ensure you have at least 2-3 times the current `annotation` table size available as free disk space on your PostgreSQL data volume.
1. **Verify available disk space**: Ensure you have at least 2-3 times the current `annotation` table size available as free disk space on your database data volume.
2. **Review your annotation data**: Consider whether you need to retain all historical annotations.
1. **Review your annotation data**: Consider whether you need to retain all historical annotations.
3. **Clean up old annotations (optional)**: If you have annotations you don't need, remove them before upgrading.
1. **Clean up old annotations (optional)**: If you have annotations you don't need, remove them before upgrading.
4. **Back up your database**: Always back up your Grafana database before performing an upgrade. For more information, refer to [Back up Grafana](#back-up-grafana).
1. **Back up your database**: Always back up your Grafana database before performing an upgrade. For more information, refer to [Back up Grafana](#back-up-grafana).
#### What should I do after upgrading?
After successfully upgrading to Grafana v12.x, you can reclaim disk space by running a `VACUUM FULL` operation on the `annotation` table during a maintenance window:
After successfully upgrading to Grafana v12.x, you can reclaim disk space by performing database maintenance operations during a maintenance window.
For PostgreSQL, run a `VACUUM FULL` operation on the `annotation` table:
```sql
VACUUM FULL annotation;
```
This operation requires a lock on the table and may take significant time depending on the table size. Plan to run this during a low-traffic period.
For MySQL, run an `OPTIMIZE TABLE` operation on the `annotation` table:
```sql
OPTIMIZE TABLE annotation;
```
For SQLite, run a `VACUUM` operation on the database:
```sql
VACUUM;
```
These operations require a lock on the table and may take significant time depending on the table size. Plan to run these during a low-traffic period.
docs/sources/upgrade-guide/upgrade-v12.2/index.md
+45 -11
View File
@@ -21,24 +21,26 @@ weight: 498
## Technical notes
### PostgreSQL annotation table migration
### Annotation table migration
**Plan for increased disk usage when upgrading from Grafana v11.x**
Upgrading from Grafana v11.x to Grafana v12.x triggers a full-table rewrite of the PostgreSQL `annotation` table. The migration populates the new `dashboard_uid` column, which causes PostgreSQL to rewrite the entire table and rebuild its indexes.
Upgrading from Grafana v11.x to Grafana v12.x triggers a full-table rewrite of the `annotation` table. The migration populates the new `dashboard_uid` column, which causes the database to rewrite the entire table and rebuild its indexes.
Environments with large annotation datasets can experience significant temporary disk usage increase, which may lead to:
- Rapid disk consumption on the PostgreSQL data volume
- Rapid disk consumption on the database data volume
- Database migration failures (for example, "could not extend file: No space left on device")
- Grafana startup failures
- Extended downtime during the upgrade process
#### How do I know if I'm affected?
You're affected if you're upgrading from Grafana v11.x to v12.x and you have a large `annotation` table in your PostgreSQL database.
You're affected if you're upgrading from Grafana v11.x to v12.x and you have a large `annotation` table in your database.
To check your annotation table size, connect to your PostgreSQL database and run the following query:
To check your annotation table size, connect to your database and check the table size.
For PostgreSQL, run the following query:
```sql
SELECT
@@ -47,26 +49,58 @@ SELECT
pg_size_pretty(pg_total_relation_size('annotation')) AS total_size;
```
For MySQL, run the following query:
```sql
SELECT
ROUND(data_length / 1024 / 1024, 2) AS table_size_mb,
ROUND(index_length / 1024 / 1024, 2) AS indexes_size_mb,
ROUND((data_length + index_length) / 1024 / 1024, 2) AS total_size_mb
FROM information_schema.tables
WHERE table_schema = DATABASE()
AND table_name = 'annotation';
```
For SQLite, check the database file size directly, as SQLite stores all tables in a single file. You can run the following command from your terminal:
```bash
ls -lh <PATH/TO/GRAFANA.DB>
```
If your total size is several gigabytes or more, you should plan accordingly before upgrading.
#### What should I do before upgrading?
Before you upgrade, take the following steps:
1. **Verify available disk space**: Ensure you have at least 2-3 times the current `annotation` table size available as free disk space on your PostgreSQL data volume.
1. **Verify available disk space**: Ensure you have at least 2-3 times the current `annotation` table size available as free disk space on your database data volume.
2. **Review your annotation data**: Consider whether you need to retain all historical annotations.
1. **Review your annotation data**: Consider whether you need to retain all historical annotations.
3. **Clean up old annotations (optional)**: If you have annotations you don't need, remove them before upgrading.
1. **Clean up old annotations (optional)**: If you have annotations you don't need, remove them before upgrading.
4. **Back up your database**: Always back up your Grafana database before performing an upgrade. For more information, refer to [Back up Grafana](#back-up-grafana).
1. **Back up your database**: Always back up your Grafana database before performing an upgrade. For more information, refer to [Back up Grafana](#back-up-grafana).
#### What should I do after upgrading?
After successfully upgrading to Grafana v12.x, you can reclaim disk space by running a `VACUUM FULL` operation on the `annotation` table during a maintenance window:
After successfully upgrading to Grafana v12.x, you can reclaim disk space by performing database maintenance operations during a maintenance window.
For PostgreSQL, run a `VACUUM FULL` operation on the `annotation` table:
```sql
VACUUM FULL annotation;
```
This operation requires a lock on the table and may take significant time depending on the table size. Plan to run this during a low-traffic period.
For MySQL, run an `OPTIMIZE TABLE` operation on the `annotation` table:
```sql
OPTIMIZE TABLE annotation;
```
For SQLite, run a `VACUUM` operation on the database:
```sql
VACUUM;
```
These operations require a lock on the table and may take significant time depending on the table size. Plan to run these during a low-traffic period.
docs/sources/upgrade-guide/upgrade-v12.3/index.md
+45 -11
View File
@@ -21,24 +21,26 @@ weight: 497
## Technical notes
### PostgreSQL annotation table migration
### Annotation table migration
**Plan for increased disk usage when upgrading from Grafana v11.x**
Upgrading from Grafana v11.x to Grafana v12.x triggers a full-table rewrite of the PostgreSQL `annotation` table. The migration populates the new `dashboard_uid` column, which causes PostgreSQL to rewrite the entire table and rebuild its indexes.
Upgrading from Grafana v11.x to Grafana v12.x triggers a full-table rewrite of the `annotation` table. The migration populates the new `dashboard_uid` column, which causes the database to rewrite the entire table and rebuild its indexes.
Environments with large annotation datasets can experience significant temporary disk usage increase, which may lead to:
- Rapid disk consumption on the PostgreSQL data volume
- Rapid disk consumption on the database data volume
- Database migration failures (for example, "could not extend file: No space left on device")
- Grafana startup failures
- Extended downtime during the upgrade process
#### How do I know if I'm affected?
You're affected if you're upgrading from Grafana v11.x to v12.x and you have a large `annotation` table in your PostgreSQL database.
You're affected if you're upgrading from Grafana v11.x to v12.x and you have a large `annotation` table in your database.
To check your annotation table size, connect to your PostgreSQL database and run the following query:
To check your annotation table size, connect to your database and check the table size.
For PostgreSQL, run the following query:
```sql
SELECT
@@ -47,26 +49,58 @@ SELECT
pg_size_pretty(pg_total_relation_size('annotation')) AS total_size;
```
For MySQL, run the following query:
```sql
SELECT
ROUND(data_length / 1024 / 1024, 2) AS table_size_mb,
ROUND(index_length / 1024 / 1024, 2) AS indexes_size_mb,
ROUND((data_length + index_length) / 1024 / 1024, 2) AS total_size_mb
FROM information_schema.tables
WHERE table_schema = DATABASE()
AND table_name = 'annotation';
```
For SQLite, check the database file size directly, as SQLite stores all tables in a single file. You can run the following command from your terminal:
```bash
ls -lh <PATH/TO/GRAFANA.DB>
```
If your total size is several gigabytes or more, you should plan accordingly before upgrading.
#### What should I do before upgrading?
Before you upgrade, take the following steps:
1. **Verify available disk space**: Ensure you have at least 2-3 times the current `annotation` table size available as free disk space on your PostgreSQL data volume.
1. **Verify available disk space**: Ensure you have at least 2-3 times the current `annotation` table size available as free disk space on your database data volume.
2. **Review your annotation data**: Consider whether you need to retain all historical annotations.
1. **Review your annotation data**: Consider whether you need to retain all historical annotations.
3. **Clean up old annotations (optional)**: If you have annotations you don't need, remove them before upgrading.
1. **Clean up old annotations (optional)**: If you have annotations you don't need, remove them before upgrading.
4. **Back up your database**: Always back up your Grafana database before performing an upgrade. For more information, refer to [Back up Grafana](#back-up-grafana).
1. **Back up your database**: Always back up your Grafana database before performing an upgrade. For more information, refer to [Back up Grafana](#back-up-grafana).
#### What should I do after upgrading?
After successfully upgrading to Grafana v12.x, you can reclaim disk space by running a `VACUUM FULL` operation on the `annotation` table during a maintenance window:
After successfully upgrading to Grafana v12.x, you can reclaim disk space by performing database maintenance operations during a maintenance window.
For PostgreSQL, run a `VACUUM FULL` operation on the `annotation` table:
```sql
VACUUM FULL annotation;
```
This operation requires a lock on the table and may take significant time depending on the table size. Plan to run this during a low-traffic period.
For MySQL, run an `OPTIMIZE TABLE` operation on the `annotation` table:
```sql
OPTIMIZE TABLE annotation;
```
For SQLite, run a `VACUUM` operation on the database:
```sql
VACUUM;
```
These operations require a lock on the table and may take significant time depending on the table size. Plan to run these during a low-traffic period.