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

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 section. You can enhance your monitoring by enabling your desired metrics listed in the Additional metrics section.

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

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.

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)

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`

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)

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

`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
`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
`db.query.comment_tags` / `.nr_service_guid`	Same as `query_sample`
`db.query.text.normalized.hash`	Same as `query_sample`

Execution plan collection

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.

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

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

Instrumentation in self-hosted environments

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

Instrumentation in RDS environments

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

Troubleshooting guide

Learn how to troubleshoot common issues with MySQL monitoring.

Preview

Default metrics

Additional metrics

Connections, threads & sessions

Query & statement statistics

Tables & schema

Replication & server metadata

Log events

`db.server.query_sample`

Tip

`db.server.top_query`

Execution plan collection

Important

Timer units

Important

Instrumentation in self-hosted environments

Instrumentation in RDS environments

Troubleshooting guide

MySQL NRDOT metrics reference

Preview

Additional metrics .css-21sua1{background:none;border:none;width:0;padding:0;}

Connections, threads & sessions

Query & statement statistics

Tables & schema

Replication & server metadata

Log events

db.server.query_sample

Tip

db.server.top_query

Execution plan collection

Important

Timer units

Important

Related documentation

Instrumentation in self-hosted environments

Instrumentation in RDS environments

Troubleshooting guide

Additional metrics

`db.server.query_sample`

`db.server.top_query`