mysqlreceiver

README

MySQL Receiver

Status
Stability	development: logs
	beta: metrics
Distributions	contrib
Issues
Code coverage
Code Owners	@antonblock, @ishleenk17 | Seeking more code owners!
Emeritus	@djaglowski

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

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 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 <your-user>@'%';

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

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 with detailed sample configurations in testdata/config.yaml.

Metrics

Details about the metrics produced by this receiver can be found in metadata.yaml

Logs

Details about the logs produced by this receiver can be found in 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 (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:

GRANT SELECT ON performance_schema.* TO '<your-user>'@'%';
GRANT UPDATE ON performance_schema.setup_consumers TO '<your-user>'@'%';

Enabling the consumer

Manual server (MySQL 5.7 / 8.x / MariaDB) — persistent across restarts

Add to [mysqld] in my.cnf / my.ini:

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:

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.

Documentation

Index

• func NewFactory() receiver.Factory
• type Config
  • func (cfg *Config) Unmarshal(componentParser *confmap.Conf) error
• type QuerySampleCollection
• type StatementEventsConfig
• type TopQueryCollection

Functions

func NewFactory

func NewFactory() receiver.Factory

Types

type Config

type Config struct {
	scraperhelper.ControllerConfig `mapstructure:",squash"`
	Username                       string              `mapstructure:"username,omitempty"`
	Password                       configopaque.String `mapstructure:"password,omitempty"`
	Database                       string              `mapstructure:"database,omitempty"`
	AllowNativePasswords           bool                `mapstructure:"allow_native_passwords,omitempty"`
	confignet.AddrConfig           `mapstructure:",squash"`
	TLS                            configtls.ClientConfig        `mapstructure:"tls,omitempty"`
	MetricsBuilderConfig           metadata.MetricsBuilderConfig `mapstructure:",squash"`
	LogsBuilderConfig              metadata.LogsBuilderConfig    `mapstructure:",squash"`
	StatementEvents                StatementEventsConfig         `mapstructure:"statement_events"`
	TopQueryCollection             TopQueryCollection            `mapstructure:"top_query_collection"`
	QuerySampleCollection          QuerySampleCollection         `mapstructure:"query_sample_collection"`
}

func (*Config) Unmarshal

func (cfg *Config) Unmarshal(componentParser *confmap.Conf) error

type QuerySampleCollection

type QuerySampleCollection struct {
	MaxRowsPerQuery uint64 `mapstructure:"max_rows_per_query"`
	// contains filtered or unexported fields
}

type StatementEventsConfig

type StatementEventsConfig struct {
	DigestTextLimit int           `mapstructure:"digest_text_limit"`
	Limit           int           `mapstructure:"limit"`
	TimeLimit       time.Duration `mapstructure:"time_limit"`
}

type TopQueryCollection

type TopQueryCollection struct {
	LookbackTime        uint64        `mapstructure:"lookback_time"`
	MaxQuerySampleCount uint64        `mapstructure:"max_query_sample_count"`
	TopQueryCount       uint64        `mapstructure:"top_query_count"`
	CollectionInterval  time.Duration `mapstructure:"collection_interval"`
	QueryPlanCacheSize  int           `mapstructure:"query_plan_cache_size"`
	QueryPlanCacheTTL   time.Duration `mapstructure:"query_plan_cache_ttl"`
	// contains filtered or unexported fields
}