Telemetry reference

Database Observability collects telemetry from your PostgreSQL and MySQL databases through two Alloy pipelines: Prometheus exporter metrics and structured logs. This reference documents the metrics and logs available in Grafana Cloud, which ones the Database Observability dashboards use, and how to query them.

How telemetry is collected

Grafana Alloy collects telemetry through two component families that run in parallel:

                              ┌─ prometheus.exporter.*     ─▶ scrape ─▶ remote write ─▶ Mimir (metrics)
Database ──▶ Grafana Alloy ──┤
                              │  database_observability.*  ─▶ scrape ─▶ remote write ─▶ Mimir (metrics)
                              └─ database_observability.*  ─▶ forward_to ────────────▶ Loki  (logs)

The prometheus.exporter.* components produce query statistics metrics (for example, pg_stat_statements_*, mysql_perf_schema_*). The database_observability.* components produce both their own metrics (the database_observability_* series used by the Configuration page) and structured logs forwarded to Loki (query samples, explain plans, schema details, wait events). Database Observability correlates data from all three outputs to power its dashboards.

Metrics

These metrics are used by the Database Observability dashboards and Configuration page. If data is missing in the UI, check these first.

Connection and health metrics

These metrics come from the database_observability.* component’s metric targets (scraped into Mimir, not the log output). They power the Configuration page and instance discovery.

Metric	Type	Description
`database_observability_connection_info`	gauge	Instance metadata and connectivity status. Powers the Configuration page instance list.
`database_observability_setup_consumers_enabled`	gauge	Whether required MySQL `Performance Schema` consumers are enabled (MySQL only).
`database_observability_pg_errors_total`	counter	Total PostgreSQL error count (PostgreSQL only).

PostgreSQL query performance metrics

These metrics come from the prometheus.exporter.postgres component and require the pg_stat_statements extension.

Metric	Type	Used in
`pg_stat_statements_calls_total`	counter	Overview query rate, query list sorting
`pg_stat_statements_seconds_total`	counter	Overview latency, average duration calculations
`pg_stat_statements_rows_total`	counter	Rows returned/affected panels
`pg_stat_statements_blks_read_total`	counter	Buffer cache hit ratio calculations
`pg_stat_statements_blks_hit_total`	counter	Buffer cache hit ratio calculations

Labels:

Label	Description
`datname`	Database name
`usename`	User who executed the query
`queryid`	Unique identifier for the query

MySQL query performance metrics

These metrics come from the prometheus.exporter.mysql component and require Performance Schema.

Metric	Type	Used in
`mysql_perf_schema_events_statements_total`	counter	Overview query rate, query list sorting
`mysql_perf_schema_events_statements_seconds_total`	counter	Overview latency, average duration calculations
`mysql_perf_schema_events_statements_errors_total`	counter	Error rate panels
`mysql_perf_schema_events_statements_rows_sent_total`	counter	Rows returned panels
`mysql_perf_schema_events_statements_rows_examined_total`	counter	Rows examined panels
`mysql_perf_schema_events_statements_rows_affected_total`	counter	Rows modified panels
`mysql_perf_schema_events_statements_lock_time_seconds_total`	counter	Lock time panels
`mysql_perf_schema_events_statements_cpu_time_seconds_total`	counter	CPU time panels
`mysql_perf_schema_events_statements_latency`	histogram	P95/P99 latency percentile panels

Labels:

Label	Description
`schema`	Database schema
`digest`	Statement digest (normalized query identifier)
`user`	Database user

MySQL configuration validation metrics

These metrics come from the prometheus.exporter.mysql component and are checked by the Configuration page to verify that Performance Schema is properly configured.

Metric	Type	Description
`mysql_global_variables_performance_schema`	gauge	Whether `Performance Schema` is enabled
`mysql_global_variables_performance_schema_max_sql_text_length`	gauge	Maximum SQL text length captured
`mysql_global_variables_performance_schema_max_digest_length`	gauge	Maximum digest length
`mysql_global_variables_max_digest_length`	gauge	Maximum digest length (global variable)

