MySQL receiver

This receiver queries MySQL and MariaDB global status and InnoDB tables.

The MySQL receiver is a component of the OpenTelemetry Collector. It connects to a MySQL or MariaDB instance and supports metrics and logs pipelines.

MySQL and MariaDB support starts from these minimum collector versions:

  • Splunk Distribution of the OpenTelemetry Collector (splunk-otel-collector) v0.154.0 or later
  • Community (OSS) version of the OpenTelemetry Collector (opentelemetry-collector-contrib) v0.154.0 or later

Supported versions and platforms

Splunk Database Monitoring supports these MySQL and MariaDB versions and platforms:

  • MySQL versions: 5.7+
  • MariaDB versions: 10.5+
  • Platforms: AWS RDS, standalone

Prerequisites

  1. Enable performance schema for MySQL and MariaDB:

    AWS RDS

    1. On the AWS console, navigate to Aurora and RDS > Parameter groups > Edit parameter group. In your MySQL or MariaDB parameter group, change these values:

      • performance_schema: 1

      • max_digest_length: 4096

      • performance_schema_max_digest_length: 4096

      • performance_schema_max_sql_text_length: 4096

      • (Optional) require_secure_transport: 0 only if non-TLS connections are allowed

    2. Save the parameter group.

    3. Attach the parameter group to the database instance if it isn't already attached.

    4. Restart the database instance.

    5. (Optional) Verify:

      SQL 
      SHOW VARIABLES LIKE 'performance_schema';
SHOW VARIABLES LIKE 'max_digest_length';
SHOW VARIABLES LIKE 'performance_schema_max_digest_length';
SHOW VARIABLES LIKE 'performance_schema_max_sql_text_length';
    Note:

    • performance_schema = 1 is mandatory.

    • Splunk strongly recommends the 4096 values for some settings above to reduce query text truncation.

    • require_secure_transport is optional and depends on your TLS policy.

    • RDS parameter group values must be changed from the AWS Console, AWS CLI, Terraform, or API; not from a normal MySQL or MariaDB SQL session.

    • User creation and grants can still be done from any database client connected to the RDS instance.

    Note:

    These parameter group settings apply to both AWS RDS for MySQL and AWS RDS for MariaDB. MariaDB supports performance_schema_max_sql_text_length and performance_schema_max_digest_length from version 10.5.2 onward. All MariaDB versions available on AWS RDS support these settings.

    Standalone

    1. Update my.cnf or mysqld.cnf. MariaDB also uses my.cnf with the same [mysqld] section:

      SQL 
      [mysqld]
performance_schema=ON
max_digest_length=4096
performance_schema_max_digest_length=4096
performance_schema_max_sql_text_length=4096

      In this section, add require_secure_transport=OFF only if TLS isn't enabled.

    2. Restart the database instance.

    3. (Optional) Verify:

      SQL 
      SHOW VARIABLES LIKE 'performance_schema';
SHOW VARIABLES LIKE 'max_digest_length';
SHOW VARIABLES LIKE 'performance_schema_max_digest_length';
SHOW VARIABLES LIKE 'performance_schema_max_sql_text_length';
SHOW GRANTS FOR 'username'@'%';
    Note:

    • performance_schema=ON is mandatory.

    • The 4096 settings are strongly recommended.

    • require_secure_transport=OFF is optional. Keep it enabled if TLS is required and configure the receiver accordingly.

    Note:

    MariaDB uses the same configuration file format and [mysqld] section as MySQL. On MariaDB installations, the configuration file is typically located at /etc/mysql/my.cnf, /etc/my.cnf, or under /etc/mysql/mariadb.conf.d/. The same parameter names and values apply.

  2. Create a database user for the receiver to use.

    These commands apply to both AWS RDS and standalone platforms.

    Use these privileges to configure the receiver user:

    Privilege Required for Applies to
    REPLICATION CLIENT Replica status monitoring with SHOW SLAVE STATUS or SHOW REPLICA STATUS MySQL
    SLAVE MONITOR Replica status monitoring with SHOW SLAVE STATUS MariaDB 10.5.9+ (use instead of REPLICATION CLIENT)
    PROCESS InnoDB buffer pool metrics collection MySQL and MariaDB
    SELECT ON performance_schema.* Query sample and top query collection MySQL and MariaDB
    SELECT ON schema-name.* EXPLAIN plan collection for queries in that schema MySQL and MariaDB
  3. Run these commands:
    MySQL
    SQL 
    CREATE USER 'otel-user'@'%' IDENTIFIED BY 'otel-user-password';

-- Required for replica status monitoring
GRANT REPLICATION CLIENT ON *.* TO 'otel-user'@'%';

-- Required for InnoDB metrics collection
GRANT PROCESS ON *.* TO 'otel-user'@'%';

-- Required for performance-related metadata and query collection
GRANT SELECT ON performance_schema.* TO 'otel-user'@'%';

FLUSH PRIVILEGES;
    MariaDB
    SQL 
    CREATE USER 'otel-user'@'%' IDENTIFIED BY 'otel-user-password';

-- Required for replica status monitoring
GRANT SLAVE MONITOR ON *.* TO 'otel-user'@'%';

-- Required for InnoDB metrics collection
GRANT PROCESS ON *.* TO 'otel-user'@'%';

-- Required for performance-related metadata and query collection
GRANT SELECT ON performance_schema.* TO 'otel-user'@'%';

