---
title: MySQL NRDOT metrics reference
source: https://docs.newrelic.com/docs/opentelemetry/database/mysql/metrics-reference
---

> #### 💡 PREVIEW
>
> We're still working on this feature, but we'd love for you to try it out!
>
> This feature is currently provided as part of a preview pursuant to our [pre-release policies](https://docs.newrelic.com/docs/licenses/license-information/referenced-policies/new-relic-pre-release-policy/).

Monitor your MySQL database performance with comprehensive metrics collected by the NRDOT Collector. By default, New Relic collects the metrics referenced in the [Default metrics](#default) section. You can enhance your monitoring by enabling your desired metrics listed in the [Additional metrics](#additional) section.

**Default metrics**

The following metrics are collected automatically for New Relic UI functionality.

| Metric                           | Description                                         | Unit | Type                             | Attributes                                                                                                                                                                                                  |
| -------------------------------- | --------------------------------------------------- | ---- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mysql.buffer_pool.data_pages`   | Number of data pages in the InnoDB buffer pool      | `1`  | sum (cumulative, int)            | `status` (dirty, clean)                                                                                                                                                                                     |
| `mysql.buffer_pool.limit`        | Configured size of the InnoDB buffer pool           | `By` | sum (cumulative, int)            | —                                                                                                                                                                                                           |
| `mysql.buffer_pool.operations`   | Operations on the InnoDB buffer pool                | `1`  | sum (cumulative, int, monotonic) | `operation` (read_ahead_rnd, read_ahead, read_ahead_evicted, read_requests, reads, wait_free, write_requests)                                                                                               |
| `mysql.buffer_pool.page_flushes` | Requests to flush pages from the InnoDB buffer pool | `1`  | sum (cumulative, int, monotonic) | —                                                                                                                                                                                                           |
| `mysql.buffer_pool.pages`        | Number of pages in the InnoDB buffer pool           | `1`  | sum (cumulative, int)            | `kind` (data, free, misc, total)                                                                                                                                                                            |
| `mysql.buffer_pool.usage`        | Bytes in the InnoDB buffer pool                     | `By` | sum (cumulative, int)            | `status` (dirty, clean)                                                                                                                                                                                     |
| `mysql.double_writes`            | Writes to the InnoDB doublewrite buffer             | `1`  | sum (cumulative, int, monotonic) | `kind` (pages_written, writes)                                                                                                                                                                              |
| `mysql.handlers`                 | Requests to various MySQL handlers                  | `1`  | sum (cumulative, int, monotonic) | `kind` (commit, delete, discover, external_lock, mrr_init, prepare, read_first, read_key, read_last, read_next, read_prev, read_rnd, read_rnd_next, rollback, savepoint, savepoint_rollback, update, write) |
| `mysql.index.io.wait.count`      | I/O wait event count for an index                   | `1`  | sum (cumulative, int, monotonic) | `operation`, `table`, `schema`, `index`                                                                                                                                                                     |
| `mysql.index.io.wait.time`       | I/O wait event time for an index                    | `ns` | sum (cumulative, int, monotonic) | `operation`, `table`, `schema`, `index`                                                                                                                                                                     |
| `mysql.locks`                    | Number of MySQL locks                               | `1`  | sum (cumulative, int, monotonic) | `kind` (immediate, waited)                                                                                                                                                                                  |
| `mysql.log_operations`           | InnoDB log operations                               | `1`  | sum (cumulative, int, monotonic) | `operation` (waits, write_requests, writes, fsyncs)                                                                                                                                                         |
| `mysql.mysqlx_connections`       | mysqlx connections (X Plugin / Document Store)      | `1`  | sum (cumulative, int, monotonic) | `status` (accepted, closed, rejected)                                                                                                                                                                       |
| `mysql.opened_resources`         | Number of opened resources                          | `1`  | sum (cumulative, int, monotonic) | `kind` (file, table_definition, table)                                                                                                                                                                      |
| `mysql.operations`               | InnoDB operations                                   | `1`  | sum (cumulative, int, monotonic) | `operation` (fsyncs, reads, writes)                                                                                                                                                                         |
| `mysql.page_operations`          | InnoDB page operations                              | `1`  | sum (cumulative, int, monotonic) | `operation` (created, read, written)                                                                                                                                                                        |
| `mysql.prepared_statements`      | Prepared statement commands issued                  | `1`  | sum (cumulative, int, monotonic) | `command` (execute, close, fetch, prepare, reset, send_long_data)                                                                                                                                           |
| `mysql.row_locks`                | InnoDB row locks                                    | `1`  | sum (cumulative, int, monotonic) | `kind` (waits, time)                                                                                                                                                                                        |
| `mysql.row_operations`           | InnoDB row operations                               | `1`  | sum (cumulative, int, monotonic) | `operation` (deleted, inserted, read, updated)                                                                                                                                                              |
| `mysql.sorts`                    | Number of MySQL sorts                               | `1`  | sum (cumulative, int, monotonic) | `kind` (merge_passes, range, rows, scan)                                                                                                                                                                    |
| `mysql.table.io.wait.count`      | I/O wait event count for a table                    | `1`  | sum (cumulative, int, monotonic) | `operation`, `table`, `schema`                                                                                                                                                                              |
| `mysql.table.io.wait.time`       | I/O wait event time for a table                     | `ns` | sum (cumulative, int, monotonic) | `operation`, `table`, `schema`                                                                                                                                                                              |
| `mysql.threads`                  | State of MySQL threads                              | `1`  | sum (cumulative, int)            | `kind` (cached, connected, created, running)                                                                                                                                                                |
| `mysql.tmp_resources`            | Temporary resources created                         | `1`  | sum (cumulative, int, monotonic) | `resource` (disk_tables, files, tables)                                                                                                                                                                     |
| `mysql.uptime`                   | Seconds the server has been up                      | `s`  | sum (cumulative, int, monotonic) | —                                                                                                                                                                                                           |

## Additional metrics [#additional]

The following metrics are disabled by default but can be enabled for deeper insights into MySQL performance and health. These metrics are organized by functionality and most require a direct MySQL connection.

**Connections, threads & sessions**

| Metric                        | Description                                     | Unit | Type                             | Attributes                                                                                                   |
| ----------------------------- | ----------------------------------------------- | ---- | -------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `mysql.connection.count`      | Connection attempts (successful or not)         | `1`  | sum (cumulative, int, monotonic) | —                                                                                                            |
| `mysql.connection.errors`     | Errors during the client connection process     | `1`  | sum (cumulative, int, monotonic) | `error` (accept, internal, max_connections, peer_address, select, tcpwrap, aborted, aborted_clients, locked) |
| `mysql.max_used_connections`  | Max simultaneous connections since server start | `1`  | sum (cumulative, int)            | —                                                                                                            |
| `mysql.client.network.io`     | Bytes transmitted between server and clients    | `By` | sum (cumulative, int, monotonic) | `kind` (received, sent)                                                                                      |
| `mysql.mysqlx_worker_threads` | mysqlx worker threads available                 | `1`  | sum (cumulative, int)            | `kind` (available, active)                                                                                   |

**Query & statement statistics**

| Metric                            | Description                                   | Unit | Type                             | Attributes                                                                                                                                                                                      |
| --------------------------------- | --------------------------------------------- | ---- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mysql.commands`                  | Times each command type was executed          | `1`  | sum (cumulative, int, monotonic) | `command` (delete, delete_multi, insert, select, update, update_multi)                                                                                                                          |
| `mysql.query.count`               | Statements executed by the server             | `1`  | sum (cumulative, int, monotonic) | —                                                                                                                                                                                               |
| `mysql.query.client.count`        | Statements sent to the server by clients only | `1`  | sum (cumulative, int, monotonic) | —                                                                                                                                                                                               |
| `mysql.query.slow.count`          | Slow queries                                  | `1`  | sum (cumulative, int, monotonic) | —                                                                                                                                                                                               |
| `mysql.joins`                     | Joins that perform table scans                | `1`  | sum (cumulative, int, monotonic) | `kind` (full, full_range, range, range_check, scan)                                                                                                                                             |
| `mysql.statement_event.count`     | Summary of current/recent statement events    | `1`  | sum (cumulative, int)            | `schema`, `digest`, `digest_text`, `kind` (errors, warnings, rows_affected, rows_sent, rows_examined, created_tmp_disk_tables, created_tmp_tables, sort_merge_passes, sort_rows, no_index_used) |
| `mysql.statement_event.wait.time` | Total wait time of summarized timed events    | `ns` | sum (cumulative, int)            | `schema`, `digest`, `digest_text`                                                                                                                                                               |

**Tables & schema**

| Metric                              | Description                                     | Unit | Type                             | Attributes                                                                                 |
| ----------------------------------- | ----------------------------------------------- | ---- | -------------------------------- | ------------------------------------------------------------------------------------------ |
| `mysql.table.average_row_length`    | Average row length for a table                  | `By` | sum (cumulative, int)            | `table`, `schema`                                                                          |
| `mysql.table.rows`                  | Row count for a table                           | `1`  | sum (cumulative, int)            | `table`, `schema`                                                                          |
| `mysql.table.size`                  | Table size                                      | `By` | sum (cumulative, int)            | `table`, `schema`, `kind` (data, index)                                                    |
| `mysql.table_open_cache`            | Hits/misses/overflows for the open-tables cache | `1`  | sum (cumulative, int, monotonic) | `status` (hit, miss, overflow)                                                             |
| `mysql.table.lock_wait.read.count`  | Table lock wait read events                     | `1`  | sum (cumulative, int)            | `schema`, `table`, `kind` (normal, with_shared_locks, high_priority, no_insert, external)  |
| `mysql.table.lock_wait.read.time`   | Table lock wait read event time                 | `ns` | sum (cumulative, int)            | `schema`, `table`, `kind` (normal, with_shared_locks, high_priority, no_insert, external)  |
| `mysql.table.lock_wait.write.count` | Table lock wait write events                    | `1`  | sum (cumulative, int)            | `schema`, `table`, `kind` (allow_write, concurrent_insert, low_priority, normal, external) |
| `mysql.table.lock_wait.write.time`  | Table lock wait write event time                | `ns` | sum (cumulative, int)            | `schema`, `table`, `kind` (allow_write, concurrent_insert, low_priority, normal, external) |

**Replication & server metadata**

| Metric                             | Description                             | Unit | Type                  | Attributes |
| ---------------------------------- | --------------------------------------- | ---- | --------------------- | ---------- |
| `mysql.replica.sql_delay`          | Seconds the replica must lag the source | `s`  | sum (cumulative, int) | —          |
| `mysql.replica.time_behind_source` | How "late" the replica is               | `s`  | sum (cumulative, int) | —          |
| `mysql.page_size`                  | InnoDB page size                        | `By` | sum (cumulative, int) | —          |

## Log events [#log-events]

### `db.server.query_sample`

Real-time visibility into currently-running database statements — a point-in-time snapshot taken every scrape, not a complete execution log. Disabled by default.

| Attribute                                     | Description                                                                                                                                                                                                                                                            |
| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `db.system.name`                              | `mysql`                                                                                                                                                                                                                                                                |
| `mysql.threads.thread_id`                     | Unique identifier for the thread executing the statement                                                                                                                                                                                                               |
| `mysql.session.id`                            | `PROCESSLIST_ID` — the connection ID visible via `SHOW PROCESSLIST`                                                                                                                                                                                                    |
| `user.name`                                   | Foreground-thread user; empty for background threads                                                                                                                                                                                                                   |
| `db.namespace`                                | Thread's current database (`processlist_db`)                                                                                                                                                                                                                           |
| `mysql.threads.processlist_command`           | Command type, or `Sleep` if idle                                                                                                                                                                                                                                       |
| `mysql.threads.processlist_state`             | Current action/state of the thread                                                                                                                                                                                                                                     |
| `db.query.text`                               | SQL statement text                                                                                                                                                                                                                                                     |
| `mysql.events_statements_current.digest`      | SHA-256 statement digest                                                                                                                                                                                                                                               |
| `mysql.events_statements_current.timer_start` | Monotonic picosecond counter marking statement start — a stable per-execution key across scrape cycles                                                                                                                                                                 |
| `mysql.events_statements_current.timer_wait`  | Elapsed execution time, in seconds                                                                                                                                                                                                                                     |
| `mysql.events_waits_current.timer_wait`       | Elapsed wait time, in seconds (requires the `events_waits_current` consumer)                                                                                                                                                                                           |
| `mysql.wait_event_type`                       | Top-level wait classification derived from the wait event name (`io`, `lock`, `synch`), or `CPU`/`User sleep`/`other` when not actually waiting. Paired with `mysql.wait_event`.                                                                                       |
| `mysql.wait_event`                            | Detailed wait breakdown — the wait event name with its category segment stripped (for example, `table/sql/handler`, `mutex/innodb/checkpoint_state`), or `CPU`/`User sleep`/`other` when not actually waiting. Paired with `mysql.wait_event_type`.                    |
| `mysql.wait_type`                             | Raw, unprocessed name of the instrument that produced the wait event — for the parsed/categorized breakdown, see `mysql.wait_event_type` / `mysql.wait_event`.                                                                                                         |
| `mysql.session.status`                        | `waiting`, `running`, or `other`                                                                                                                                                                                                                                       |
| `mysql.query_plan` / `mysql.query_plan.hash`  | Query plan, if available, and its cache key                                                                                                                                                                                                                            |
| `mysql.event_id`                              | Thread + current event number when the event started                                                                                                                                                                                                                   |
| `client.address` / `client.port`              | Client host/port (port populated on MySQL 8.0.22+ only, else `0`)                                                                                                                                                                                                      |
| `network.peer.address` / `network.peer.port`  | Same, as network-layer attributes                                                                                                                                                                                                                                      |
| `mysql.blocking.blockers`                     | JSON array of `{thread_id, session_id}` tuples, one per concurrent InnoDB row-lock blocker for this session — not just the first, if more than one exists. `"[]"` when not blocked; a blocker's `session_id` is `null` if it disconnected before it could be resolved. |
| `mysql.blocking.blocker.count`                | Integer count of concurrent blockers. `0` means not blocked.                                                                                                                                                                                                           |
| `mysql.session.client_name`                   | Client driver's self-reported identity (for example, `MySQL Connector/J`), from `session_connect_attrs`. Empty if the driver doesn't send connect attributes.                                                                                                          |
| `db.query.comment_tags` / `.nr_service_guid`  | APM-correlation comment tags — see [(Optional) Set up APM-database correlation](https://docs.newrelic.com/docs/opentelemetry/database/mysql/hosted#validate)                                                                                                           |
| `db.query.text.normalized.hash`               | MD5 of normalized SQL for cross-engine correlation                                                                                                                                                                                                                     |

> #### 💡 TIP
>
> Filter blocking with `mysql.blocking.blocker.count > 0`, not `!= 0` — `null != 0` evaluates `TRUE` in NRQL, which would silently include non-blocked sessions in your results.

### `db.server.top_query`

The queries consuming the most execution time, aggregated server-side by MySQL's own `performance_schema.events_statements_summary_by_digest` — a true per-digest execution counter, not a sample count. Disabled by default.

| Attribute                                                                        | Description                                                                                                        |
| -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `db.system.name`                                                                 | `mysql`                                                                                                            |
| `db.query.text`                                                                  | SQL statement text (obfuscated)                                                                                    |
| `db.namespace`                                                                   | Digest's `SCHEMA_NAME`                                                                                             |
| `mysql.events_statements_summary_by_digest.digest`                               | SHA-256 statement digest                                                                                           |
| `mysql.events_statements_summary_by_digest.count_star`                           | Times the statement executed, reported as a **per-scrape delta**, not cumulative                                   |
| `mysql.events_statements_summary_by_digest.sum_timer_wait`                       | Total execution time, delta seconds                                                                                |
| `mysql.events_statements_summary_by_digest.sum_rows_examined` / `.sum_rows_sent` | Delta row counts — dividing by `count_star` gives per-execution averages. These are row counts, not logical reads. |
| `mysql.query_plan` / `mysql.query_plan.hash`                                     | Query plan (via `EXPLAIN`), if available — see [Execution plan collection](#explain)                               |
| `db.query.comment_tags` / `.nr_service_guid`                                     | Same as `query_sample`                                                                                             |
| `db.query.text.normalized.hash`                                                  | Same as `query_sample`                                                                                             |

### Execution plan collection [#explain]

`EXPLAIN` needs a literal SQL statement — the normalized digest text uses placeholders (`SELECT ? FROM t WHERE id = ?`) that MySQL can't execute.

| MySQL version          | Plan availability                                                                               |
| ---------------------- | ----------------------------------------------------------------------------------------------- |
| `8.0.3`+               | Available — `query_sample_text` on the digest summary table holds a real statement to `EXPLAIN` |
| `5.x`, `8.0.0`–`8.0.2` | Not available — no `query_sample_text` to explain                                               |

If a captured statement is truncated (ends in `...`), `EXPLAIN` is skipped on every version — see [Recommended server parameters](https://docs.newrelic.com/docs/opentelemetry/database/mysql/compatibility#params).

| `explain_mode`     | Behavior                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `inline` (default) | Runs `EXPLAIN FORMAT=json <statement>` directly — sufficient for `SELECT`-only workloads                                                                                                                                                                                                                                                                                                                                               |
| `procedure`        | Routes through a `SQL SECURITY DEFINER` procedure (`<schema>.explain_statement`) so write statements (`UPDATE`/`DELETE`/`INSERT`/`REPLACE`) can be explained without granting DML to the monitoring user. Falls back to `inline` if the procedure is missing. Requires the one-time setup step per schema — see [Query plans for write statements](https://docs.newrelic.com/docs/opentelemetry/database/mysql/advanced-config#query). |

> #### ⚠️ IMPORTANT
>
> `mysql.query_plan` is the raw `EXPLAIN FORMAT=json` output, wrapped in a one-element JSON array before caching, so New Relic's log ingest doesn't auto-flatten and destroy it. Parse index `[0]` to recover the plan object.

## Timer units

| Telemetry type                                                    | Fields                                                                                      | Unit            |
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | --------------- |
| Log events (`query_sample`, `top_query`)                          | `sum_timer_wait`, `events_statements_current.timer_wait`, `events_waits_current.timer_wait` | **seconds**     |
| Metrics (statement events, table/index I/O wait, table lock wait) | per `metadata.yaml` unit: ns                                                                | **nanoseconds** |

> #### ⚠️ IMPORTANT
>
> `mysql.events_waits_current.timer_wait` is the one field that is a genuine, distinct wait/block duration (not total elapsed time) — pair it with `mysql.wait_event_type` / `mysql.wait_event` (or the raw `mysql.wait_type`).

## Related documentation [#related]

[Instrumentation in self-hosted environments](https://docs.newrelic.com/docs/opentelemetry/database/mysql/hosted)

Learn how to set up MySQL monitoring in self-hosted environments with New Relic.

[Instrumentation in RDS environments](https://docs.newrelic.com/docs/opentelemetry/database/mysql/rds)

Learn how to set up MySQL monitoring in RDS environments with New Relic.

[Troubleshooting guide](https://docs.newrelic.com/docs/opentelemetry/database/mysql/troubleshooting)

Learn how to troubleshoot common issues with MySQL monitoring.