---
title: "Telemetry reference | Database Observability documentation"
description: "Reference documentation for all metrics and logs collected by Database Observability from MySQL and PostgreSQL databases."
---

> For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt).

# 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:

![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```none
                              ┌─ 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.

Expand table

| 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.

Expand table

| 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:**

Expand table

| 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`.

Expand table

| 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:**

Expand table

| 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.

Expand table

| 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`](/docs/alloy/latest/reference/components/prometheus.exporter.postgres/) and [`prometheus.exporter.mysql`](/docs/alloy/latest/reference/components/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:

Expand table

| 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

Expand table

| `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

promql ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```promql
# 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

promql ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```promql
# 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

promql ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```promql
# 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

promql ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```promql
# 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

promql ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```promql
# 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:

Expand table

| 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](/docs/grafana-cloud/monitor-applications/database-observability/configure/tune-alloy-collection/), which covers `statements_limit`, schema exclusion, and collection interval tuning.

## Related documentation

- [Labels reference](/docs/grafana-cloud/monitor-applications/database-observability/reference/labels/): Label documentation
- [PostgreSQL configuration](/docs/grafana-cloud/monitor-applications/database-observability/reference/postgres-configuration/): Configure PostgreSQL for metrics
- [MySQL configuration](/docs/grafana-cloud/monitor-applications/database-observability/reference/mysql-configuration/): Configure MySQL for metrics
- [Tune Alloy collection](/docs/grafana-cloud/monitor-applications/database-observability/configure/tune-alloy-collection/): Control what’s collected