Troubleshooting MySQL NRDOT monitoring

Preview

We're still working on this feature, but we'd love for you to try it out!

This feature is currently provided as part of a preview pursuant to our pre-release policies.

Troubleshoot common issues you may encounter when monitoring your MySQL with the NRDOT Collector.

Test connectivity

Test network connectivity to MySQL

First confirm the port is reachable at all:

bash

$nc -zv <YOUR_DB_HOST> <YOUR_DB_PORT>

Then confirm the monitoring user can actually authenticate and query:

bash

$mysql -h <YOUR_DB_HOST> -P <YOUR_DB_PORT> -u <YOUR_DB_USERNAME> -p -e "SELECT 1;"

If the command completes without an error, the monitoring user, host, and port are all correct.

Test OTLP endpoint connectivity

Run the following to verify your host can reach the selected New Relic OTLP endpoint:

bash

$ENDPOINT="<YOUR_NEWRELIC_OTLP_ENDPOINT>"
$HOST=$(echo "$ENDPOINT" | sed 's|https://||' | cut -d: -f1)
$PORT=$(echo "$ENDPOINT" | awk -F: '{print $NF}')
$(timeout 2 bash -c "</dev/tcp/$HOST/$PORT" && echo "SUCCESS") || echo "FAILED"

Expected output: SUCCESS

Common issues

Symptoms: Missing query sample and top query log events in New Relic.

Possible causes:

performance_schema disabled
Query events not enabled in receiver configuration
Insufficient database privileges

Solutions:

Verify Performance Schema is enabled:
```
SHOW VARIABLES LIKE 'performance_schema';
```
The value should be ON.

Check receiver configuration:

events:
  db.server.query_sample:
    enabled: true
  db.server.top_query:
    enabled: true

Verify database privileges:
```
SHOW GRANTS FOR '<YOUR_DB_USERNAME>'@'%';
```
Should include SELECT on performance_schema.*.

Symptoms: Lock wait duration metrics always show 0 seconds.

Cause: The events_waits_current Performance Schema consumer is disabled.

Solutions:

For self-managed MySQL database: Add to my.cnf/my.ini:

[mysqld]
performance-schema-consumer-events-waits-current=ON

Then restart MySQL.

For AWS RDS:

UPDATE performance_schema.setup_consumers 
SET ENABLED='YES' 
WHERE NAME='events_waits_current';

Important

On RDS, this setting doesn't persist across restarts. Grant the monitoring user UPDATE privileges on performance_schema.setup_consumers so the collector can re-enable it automatically.

Symptoms: mysql.query_plan is empty for some queries, particularly longer ones.

Cause: Statement text is truncated by MySQL's digest length limits, causing the receiver to skip EXPLAIN.

Solution: Increase MySQL server parameters:

SET GLOBAL max_digest_length = 4096;
SET GLOBAL performance_schema_max_digest_length = 4096;
SET GLOBAL performance_schema_max_sql_text_length = 4096;

Add to my.cnf to make permanent:

[mysqld]
max_digest_length = 4096
performance_schema_max_digest_length = 4096
performance_schema_max_sql_text_length = 4096

Symptoms: Query plans missing for UPDATE, INSERT, DELETE, or REPLACE statements.

Cause: Monitoring user lacks DML privileges and explain_mode is set to inline.

Solution: Switch to procedure mode in your receiver configuration:

nrmysql:
  explain_mode: procedure

This uses a SQL SECURITY DEFINER procedure to explain write statements without granting DML privileges to the monitoring user.

Symptoms: APM correlation tags are not being extracted from SQL comments.

Cause: Comment tag extraction is not configured.

Solution: Add allowed_comment_keys to both collection blocks in your configuration:

query_sample_collection:
  allowed_comment_keys: [nr_service_guid]
top_query_collection:
  allowed_comment_keys: [nr_service_guid]

Comment tag extraction is empty by default for security reasons.

Symptoms:

MySQL entity missing from Entity Explorer
APM application doesn't show database relationships

Cause: Missing server.address and server.port resource attributes required for entity synthesis.

Solution: Add a resource processor to your collector configuration:

processors:
  resource/mysql:
    attributes:
      - key: server.address
        value: "<YOUR_DB_HOST>"
        action: upsert
      - key: server.port
        value: <YOUR_DB_PORT>
        action: upsert

service:
  pipelines:
    metrics:
      receivers: [nrmysql]
      processors: [resource/mysql, batch]
      exporters: [otlp/newrelic]
    logs:
      receivers: [nrmysql]
      processors: [resource/mysql, batch]
      exporters: [otlp/newrelic]

