mcpField
D
database-observability

database-observability

github.com/grafanaCloud & DevOps2954.3k installsUpdated 1d ago
Repository

About database-observability

A Grafana Cloud Database Observability skill for teams monitoring MySQL and PostgreSQL. It provides query-level performance data without application code changes, plus trace correlation and alerting guidance.

Key features

  1. 01Query-level RED metrics
  2. 02Query samples and explain plans
  3. 03MySQL and PostgreSQL monitoring
  4. 04APM trace correlation
  5. 05Latency, error, and saturation alerts

Use cases

  1. 01Find queries with high latency or call counts
  2. 02Inspect sampled SQL and explain plans
  3. 03Trace a slow service span to its SQL
  4. 04Alert on errors or connection-pool saturation

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/grafana/skills --skill database-observability

After installing, type/database-observabilityin Claude Code to confirm it loaded.

Bundled filesreferences/alloy-config.mdreferences/queries-alerts.md

Details

From the project README

Grafana Cloud Database Observability

Docs: https://grafana.com/docs/grafana-cloud/monitor-applications/database-observability/

Query-level insights (RED metrics, query samples, explain plans) for MySQL and PostgreSQL without application code changes. GA since April 2026.

Common Workflows

PostgreSQL setup
-- 1. Enable pg_stat_statements (requires restart)
--    In postgresql.conf:  shared_preload_libraries = 'pg_stat_statements'
--    Then restart PostgreSQL.

-- 2. Create a least-privilege monitoring user
CREATE USER grafana_monitoring WITH PASSWORD 'secret';
GRANT pg_monitor TO grafana_monitoring;
GRANT CONNECT ON DATABASE mydb TO grafana_monitoring;

-- 3. Enable the extension on each monitored DB
CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

-- 4. Verify
SELECT count(*) FROM pg_stat_statements;
-- Should return >= 0 (not an error). If "relation does not exist": step 3 didn't run.
  1. Add the Alloy config block from references/alloy-config.md § PostgreSQL
  2. Restart Alloy and wait ~60s for first scrape
  3. Verify in Grafana Cloud → Database Observability — the instance should appear with non-empty db_query_total{db_instance="mydb"} series. If empty after 2 minutes: check Alloy logs for connection errors, then re-verify pg_stat_statements permissions.
MySQL setup
-- 1. Create least-privilege monitoring user
CREATE USER 'grafana_monitoring'@'%' IDENTIFIED BY 'secret';
GRANT SELECT, PROCESS, REPLICATION CLIENT ON *.* TO 'grafana_monitoring'@'%';
GRANT SELECT ON performance_schema.* TO 'grafana_monitoring'@'%';
FLUSH PRIVILEGES;

-- 2. Verify performance_schema is enabled (default in MySQL 8+)
SELECT @@performance_schema;
-- Returns 1 → enabled. 0 → set performance_schema=ON in my.cnf + restart.
  1. Add the Alloy config block from references/alloy-config.md § MySQL
  2. Restart Alloy, wait ~60s, verify the instance appears in Grafana Cloud → Database Observability

Supported databases

DatabaseVariants
MySQLSelf-managed, RDS MySQL, Aurora MySQL, Cloud SQL MySQL, Azure Database for MySQL
PostgreSQLSelf-managed, RDS PostgreSQL, Aurora PostgreSQL, Cloud SQL PostgreSQL, Azure Database for PostgreSQL

For managed databases (RDS / Cloud SQL / Azure), pg_stat_statements is preinstalled but disabled — enable it via the parameter group / flag, then re-create the extension at the DB level.

What you get

  • Query Performance dashboard (auto-provisioned): top queries by total time / call count / mean latency, sampled query texts with parameters, visual explain plans, RED metrics per query digest
  • APM correlation: drill from a slow service-latency span to the specific slow SQL via db.statement / db.system / db.name OTel attributes — see references/queries-alerts.md § Trace correlation
  • Alerting on query latency, error rate, and connection-pool saturation — full alert YAML in references/queries-alerts.md § Alert rules

References

  • references/alloy-config.md — full Alloy database_observability.postgres / database_observability.mysql config blocks + collector reference (pg_stat_statements, query_samples, schema_details, explain_plans)
  • references/queries-alerts.md — key PromQL queries, alert rule YAML, and trace-correlation setup

Comments

Markdown supported