MySQL OpenTelemetry Assets

This package allows you to monitor MySQL, an open-source Relational Database Management System (RDBMS) that enables users to store, manage, and retrieve structured data efficiently.

The MySQL OpenTelemetry assets provide a visual representation of MySQL metrics and logs collected using the OpenTelemetry MySQL receiver, enabling you to monitor database performance and troubleshoot issues effectively in real time.

The MySQL OpenTelemetry assets have been tested with OpenTelemetry MySQL receiver v0.145.0.

Databases tested against:

• MySQL 8.0, 9.4
• MariaDB 10.11, 11.8

You need Elasticsearch for storing and searching your data and Kibana for visualizing and managing it. You can use our hosted Elasticsearch Service on Elastic Cloud, which is recommended, or self-manage the Elastic Stack on your own hardware.

The MySQL user configured for monitoring requires the following permissions:

Primary instance:

-- SHOW GLOBAL STATUS visibility and query sample access to information_schema.processlist
GRANT PROCESS ON *.* TO '<MYSQL_USER>'@'%';

-- Query samples, top queries, statement events (performance_schema access)
GRANT SELECT ON performance_schema.* TO '<MYSQL_USER>'@'%';

-- Table statistics (mysql.table.size, mysql.table.rows) and EXPLAIN for top query plans
GRANT SELECT ON <your_database>.* TO '<MYSQL_USER>'@'%';

Replica instance (for replication metrics):

-- mysql.replica.time_behind_source, mysql.replica.sql_delay
-- Works on both MySQL and MariaDB (MariaDB 10.5+ remaps this to BINLOG MONITOR)
GRANT REPLICATION CLIENT ON *.* TO '<MYSQL_USER>'@'%';

Performance Schema consumers:

The dashboards rely on the following Performance Schema consumers. Ensure they are enabled:

• statements_digest (ON by default) — required for top queries and statement events
• events_statements_current (ON by default) — required for query samples
• events_waits_current (OFF by default) — required for wait event details in query samples

Verify they are enabled:

SELECT NAME, ENABLED FROM performance_schema.setup_consumers
WHERE NAME IN ('statements_digest', 'events_statements_current', 'events_waits_current');

Install and configure the upstream OpenTelemetry Collector or Elastic Distribution of OpenTelemetry (EDOT) Collector to export metrics to Elasticsearch. The configuration below uses separate receivers for primary and replica instances because replication metrics are only available on replicas.

Replace the following placeholders in the configuration:

• <MYSQL_PRIMARY_ENDPOINT>: MySQL primary instance endpoint (format: host:port, for example, localhost:3306 or mysql-primary.example.com:3306)
• <MYSQL_REPLICA_ENDPOINT>: MySQL replica instance endpoint (format: host:port, for example, mysql-replica.example.com:3306)
• <MYSQL_USER>: MySQL username configured with required permissions
• <MYSQL_PASSWORD>: MySQL user password
• <ES_ENDPOINT>: Elasticsearch endpoint (for example, https://elasticsearch.example.com:9200)
• <ES_API_KEY>: Elasticsearch API key for authentication

receivers:
  mysql/primary:
    endpoint: <MYSQL_PRIMARY_ENDPOINT>
    username: <MYSQL_USER>
    password: <MYSQL_PASSWORD>
    collection_interval: 10s
    statement_events:
      digest_text_limit: 120
      time_limit: 24h
      limit: 250
    query_sample_collection:
      max_rows_per_query: 100
    top_query_collection:
      collection_interval: 30s
      lookback_time: 60
      max_query_sample_count: 1000
      top_query_count: 100
    events:
      db.server.query_sample:
        enabled: true
      db.server.top_query:
        enabled: true
    metrics:
      mysql.client.network.io:
        enabled: true
      mysql.connection.errors:
        enabled: true
      mysql.max_used_connections:
        enabled: true
      mysql.query.client.count:
        enabled: true
      mysql.query.count:
        enabled: true
      mysql.query.slow.count:
        enabled: true
      mysql.table.rows:
        enabled: true
      mysql.table.size:
        enabled: true

  mysql/replica:
    endpoint: <MYSQL_REPLICA_ENDPOINT>
    username: <MYSQL_USER>
    password: <MYSQL_PASSWORD>
    collection_interval: 10s
    metrics:
      mysql.replica.time_behind_source:
        enabled: true
      mysql.replica.sql_delay:
        enabled: true

exporters:
  elasticsearch/otel:
    endpoint: <ES_ENDPOINT>
    api_key: <ES_API_KEY>
    mapping:
      mode: otel

service:
  pipelines:
    metrics:
      receivers: [mysql/primary, mysql/replica]
      exporters: [elasticsearch/otel]
    logs:
      receivers: [mysql/primary]
      exporters: [elasticsearch/otel]

Refer to the metadata.yaml of the OpenTelemetry MySQL receiver for details on available metrics.

Refer to the documentation.md of the OpenTelemetry MySQL receiver for details on log events (db.server.query_sample and db.server.top_query) and their attributes.

This integration includes one or more Kibana dashboards that visualizes the data collected by the integration. The screenshots below illustrate how the ingested data is displayed.