Symptoms:

"Connection refused" errors
"Access denied" authentication failures

Solutions:

For connection refused:

Verify MySQL is running:
bash
```
$systemctl status mysql
```
Check firewall rules allow connections on MySQL port (default 3306)
Verify bind-address in MySQL configuration allows external connections

For authentication errors:

Verify user exists and has correct privileges:

SELECT User, Host FROM mysql.user WHERE User='<YOUR_DB_USERNAME>';
SHOW GRANTS FOR '<YOUR_DB_USERNAME>'@'%';

Check password is correct
For RDS, ensure security group allows inbound connections

RDS Performance Schema consumer resets: The events_waits_current consumer automatically disables on RDS restart/failover. Grant UPDATE privileges on performance_schema.setup_consumers so the collector can re-enable it:

GRANT UPDATE ON performance_schema.setup_consumers TO '<YOUR_DB_USERNAME>'@'%';

RDS network security: Ensure your RDS security group allows inbound traffic on port 3306 from the NRDOT Collector's IP address or security group.

Symptoms: The collector fails to connect, with a certificate or TLS-related error.

Cause: RDS enforces TLS. The collector doesn't trust Amazon's RDS CA by default.

Solution: Set tls.ca_file (or tls.ca_pem) to the Amazon RDS certificate bundle, and leave tls.insecure/tls.insecure_skip_verify at false:

nrmysql:
  tls:
    insecure: false
    insecure_skip_verify: false
    ca_file: /path/to/global-bundle.pem

NRQL query examples

Use these NRQL queries to troubleshoot and verify your MySQL monitoring:

Check for blocked queries

FROM Log SELECT * WHERE event.name = 'db.server.query_sample' 
AND mysql.blocking.blocker.count > 0 
SINCE 1 hour ago

Tip

Filter with mysql.blocking.blocker.count > 0, not != 0 — in NRQL, null != 0 evaluates to TRUE, which would silently include non-blocked sessions in your results.

Find slowest queries

FROM Log SELECT db.query.text, 
mysql.events_statements_summary_by_digest.sum_timer_wait,
mysql.events_statements_summary_by_digest.count_star
WHERE event.name = 'db.server.top_query'
ORDER BY mysql.events_statements_summary_by_digest.sum_timer_wait DESC
LIMIT 10

Verify entity synthesis

FROM Metric SELECT uniqueCount(entity.guid) 
WHERE metricName LIKE 'mysql.%' 
FACET server.address, server.port
SINCE 1 hour ago

Getting help

If you continue experiencing issues:

Check the NRDOT Collector logs:
bash
```
$journalctl -u nrdot-collector -f
```

Verify your configuration syntax:

bash

$nrdot-collector validate --config=<your-config-file>

Review our compatibility requirements
Contact New Relic support with your collector logs and configuration (remove sensitive information like passwords)

Instrumentation in self-hosted environments

Learn how to set up MySQL monitoring in self-hosted environments with New Relic.

Instrumentation in RDS environments

Learn how to set up MySQL monitoring in RDS environments with New Relic.

Metrics reference

Learn about the available metrics collected by the NRDOT Collector.

Preview

Test connectivity

Test network connectivity to MySQL

Test OTLP endpoint connectivity

Common issues

Query events or samples aren't appearing

Wait time metrics aren't appearing

Important

Query plans missing for long queries

Query plans missing in top query events

Write statement plans missing

Client name is empty for sessions

Comment tags are empty

MySQL entity or APM relationship missing

Connection refused or authentication errors

AWS RDS specific issues

TLS certificate error connecting to RDS

NRQL query examples

Check for blocked queries

Tip

Find slowest queries

Verify entity synthesis

Getting help

Instrumentation in self-hosted environments

Instrumentation in RDS environments

Metrics reference

Troubleshooting MySQL NRDOT monitoring

Preview

Test connectivity.css-21sua1{background:none;border:none;width:0;padding:0;}

Test network connectivity to MySQL

Test OTLP endpoint connectivity

Common issues

Wait time metrics aren't appearing

Query plans missing for long queries

Query plans missing in top query events

Write statement plans missing

Client name is empty for sessions

Comment tags are empty

MySQL entity or APM relationship missing

Connection refused or authentication errors

AWS RDS specific issues

TLS certificate error connecting to RDS

NRQL query examples

Check for blocked queries

Tip

Find slowest queries

Verify entity synthesis

Getting help

Related documentation

Instrumentation in self-hosted environments

Instrumentation in RDS environments

Metrics reference

Test connectivity