> ## Documentation Index > Fetch the complete documentation index at: https://otel.fyi/llms.txt > Use this file to discover all available pages before exploring further. # Mysql > OpenTelemetry receiver for Mysql # Mysql Receiver ![Status](https://img.shields.io/badge/status-beta-yellow) **Available in:** `contrib` **Maintainers:** [@antonblock](https://github.com/antonblock), [@ishleenk17](https://github.com/ishleenk17) **Source:** [opentelemetry-collector-contrib](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/mysqlreceiver) ## Supported Telemetry ![Logs](https://img.shields.io/badge/logs-development-blue) ![Metrics](https://img.shields.io/badge/metrics-beta-green) ## Overview This receiver queries MySQL's global status and InnoDB tables. Some metrics will not appear if their corresponding feature is inactive.\ There are also optional metrics that you must specify in your configuration to collect, listed in [documentation.md](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/mysqlreceiver/documentation.md) ## Prerequisites The receiver detects the database product and version on first connection and adjusts its behavior accordingly. ### Supported database versions | Product | Versions | Query plans on `db.server.top_query` | Traceparent propagation | `client.port` / `network.peer.port` | Replica status syntax | | ------- | ---------------------- | ------------------------------------ | ----------------------- | ----------------------------------- | --------------------- | | MySQL | 5.7.x | No | Yes | 0 | `SHOW SLAVE STATUS` | | MySQL | 8.0.0–8.0.21 | Yes | Yes | 0 | `SHOW SLAVE STATUS` | | MySQL | 8.0.22+ | Yes | Yes | Populated | `SHOW REPLICA STATUS` | | MySQL | 8.4.x | Yes | Yes | Populated | `SHOW REPLICA STATUS` | | MySQL | 9.x | Yes | Yes | Populated | `SHOW REPLICA STATUS` | | MariaDB | 10.5.x–10.11.x | No | Yes | 0 | `SHOW SLAVE STATUS` | | MariaDB | 11.x (LTS: 11.4, 11.8) | No | Yes | 0 | `SHOW SLAVE STATUS` | See [COMPATIBILITY.md](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/mysqlreceiver/COMPATIBILITY.md) for full details on version-gated behavior and fallbacks. Collecting most metrics requires the ability to execute `SHOW GLOBAL STATUS`. Collecting query samples requires the `performance_schema` to be enabled: ``` GRANT SELECT ON performance_schema.* TO @'%'; ``` ## Configuration The following settings are optional: * `endpoint`: (default = `localhost:3306`) * `tls`: Defines the TLS configuration to use. If `tls` is not set, the default is to disable TLS connections. * `insecure`: (default = `false`) Set this to `true` to disable TLS connections. * `insecure_skip_verify`: (default = `false`) Set this to `true` to enable TLS but not verify the certificate. * `server_name_override`: This sets the ServerName in the TLSConfig. * `username`: (default = `root`) * `password`: The password to the username. * `allow_native_passwords`: (default = `true`) * `database`: The database name. If not specified, metrics will be collected for all databases. * `collection_interval` (default = `10s`): This receiver collects metrics on an interval. This value must be a string readable by Golang's [time.ParseDuration](https://pkg.go.dev/time#ParseDuration). Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`. * `initial_delay` (default = `1s`): defines how long this receiver waits before starting. * `transport`: (default = `tcp`): Defines the network to use for connecting to the server. * `statement_events`: Additional configuration for query to build `mysql.statement_events.count` and `mysql.statement_events.wait.time` metrics: * `digest_text_limit` - maximum length of `digest_text`. Longer text will be truncated (default=`120`) * `time_limit` - maximum time from since the statements have been observed last time (default=`24h`) * `limit` - limit of records, which is maximum number of generated metrics (default=`250`) * `query_sample_collection`: Additional configuration for query sample collection(`db.server.query_sample` event): * `max_rows_per_query` - maximum number of rows to collect per scrape (default=`100`) * `top_query_collection`: Additional configuration for top queries collection (`db.server.top_query` event): * `lookback_time` (optional, example = `60`, default = `2 * collection_interval`): The time window (in seconds) in which to query for top queries. * Queries that finished execution outside the lookback window are not included in the collection. Increasing the lookback window will be useful for capturing long-running queries. * `max_query_sample_count` (optional, example = `5000`, default = `1000`): The maximum number of records to fetch in a single run. * `top_query_count`: (optional, example = `100`, default = `200`): The maximum number of active queries to report (to the next consumer) in a single run. * `collection_interval`: (optional, default = `60s`): The interval at which top queries should be emitted by this receiver. * This value can only guarantee that the top queries are collected at most once in this interval. * For instance, you have global `collection_interval` set to `10s` and `top_query_collection.collection_interval` set to `60s`. * In this case, the default receiver scraper will still run every 10 seconds. * However, the top queries collection will only run after 60 seconds have passed since the last collection. * For instance, you have global `collection_interval` set to `10s` and `top_query_collection.collection_interval` set to `5s`. * In this case, `top_query_collection.collection_interval` will have no impact on the collection frequency, which will run every 10s. * `query_plan_cache_size`: (optional, default = `1000`). The query plan cache size. Once we got query plan results from explain queries, we will store them in the cache. This defines the cache's size for query plan. * `query_plan_cache_ttl`: (optional, example = `1m`, default = `1h`). How long until a query plan expires in the cache. The receiver will run an explain query to MySQL to get the query plan after it expires. ### Example Configuration ```yaml theme={null} receivers: mysql: endpoint: localhost:3306 username: otel password: ${env:MYSQL_PASSWORD} database: otel collection_interval: 10s initial_delay: 1s statement_events: digest_text_limit: 120 time_limit: 24h limit: 250 ``` The full list of settings exposed for this receiver are documented in [config.go](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/mysqlreceiver/config.go) with detailed sample configurations in [testdata/config.yaml](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/mysqlreceiver/testdata/config.yaml). ## Metrics Details about the metrics produced by this receiver can be found in [metadata.yaml](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/mysqlreceiver/metadata.yaml) ## Logs Details about the logs produced by this receiver can be found in [documentation.md](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/mysqlreceiver/documentation.md) **Trace propagation:** Query sample log records carry a TraceID and SpanID only when a MySQL session sets the `@traceparent` user variable (W3C TraceContext format, lowercase name). The collector extracts the TraceID and SpanID from that value and stamps the application's trace context onto the corresponding log record. Log records without a `@traceparent` will have empty TraceID and SpanID fields. This allows application transactions to be correlated with query samples collected by this receiver. > **Note:** MySQL stores user variable names in lowercase in > `performance_schema.user_variables_by_thread` regardless of how the client > spelled them. The JOIN condition `VARIABLE_NAME = 'traceparent'` therefore > matches any case variation the client used (e.g. `SET @TraceParent = '...'` > works identically to `SET @traceparent = '...'`). ### Query plan availability by version EXPLAIN needs a concrete SQL statement. The normalized digest text in `events_statements_summary_by_digest` uses placeholders (`SELECT ? FROM t WHERE id = ?`), which MySQL will not execute. MySQL 8.0 added `query_sample_text` to `events_statements_summary_by_digest`. It holds an actual statement that was run for each digest, so the top-query scraper can call EXPLAIN without needing to catch the query in flight. MariaDB and MySQL 5.x do not have `query_sample_text`, so the top-query scraper has nothing to EXPLAIN. Query plans are not available for these versions. If a statement is truncated (the stored text ends with `...`), the receiver skips EXPLAIN for that statement on all versions. Truncation is controlled by [`performance_schema_max_sql_text_length`](https://dev.mysql.com/doc/refman/8.0/en/performance-schema-system-variables.html#sysvar_performance_schema_max_sql_text_length) (default 1024). Setting it to `4096` is recommended — see the requirements table below. ### MySQL Requirements to enable log collection | Parameter | Value | Description | | ---------------------------------------- | --------------------- | --------------------------------------------------- | | `performance_schema` | Enabled (Required) | Enable performance schema | | `max_digest_length` | `4096` (Recommended) | Maximum length of digest text | | `performance_schema_max_digest_length` | `4096` (Recommended) | Maximum length of digest text on performance schema | | `performance_schema_max_sql_text_length` | `4096` (Recommended) | Maximum length of sql text | ### Enabling `events_waits_current` for lock-wait duration The `mysql.events_waits_current.timer_wait` attribute on `db.server.query_sample` events is populated from `performance_schema.events_waits_current`. That consumer is **disabled by default** on all supported platforms. Without it, `timer_wait` is always `0`. #### Required privilege The database user must have `UPDATE` on `performance_schema.setup_consumers` in addition to the `SELECT` grant above: ```sql theme={null} GRANT SELECT ON performance_schema.* TO ''@'%'; GRANT UPDATE ON performance_schema.setup_consumers TO ''@'%'; ``` #### Enabling the consumer **Manual server (MySQL 5.7 / 8.x / MariaDB) — persistent across restarts** Add to `[mysqld]` in `my.cnf` / `my.ini`: ```ini theme={null} performance-schema-consumer-events-waits-current=ON ``` **AWS RDS (MySQL 5.7 / 8.x / MariaDB) — runtime only** AWS RDS does not expose `performance-schema-consumer-events-waits-current` as a parameter group setting. The consumer must be enabled at runtime and will reset on instance restart or failover: ```sql theme={null} UPDATE performance_schema.setup_consumers SET ENABLED = 'YES' WHERE NAME = 'events_waits_current'; ``` Run this statement after each restart, or grant the receiver user `UPDATE` on `performance_schema.setup_consumers` so that the receiver can re-enable it automatically on reconnect. ## Metrics | Metric Name | Description | Unit | Type | Attributes | | ------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ---- | ------------- | ------------------------------------------------------- | | ✅ `mysql.buffer_pool.data_pages` | The number of data pages in the InnoDB buffer pool. | 1 | UpDownCounter | buffer\_pool\_data | | ✅ `mysql.buffer_pool.limit` | The configured size of the InnoDB buffer pool. | By | UpDownCounter | | | ✅ `mysql.buffer_pool.operations` | The number of operations on the InnoDB buffer pool. | 1 | Counter | buffer\_pool\_operations | | ✅ `mysql.buffer_pool.page_flushes` | The number of requests to flush pages from the InnoDB buffer pool. | 1 | Counter | | | ✅ `mysql.buffer_pool.pages` | The number of pages in the InnoDB buffer pool. | 1 | UpDownCounter | buffer\_pool\_pages | | ✅ `mysql.buffer_pool.usage` | The number of bytes in the InnoDB buffer pool. | By | UpDownCounter | buffer\_pool\_data | | ❌ `mysql.client.network.io` | The number of transmitted bytes between server and clients. | By | Counter | direction | | ❌ `mysql.commands` | The number of times each type of command has been executed. | 1 | Counter | command | | ❌ `mysql.connection.count` | The number of connection attempts (successful or not) to the MySQL server. | 1 | Counter | | | ❌ `mysql.connection.errors` | Errors that occur during the client connection process. | 1 | Counter | connection\_error | | ✅ `mysql.double_writes` | The number of writes to the InnoDB doublewrite buffer. | 1 | Counter | double\_writes | | ✅ `mysql.handlers` | The number of requests to various MySQL handlers. | 1 | Counter | handler | | ✅ `mysql.index.io.wait.count` | The total count of I/O wait events for an index. | 1 | Counter | io\_waits\_operations, table\_name, schema, index\_name | | ✅ `mysql.index.io.wait.time` | The total time of I/O wait events for an index. | ns | Counter | io\_waits\_operations, table\_name, schema, index\_name | | ❌ `mysql.joins` | The number of joins that perform table scans. | 1 | Counter | join\_kind | | ✅ `mysql.locks` | The number of MySQL locks. | 1 | Counter | locks | | ✅ `mysql.log_operations` | The number of InnoDB log operations. | 1 | Counter | log\_operations | | ❌ `mysql.max_used_connections` | Maximum number of connections used simultaneously since the server started. | 1 | UpDownCounter | | | ✅ `mysql.mysqlx_connections` | The number of mysqlx connections. | 1 | Counter | connection\_status | | ❌ `mysql.mysqlx_worker_threads` | The number of worker threads available. | 1 | UpDownCounter | mysqlx\_threads | | ✅ `mysql.opened_resources` | The number of opened resources. | 1 | Counter | opened\_resources | | ✅ `mysql.operations` | The number of InnoDB operations. | 1 | Counter | operations | | ✅ `mysql.page_operations` | The number of InnoDB page operations. | 1 | Counter | page\_operations | | ❌ `mysql.page_size` | InnoDB page size. | By | UpDownCounter | | | ✅ `mysql.prepared_statements` | The number of times each type of prepared statement command has been issued. | 1 | Counter | prepared\_statements\_command | | ❌ `mysql.query.client.count` | The number of statements executed by the server. This includes only statements sent to the server by clients. | 1 | Counter | | | ❌ `mysql.query.count` | The number of statements executed by the server. | 1 | Counter | | | ❌ `mysql.query.slow.count` | The number of slow queries. | 1 | Counter | | | ❌ `mysql.replica.sql_delay` | The number of seconds that the replica must lag the source. | s | UpDownCounter | | | ❌ `mysql.replica.time_behind_source` | This field is an indication of how “late” the replica is. | s | UpDownCounter | | | ✅ `mysql.row_locks` | The number of InnoDB row locks. | 1 | Counter | row\_locks | | ✅ `mysql.row_operations` | The number of InnoDB row operations. | 1 | Counter | row\_operations | | ✅ `mysql.sorts` | The number of MySQL sorts. | 1 | Counter | sorts | | ❌ `mysql.statement_event.count` | Summary of current and recent statement events. | 1 | UpDownCounter | schema, digest, digest\_text, event\_state | | ❌ `mysql.statement_event.wait.time` | The total wait time of the summarized timed events. | ns | UpDownCounter | schema, digest, digest\_text | | ❌ `mysql.table.average_row_length` | The average row length in bytes for a given table. | By | UpDownCounter | table\_name, schema | | ✅ `mysql.table.io.wait.count` | The total count of I/O wait events for a table. | 1 | Counter | io\_waits\_operations, table\_name, schema | | ✅ `mysql.table.io.wait.time` | The total time of I/O wait events for a table. | ns | Counter | io\_waits\_operations, table\_name, schema | | ❌ `mysql.table.lock_wait.read.count` | The total table lock wait read events. | 1 | UpDownCounter | schema, table\_name, read\_lock\_type | | ❌ `mysql.table.lock_wait.read.time` | The total table lock wait read events times. | ns | UpDownCounter | schema, table\_name, read\_lock\_type | | ❌ `mysql.table.lock_wait.write.count` | The total table lock wait write events. | 1 | UpDownCounter | schema, table\_name, write\_lock\_type | | ❌ `mysql.table.lock_wait.write.time` | The total table lock wait write events times. | ns | UpDownCounter | schema, table\_name, write\_lock\_type | | ❌ `mysql.table.rows` | The number of rows for a given table. | 1 | UpDownCounter | table\_name, schema | | ❌ `mysql.table.size` | The table size in bytes for a given table. | By | UpDownCounter | table\_name, schema, table\_size\_type | | ❌ `mysql.table_open_cache` | The number of hits, misses or overflows for open tables cache lookups. | 1 | Counter | cache\_status | | ✅ `mysql.threads` | The state of MySQL threads. | 1 | UpDownCounter | threads | | ✅ `mysql.tmp_resources` | The number of created temporary resources. | 1 | Counter | tmp\_resource | | ✅ `mysql.uptime` | The number of seconds that the server has been up. | s | Counter | | ## Attributes | Attribute Name | Description | Type | Values | | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `status` | The status of buffer pool data. | string | `dirty`, `clean` | | `operation` | The buffer pool operations types. | string | `read_ahead_rnd`, `read_ahead`, `read_ahead_evicted`, `read_requests`, `reads`, `wait_free`, `write_requests` | | `kind` | The buffer pool pages types. | string | `data`, `free`, `misc`, `total` | | `status` | The status of cache access. | string | `hit`, `miss`, `overflow` | | `client.address` | Hostname or address of the client. | string | | | `client.port` | TCP port used by the client. | int | | | `command` | The command types. | string | `delete`, `delete_multi`, `insert`, `select`, `update`, `update_multi` | | `error` | The connection error type. | string | `accept`, `internal`, `max_connections`, `peer_address`, `select`, `tcpwrap`, `aborted`, `aborted_clients`, `locked` | | `status` | The connection status. | string | `accepted`, `closed`, `rejected` | | `db.namespace` | The default database for the thread, or empty if none has been selected (originally processlist\_db). | string | | | `db.query.text` | The SQL statement text for the event. | string | | | `db.system.name` | The name of the database system. | string | `mysql` | | `digest` | Digest. | string | | | `digest_text` | Text before digestion. | string | | | `kind` | The name of the transmission direction. | string | `received`, `sent` | | `kind` | The doublewrite types. | string | `pages_written`, `writes` | | `kind` | Possible event states. | string | `errors`, `warnings`, `rows_affected`, `rows_sent`, `rows_examined`, `created_tmp_disk_tables`, `created_tmp_tables`, `sort_merge_passes`, `sort_rows`, `no_index_used` | | `kind` | The handler types. | string | `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` | | `index` | The name of the index. | string | | | `operation` | The io\_waits operation type. | string | `delete`, `fetch`, `insert`, `update` | | `kind` | The kind of join. | string | `full`, `full_range`, `range`, `range_check`, `scan` | | `kind` | The table locks type. | string | `immediate`, `waited` | | `operation` | The log operation types. 'fsyncs' aren't available in MariaDB 10.8 or later. | string | `waits`, `write_requests`, `writes`, `fsyncs` | | `mysql.event_id` | The thread associated with the event and the thread current event number when the event starts. | int | | | `mysql.events_statements_current.digest` | The statement digest SHA-256 value as a string of 64 hexadecimal characters, or empty if the statements\_digest consumer is no. | string | | | `mysql.events_statements_current.timer_wait` | Elapsed time the current statement has been executing, in seconds. | double | | | `mysql.events_statements_summary_by_digest.count_star` | The number of times the statement was executed, report in delta value. | int | | | `mysql.events_statements_summary_by_digest.digest` | The statement digest SHA-256 value as a string of 64 hexadecimal characters, or empty if the statements\_digest consumer is no. | string | | | `mysql.events_statements_summary_by_digest.sum_timer_wait` | The total time spent executing the statement, report in delta seconds. | double | | | `mysql.events_waits_current.timer_wait` | Timing information for the event, indicating elapsed time the event waited in seconds. | double | | | `mysql.query_plan` | The query plan for the statement, if available. | string | | | `mysql.query_plan.hash` | This attribute is set to the same value as mysql.events\_statements\_summary\_by\_digest.digest (query digest) by design. | string | | | `mysql.session.id` | The unique identifier for the session associated with the event. | int | | | `mysql.session.status` | Simplified session status, either 'waiting', 'running' or 'other'. | string | | | `mysql.threads.processlist_command` | The type of command the thread is executing on behalf of the client for foreground threads, or `Sleep` if the session is idle. | string | | | `mysql.threads.processlist_state` | An action, event, or state that indicates what the thread is doing. | string | | | `mysql.threads.thread_id` | The unique identifier for the thread executing the statement. | int | | | `mysql.wait_type` | The name of the instrument that produced the event. | string | | | `kind` | The worker thread count kind. | string | `available`, `active` | | `network.peer.address` | IP address of the peer client. | string | | | `network.peer.port` | TCP port used by the peer client. | int | | | `kind` | The kind of the resource. | string | `file`, `table_definition`, `table` | | `operation` | The operation types. | string | `fsyncs`, `reads`, `writes` | | `operation` | The page operation types. | string | `created`, `read`, `written` | | `command` | The prepare statement command types. | string | `execute`, `close`, `fetch`, `prepare`, `reset`, `send_long_data` | | `kind` | Read operation types. | string | `normal`, `with_shared_locks`, `high_priority`, `no_insert`, `external` | | `kind` | The row lock type. | string | `waits`, `time` | | `operation` | The row operation type. | string | `deleted`, `inserted`, `read`, `updated` | | `schema` | The schema of the object. | string | | | `kind` | The sort count type. | string | `merge_passes`, `range`, `rows`, `scan` | | `table` | Table name for event or process. | string | | | `kind` | The table size types. | string | `data`, `index` | | `kind` | The thread count type. | string | `cached`, `connected`, `created`, `running` | | `resource` | The kind of temporary resources. | string | `disk_tables`, `files`, `tables` | | `user.name` | The user associated with a foreground thread, empty for a background thread (originally processlist\_user). | string | | | `kind` | Write operation types. | string | `allow_write`, `concurrent_insert`, `low_priority`, `normal`, `external` | ## Resource Attributes | Attribute Name | Description | Type | Enabled | | ------------------------- | ------------------------------- | ------ | ------- | | `mysql.instance.endpoint` | Endpoint of the MySQL instance. | string | ✅ | ## Configuration ### Example Configuration ```yaml theme={null} mysql: endpoint: localhost:3306 username: otel password: ${env:MYSQL_PASSWORD} database: otel collection_interval: 10s mysql/default_tls: endpoint: localhost:3306 username: otel password: ${env:MYSQL_PASSWORD} database: otel collection_interval: 10s tls: # specified, but use default values server_name_override: localhost ``` *** *Last generated: 2026-07-06*