MySQL receiver

This receiver queries MySQL's global status and InnoDB tables.

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

MySQL support starts from these minimum collector versions:

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

Supported versions and platforms

Splunk Database Monitoring supports these MySQL versions and platforms:

  • Versions: MySQL version 8.0+
  • Platforms: AWS RDS, standalone

Prerequisites

  1. Enable performance schema:

    AWS RDS

    1. On the AWS console, navigate to Aurora and RDS > Parameter groups > Edit parameter group. In your MySQL paramater 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 MySQL connections are allowed

    2. Save the parameter group.

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

    4. Restart the MySQL 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 SQL session.

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

    Standalone

    1. Update my.cnf or mysqld.cnf:

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

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

    These commands are the same on both AWS RDS and standalone platforms:

    Note: SELECT ON performance_schema.* is required for top query and query sample collection.
    SQL 
    CREATE USER 'otel-user'@'%' IDENTIFIED BY 'otel-user-password';

-- Required for MySQL receiver metrics/query collection
GRANT REPLICATION CLIENT ON *.* TO 'otel-user'@'%';

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

FLUSH PRIVILEGES;

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