FLUSH PRIVILEGES;
    Note:

    Starting with MariaDB 10.5.2, the REPLICATION CLIENT privilege was renamed to BINLOG MONITOR and the privilege required for SHOW SLAVE STATUS changed. From MariaDB 10.5.9 onward, use SLAVE MONITOR, also known as REPLICA MONITOR, for replica status monitoring. If you upgrade from an older MariaDB version, existing REPLICATION CLIENT grants are automatically mapped to the new privilege names.

    Note:

    On AWS RDS, you can grant EXECUTE on mysql.rds_version to suppress collector log warnings.

    SQL 
    GRANT EXECUTE ON PROCEDURE mysql.rds_version TO 'otel-user'@'%';

  4. Grant the user you created SELECT access to some or all schemas:

    Note: The MySQL receiver depends on schema-level SELECT privileges to retrieve EXPLAIN plans. If you don't grant access to a schema, queries from that schema may still appear in the UI, but their corresponding EXPLAIN plans will not be visible.
    Grant access to all schemas

    This option grants SELECT access across all schemas. It is the simplest configuration and ensures that EXPLAIN plans for top queries are consistently available in the UI without additional configuration.

    SQL 
    GRANT SELECT ON *.* TO 'otel-user'@'%';
    Grant access to specific schemas (least privilege)

    This option limits SELECT access to only the specified schemas. It is recommended for environments with strict access controls.

    SQL 
    GRANT SELECT ON `schema-name`.* TO 'otel-user'@'%';

Configure the receiver

Modify your collector configuration file as follows. All examples are for the Splunk Distribution of the OpenTelemetry Collector.

  1. In the receivers: section, add mysql:

    YAML 
    mysql:
  collection_interval: 10s
  endpoint: host:port
  username: otel-user
  password: otel-user-password
  events:
    db.server.query_sample:
      enabled: true
    db.server.top_query:
      enabled: true
  resource_attributes:
    mysql.instance.endpoint:
      enabled: true
    Important:

    If you're using the Splunk Distribution of OpenTelemetry Collector, leave the following receiver settings at their default values:

    • collection_interval (Default: 10s)

    • query_sample_collection.max_rows_per_query (Default: 100)

    • top_query_collection.collection_interval (Default: 60s)

    • top_query_collection.max_query_sample_count (Default: 1000)

    These values support Database Monitoring without affecting the performance of the database or the collector. If you increase these values you might adversely affect the performance of your database or collector, and this could result in ingest throttling.

  2. In the processors: section, add this:

    YAML 
    resource/mysql_service_instance_id:
  attributes:
    - action: insert
      from_attribute: mysql.instance.endpoint
      key: service.instance.id

  3. In the exporters: section, add otlp_http/dbmon:

    YAML 
    otlp_http/dbmon:
  headers:
    X-SF-Token: your-splunk-access-token
    X-splunk-instrumentation-library: dbmon
  logs_endpoint: https://ingest.your-splunk-realm./v3/event
  sending_queue:
    batch:
      flush_timeout: 15s
      max_size: 10485760
      sizer: bytes

  4. In the service.pipelines: section, create a metrics pipeline named metrics/dbmon and a logs pipeline named logs/dbmon:

    YAML 
    metrics/dbmon:
  receivers:
    - mysql
  processors:
    - memory_limiter
    - batch
    - resourcedetection
    - resource/mysql_service_instance_id
  exporters:
    - signalfx
logs/dbmon:
  receivers:
    - mysql
  processors:
    - memory_limiter
    - batch
    - resource/mysql_service_instance_id
  exporters:
    - otlp_http/dbmon

  5. Restart the collector to apply your configuration changes.

    The restart command varies depending on what platform you deployed the collector on and what tool you used to deploy it. Here are general examples of the restart command:

    Linux

    Linux with installer script:

    BASH 
    sudo systemctl restart splunk-otel-collector
    Windows

    Windows with installer script:

    BASH 
    stop-service splunk-otel-collector
start-service splunk-otel-collector
    Kubernetes

    Kubernetes with Helm:

    BASH 
    helm upgrade your-splunk-otel-collector splunk-otel-collector-chart/splunk-otel-collector -f your-override-values.yaml

    where splunk-otel-collector-chart is the name you gave to the Helm chart in the helm repo add command.

Your database instance should now be visible on APM > Database monitoring as well as on Infrastructure > Infrastructure monitoring if you have a Database Monitoring license. For troubleshooting, see Troubleshoot data collection .

Advanced configurations

Collect data from multiple MySQL or MariaDB instances

Omit the database name parameter, receivers.mysql.database. If omitted, the receiver will monitor all databases in the configured instance.

Enable optional metrics

Set metrics.metric-name.enabled to true. For example, for the optional metrics mysql.commands, mysql.connection.count, and mysql.connection.errors:

YAML 
mysql/extra_metrics:
  endpoint: host:port
  username: otel-user
  password: ${env:MYSQL_PASSWORD}
  database: mysql-database-name
  collection_interval: 10s
  mysql.commands:
    enabled: true
  mysql.connection.count:
    enabled: true
  mysql.connection.errors:
    enabled: true
TLS

Set these parameters at a minimum:

YAML 
mysql/default_tls:
  endpoint: host:port
  username: otel-user
  password: ${env:MYSQL_PASSWORD}
  database: mysql-database-name
  collection_interval: 10s
  tls:
    server_name_override: localhost

Set up APM correlation

See Correlate database queries with Splunk APM traces.

Settings reference

Configuration options for this receiver:

included

https://raw.githubusercontent.com/splunk/collector-config-tools/main/cfg-metadata/receiver/mysql.yaml

Metrics reference

Metrics, attributes, and resource attributes reported by this receiver:

included

https://raw.githubusercontent.com/splunk/collector-config-tools/main/metric-metadata/mysqlreceiver.yaml