Monitor MySQL with OpenTelemetry

Osuite monitors MySQL through the OpenTelemetry Collector’s mysql receiver, which reads the server’s global status counters and InnoDB statistics and exports them over OTLP. Because the metrics carry the same resource attributes as your services, buffer-pool pressure or lock contention lines up with the application traffic that caused it.

Note

The mysql receiver ships in the Collector contrib distribution. Use otelcol-contrib (or any build that includes it), not the core otelcol binary.

Setup

Prerequisites

• A reachable MySQL server (5.7 or later; MariaDB works with the same protocol).
• A monitoring user with permission to read global status and the performance schema.

CREATE USER 'otel'@'%' IDENTIFIED BY 'a-strong-password';
GRANT PROCESS ON *.* TO 'otel'@'%';
GRANT SELECT ON performance_schema.* TO 'otel'@'%';

Export the password to the Collector’s environment:

export MYSQL_PASSWORD='a-strong-password'

Configure the Collector

1. Add the mysql receiver, the otlp/osuite exporter, and a metrics pipeline. Pick the tab that matches where your Collector runs — only the receiver endpoint changes.

   Bare host

   receivers:
     mysql:
       endpoint: localhost:3306
       username: otel
       password: ${env:MYSQL_PASSWORD}
       database: mydb
       collection_interval: 30s
   
   processors:
     batch:
     resourcedetection:
   
   exporters:
     otlp/osuite:
       endpoint: ingest.<region>.osuite.io:443
       headers:
         x-osuite-ingest-token: <your-ingest-token>
   
   service:
     pipelines:
       metrics:
         receivers: [mysql]
         processors: [batch, resourcedetection]
         exporters: [otlp/osuite]

   Docker

   receivers:
     mysql:
       endpoint: mysql:3306
       username: otel
       password: ${env:MYSQL_PASSWORD}
       database: mydb
       collection_interval: 30s
   
   processors:
     batch:
     resourcedetection:
   
   exporters:
     otlp/osuite:
       endpoint: ingest.<region>.osuite.io:443
       headers:
         x-osuite-ingest-token: <your-ingest-token>
   
   service:
     pipelines:
       metrics:
         receivers: [mysql]
         processors: [batch, resourcedetection]
         exporters: [otlp/osuite]

   Kubernetes

   receivers:
     mysql:
       endpoint: mysql.default.svc.cluster.local:3306
       username: otel
       password: ${env:MYSQL_PASSWORD}
       database: mydb
       collection_interval: 30s
   
   processors:
     batch:
     resourcedetection:
   
   exporters:
     otlp/osuite:
       endpoint: ingest.<region>.osuite.io:443
       headers:
         x-osuite-ingest-token: <your-ingest-token>
   
   service:
     pipelines:
       metrics:
         receivers: [mysql]
         processors: [batch, resourcedetection]
         exporters: [otlp/osuite]

2. Start the Collector. On Docker and Kubernetes, the Collector and MySQL must share a network so the endpoint resolves.

Validate

What you should see

Metrics named mysql.* appear in Dashboards → Explore metrics within a minute, tagged with the host or pod the Collector runs on.

Data collected

Metric	Description	Unit
mysql.buffer_pool.usage	Bytes in the InnoDB buffer pool	By
mysql.buffer_pool.limit	Configured buffer-pool size	By
mysql.buffer_pool.operations	Operations on the InnoDB buffer pool	1
mysql.buffer_pool.data_pages	Data pages in the buffer pool	1
mysql.operations	InnoDB operations	1
mysql.row_operations	InnoDB row operations	1
mysql.handlers	Requests to MySQL handlers	1
mysql.locks	MySQL locks	1
mysql.log_operations	InnoDB log operations	1
mysql.double_writes	Writes to the InnoDB doublewrite buffer	1

Enable per-command counts, thread and connection metrics, and query slow-log statistics with the receiver’s optional metric toggles when you need them.

Dashboards and alerts

Once metrics arrive, build a MySQL dashboard in the dashboard builder from the series above. Alerts in Osuite are PromQL-based — see Alerts. Useful starting conditions: a falling buffer-pool hit ratio (mysql.buffer_pool.operations), rising lock counts (mysql.locks), and sustained high row-operation rates.

Troubleshooting

• Access denied — confirm the otel user has both PROCESS and SELECT on performance_schema, and that its host mask ('%') covers the Collector’s source address.
• Missing metrics — confirm performance_schema is enabled on the server (SHOW VARIABLES LIKE 'performance_schema').

No data in Osuite after a few minutes? Work through these checks.

• Endpoint — confirm the exporter targets exactly ingest.<region>.osuite.io:443 for your region, over TLS.
• Token — confirm the ingest header carries a valid <your-ingest-token> and has not been rotated.
• Pipeline — confirm the signal you expect (traces, logs, or metrics) is wired into an active pipeline with the otlp/osuite exporter attached.
• Export errors — check the application or Collector logs for OTLP export failures (auth, DNS, TLS, connection refused).
• Network — confirm the host has outbound access to the ingest endpoint on port 443.
• Timing — allow up to a minute for the first data to appear before assuming a failure.

Still stuck? Ask the Investigation Agent or contact support.