Additional exporter metrics

The Prometheus exporters emit additional metrics beyond what the Database Observability dashboards use, including connections, replication, InnoDB, locks, and database size. These are available in Grafana Cloud Mimir for custom dashboards and alerting. For the full catalog, refer to the prometheus.exporter.postgres and prometheus.exporter.mysql Alloy component references.

Logs

Database Observability stores structured logs in Grafana Cloud Loki. Each log entry uses logfmt encoding and is identified by its op (operation) label. These logs power the detail-level features: query samples, explain plans, schema details, wait events, and configuration health checks.

All log entries share these stream labels:

Label	Description
`job`	Always `integrations/db-o11y`
`instance`	Database instance (`host:port`)
`op`	Operation type (see table below)
`server_id`	Unique server identifier

Log types

`op` value	UI feature	Key logfmt fields
`query_sample`	Samples tab, trace correlation	`digest` / `queryid`, `schema` / `datname`, `duration` / `time_elapsed`
`query_association`	Overview query list, query text display, search	`digest` / `queryid`, `digest_text` / `querytext`, `schema` / `datname`
`wait_event`	Wait Events tab, overview wait time column	`digest` / `queryid`, `wait_event_type`, `wait_event_name`, `wait_time`
`explain_plan_output`	Explain Plans tab	`digest`, `explain_plan_output` (base64-encoded)
`create_statement`	Schema tab	`table`, `table_spec` (base64-encoded)
`health_status`	Configuration page status checks	`check`, `result`

Field names vary by database engine: PostgreSQL uses queryid, datname, querytext, and time_elapsed; MySQL uses digest, schema, digest_text, and duration.

PromQL examples for custom monitoring

The Database Observability dashboards are pre-built and don’t require custom PromQL. The following examples show how to query these metrics for your own dashboards, recording rules, or alerts.

Calculate query rate

# PostgreSQL queries per second
rate(pg_stat_statements_calls_total[5m])

# MySQL statements per second
rate(mysql_perf_schema_events_statements_total[5m])

Calculate average query duration

# PostgreSQL average duration
rate(pg_stat_statements_seconds_total[5m]) / rate(pg_stat_statements_calls_total[5m])

# MySQL average duration
rate(mysql_perf_schema_events_statements_seconds_total[5m]) /
rate(mysql_perf_schema_events_statements_total[5m])

Calculate error rate

# MySQL error percentage
rate(mysql_perf_schema_events_statements_errors_total[5m]) /
rate(mysql_perf_schema_events_statements_total[5m]) * 100

Calculate buffer cache hit ratio

# PostgreSQL buffer hit ratio
rate(pg_stat_statements_blks_hit_total[5m]) /
(rate(pg_stat_statements_blks_hit_total[5m]) + rate(pg_stat_statements_blks_read_total[5m])) * 100

# MySQL InnoDB buffer pool hit ratio
(1 - rate(mysql_global_status_innodb_buffer_pool_reads_total[5m]) /
     rate(mysql_global_status_innodb_buffer_pool_read_requests_total[5m])) * 100

Identify slow queries

# PostgreSQL: Queries with average > 100ms
avg by (queryid, datname) (
  rate(pg_stat_statements_seconds_total[5m]) /
  rate(pg_stat_statements_calls_total[5m])
) > 0.1

# MySQL: Statements with average > 100ms
avg by (schema, digest) (
  rate(mysql_perf_schema_events_statements_seconds_total[5m]) /
  rate(mysql_perf_schema_events_statements_total[5m])
) > 0.1

Metric cardinality

Be aware of cardinality (number of unique time series) when monitoring many databases:

Factor	Impact on cardinality
Number of databases	Multiplies all per-database metrics
Number of unique queries	One series per query for statement metrics
Number of schemas	Additional dimension for MySQL metrics
Number of users	Additional dimension for PostgreSQL metrics

To reduce cardinality, refer to Tune Alloy collection, which covers statements_limit, schema exclusion, and collection interval tuning.