Install & configure NRDOT for Self-hosted MySQL

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.

Set up MySQL monitoring using the NRDOT Collector on self-hosted environments including physical servers, virtual machines, and standalone installations.

Prerequisites

Before you install, make sure you have:

A New Relic license key.
Administrative access to your MySQL instance.
Network connectivity between the host where you install the NRDOT Collector and your MySQL database.
Network connectivity to New Relic OTLP endpoints documentation
This integration is available as a part of New Relic public preview program. Check with your Organization Manager to opt in from the Previews & Trials page.

For supported MySQL versions, required grants, and performance_schema requirements, see Compatibility and prerequisites.

Set up NRDOT Collector

Install the NRDOT Collector on your system:

For Debian/Ubuntu system, run:
bash
```
$NRDOT_VERSION=$(curl -s https://api.github.com/repos/newrelic/nrdot-collector-releases/releases/latest | grep '"tag_name":' | awk -F'"' '{print $4}') && curl -L "https://github.com/newrelic/nrdot-collector-releases/releases/download/${NRDOT_VERSION}/nrdot-collector_${NRDOT_VERSION}_linux_amd64.deb" --output nrdot-collector.deb && sudo dpkg -i nrdot-collector.deb
```

For RHEL/CentOS/OEL system, run:

bash

$NRDOT_VERSION=$(curl -s https://api.github.com/repos/newrelic/nrdot-collector-releases/releases/latest | grep '"tag_name":' | awk -F'"' '{print $4}') && curl -L "https://github.com/newrelic/nrdot-collector-releases/releases/download/${NRDOT_VERSION}/nrdot-collector_${NRDOT_VERSION}_linux_x86_64.rpm" --output nrdot-collector.rpm && sudo rpm -ivh nrdot-collector.rpm

For Debian/Ubuntu system, run:

bash

$NRDOT_VERSION=$(curl -s https://api.github.com/repos/newrelic/nrdot-collector-releases/releases/latest | grep '"tag_name":' | awk -F'"' '{print $4}') && curl -L "https://github.com/newrelic/nrdot-collector-releases/releases/download/${NRDOT_VERSION}/nrdot-collector_${NRDOT_VERSION}_linux_arm64.deb" --output nrdot-collector.deb && sudo dpkg -i nrdot-collector.deb

For RHEL/CentOS/OEL system, run:

bash

$NRDOT_VERSION=$(curl -s https://api.github.com/repos/newrelic/nrdot-collector-releases/releases/latest | grep '"tag_name":' | awk -F'"' '{print $4}') && curl -L "https://github.com/newrelic/nrdot-collector-releases/releases/download/${NRDOT_VERSION}/nrdot-collector_${NRDOT_VERSION}_linux_arm64.rpm" --output nrdot-collector.rpm && sudo rpm -ivh nrdot-collector.rpm

Configure database user

Create a monitoring user with the necessary privileges for your MySQL database instance.

To create a monitoring user, run the following command in your MySQL database:
```
CREATE USER '<YOUR_DB_USERNAME>'@'%' IDENTIFIED BY '<YOUR_DB_PASSWORD>';
```
To collect query samples and top queries, grant the following privileges to the monitoring user:
```
GRANT SELECT ON performance_schema.* TO '<YOUR_DB_USERNAME>'@'%';
```
(Optional) To view the wait-time data in New Relic platform, grant the following privileges to the monitoring user:
```
GRANT UPDATE ON performance_schema.setup_consumers TO '<YOUR_DB_USERNAME>'@'%';
```
(Optional) To verify the connection and grants, run:
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.

Configure NRDOT Collector

Configure the NRDOT Collector with your MySQL-specific settings. Select your configuration type based on your monitoring needs:

This configuration focuses on essential MySQL monitoring with the nrmysql receiver only.

Create a configuration file named as mysql-config.yaml:
bash
```
$sudo nano /etc/nrdot-collector/mysql-config.yaml
```
Add the following configuration to the mysql-config.yaml file you created in the previous step.

receivers:
  nrmysql:
    endpoint: "<YOUR_DB_HOST>:<YOUR_DB_PORT>"
    transport: tcp
    username: "<YOUR_DB_USERNAME>"
    password: "<YOUR_DB_PASSWORD>"
    database: "<YOUR_DATABASE_NAME>"
    allow_native_passwords: true
    collection_interval: 10s
    initial_delay: 1s
    tls:
      insecure: false
      insecure_skip_verify: false
      # ca_file: /path/to/global-bundle.pem
    explain_mode: procedure
    statement_events:
      digest_text_limit: 4096
      time_limit: 24h
      limit: 500
    query_sample_collection:
      max_rows_per_query: 100
      allowed_comment_keys: [nr_service_guid]
    top_query_collection:
      lookback_time: 120
      max_query_sample_count: 5000
      top_query_count: 200
      collection_interval: 60s
      query_plan_cache_size: 1000
      query_plan_cache_ttl: 1h
      allowed_comment_keys: [nr_service_guid]
    events:
      db.server.query_sample:
        enabled: true
      db.server.top_query:
        enabled: true

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

exporters:
  otlp/newrelic:
    endpoint: "<YOUR_NEWRELIC_OTLP_ENDPOINT>"
    headers:
      api-key: "<YOUR_NEWRELIC_LICENSE_KEY>"
    compression: gzip
    retry_on_failure:
      enabled: true
      initial_interval: 5s
      max_interval: 30s
      max_elapsed_time: 300s

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

This configuration adds host-level metrics (CPU, memory, disk, network) alongside MySQL database monitoring.

Create a configuration file named as mysql-config.yaml:
bash
```
$sudo nano /etc/nrdot-collector/mysql-config.yaml
```
Add the following configuration to the mysql-config.yaml file you created in the previous step.

extensions:
  health_check:

receivers:
  otlp:
    protocols:
      grpc:
      http:

  host_metrics:
    collection_interval: 30s
    scrapers:
      cpu:
        metrics:
          system.cpu.time:
            enabled: false
          system.cpu.utilization:
            enabled: true
      load:
      memory:
        metrics:
          system.memory.utilization:
            enabled: true
      paging:
        metrics:
          system.paging.utilization:
            enabled: false
          system.paging.faults:
            enabled: false
      filesystem:
        metrics:
          system.filesystem.utilization:
            enabled: true
      disk:
        metrics:
          system.disk.merged:
            enabled: false
          system.disk.pending_operations:
            enabled: false
          system.disk.weighted_io_time:
            enabled: false
      network:
        metrics:
          system.network.connections:
            enabled: false
      # Uncomment to enable process metrics, which can be noisy but valuable.
      # processes:
      # process:
      #  metrics:
      #    process.cpu.utilization:
      #      enabled: true
      #    process.cpu.time:
      #      enabled: false

  nrmysql:
    endpoint: "<YOUR_DB_HOST>:<YOUR_DB_PORT>"
    transport: tcp
    username: "<YOUR_DB_USERNAME>"
    password: "<YOUR_DB_PASSWORD>"
    database: "<YOUR_DATABASE_NAME>"
    allow_native_passwords: true
    collection_interval: 10s
    initial_delay: 1s
    tls:
      insecure: false
      insecure_skip_verify: false
      # Required for Amazon RDS/Aurora with SSL/TLS enforcement -- see
      # Prerequisites -> Network access -> Amazon RDS / Aurora for MySQL.
      # ca_file: /path/to/global-bundle.pem
    # "procedure" collects EXPLAIN plans for write statements (UPDATE/DELETE/INSERT/REPLACE)
    # without granting DML to the monitoring user, via a SQL SECURITY DEFINER procedure.
    # Falls back to "inline" (default) automatically if the procedure is absent for a schema.
    # Requires one-time setup per schema -- see Prerequisites -> DML query plan collection.
    explain_mode: procedure
    statement_events:
      digest_text_limit: 4096
      time_limit: 24h
      limit: 500
    query_sample_collection:
      max_rows_per_query: 100
      # APM-DB correlation: surfaces the nr_service_guid SQL comment tag (e.g. injected by
      # transaction_tracer.sql_metadata_comments in the Java agent) as db.query.comment_tags /
      # db.query.comment_tags.nr_service_guid. Empty list by default -- nothing is extracted
      # unless the key is explicitly allow-listed here.
      allowed_comment_keys: [nr_service_guid]
    top_query_collection:
      lookback_time: 120
      max_query_sample_count: 5000
      top_query_count: 200
      collection_interval: 60s
      query_plan_cache_size: 1000
      query_plan_cache_ttl: 1h
      allowed_comment_keys: [nr_service_guid]
    events:
      db.server.query_sample:
        enabled: true
      db.server.top_query:
        enabled: true

processors:
  metrics_transform:
    transforms:
      - include: system.cpu.utilization
        action: update
        operations:
          - action: aggregate_labels
            label_set: [state]
            aggregation_type: mean
      - include: system.paging.operations
        action: update
        operations:
          - action: aggregate_labels
            label_set: [direction]
            aggregation_type: sum

  filter/exclude_cpu_utilization:
    metrics:
      datapoint:
        - 'metric.name == "system.cpu.utilization" and attributes["state"] == "interrupt"'
        - 'metric.name == "system.cpu.utilization" and attributes["state"] == "nice"'
        - 'metric.name == "system.cpu.utilization" and attributes["state"] == "softirq"'

  filter/exclude_memory_utilization:
    metrics:
      datapoint:
        - 'metric.name == "system.memory.utilization" and attributes["state"] == "slab_unreclaimable"'
        - 'metric.name == "system.memory.utilization" and attributes["state"] == "inactive"'
        - 'metric.name == "system.memory.utilization" and attributes["state"] == "cached"'
        - 'metric.name == "system.memory.utilization" and attributes["state"] == "buffered"'
        - 'metric.name == "system.memory.utilization" and attributes["state"] == "slab_reclaimable"'

  filter/exclude_memory_usage:
    metrics:
      datapoint:
        - 'metric.name == "system.memory.usage" and attributes["state"] == "slab_unreclaimable"'
        - 'metric.name == "system.memory.usage" and attributes["state"] == "inactive"'

  filter/exclude_filesystem_utilization:
    metrics:
      datapoint:
        - 'metric.name == "system.filesystem.utilization" and attributes["type"] == "squashfs"'

  filter/exclude_filesystem_usage:
    metrics:
      datapoint:
        - 'metric.name == "system.filesystem.usage" and attributes["type"] == "squashfs"'
        - 'metric.name == "system.filesystem.usage" and attributes["state"] == "reserved"'

  filter/exclude_filesystem_inodes_usage:
    metrics:
      datapoint:
        - 'metric.name == "system.filesystem.inodes.usage" and attributes["type"] == "squashfs"'
        - 'metric.name == "system.filesystem.inodes.usage" and attributes["state"] == "reserved"'

  filter/exclude_system_disk:
    metrics:
      datapoint:
        - 'metric.name == "system.disk.operations" and IsMatch(attributes["device"], "^loop.*") == true'
        - 'metric.name == "system.disk.merged" and IsMatch(attributes["device"], "^loop.*") == true'
        - 'metric.name == "system.disk.io" and IsMatch(attributes["device"], "^loop.*") == true'
        - 'metric.name == "system.disk.io_time" and IsMatch(attributes["device"], "^loop.*") == true'
        - 'metric.name == "system.disk.operation_time" and IsMatch(attributes["device"], "^loop.*") == true'

  filter/exclude_network:
    metrics:
      datapoint:
        - 'IsMatch(metric.name, "^system.network.*") == true and attributes["device"] == "lo"'

  attributes/exclude_system_paging:
    include:
      match_type: strict
      metric_names:
        - system.paging.operations
    actions:
      - key: type
        action: delete

  cumulative_to_delta:

  transform:
    trace_statements:
      - context: span
        statements:
          - truncate_all(span.attributes, 4095)
          - truncate_all(resource.attributes, 4095)

  transform/host:
    metric_statements:
      - context: metric
        statements:
          - set(metric.description, "")
          - set(metric.unit, "")

  # Static server.address/server.port, reusing the same <YOUR_DB_HOST>/<YOUR_DB_PORT>
  # values already set on the receiver's own `endpoint` field above -- nrmysqlreceiver
  # itself emits no server.address/server.port, only its own mysql.instance.endpoint
  # (a combined "host:port" string). Applies uniformly to both metrics and logs
  # pipelines since neither depends on how that string is derived.
  resource/mysql:
    attributes:
      - key: server.address
        value: "<YOUR_DB_HOST>"
        action: upsert
      - key: server.port
        value: <YOUR_DB_PORT>
        action: upsert

  batch:

  resource_detection:
    detectors: ["system"]
    system:
      hostname_sources: ["os"]
      resource_attributes:
        host.id:
          enabled: true

  resource_detection/cloud:
    detectors: ["gcp", "ec2", "azure"]
    timeout: 2s
    override: true

  resource_detection/env:
    detectors: ["env"]
    timeout: 2s
    override: true

exporters:
  otlp/newrelic:
    endpoint: "<YOUR_NEWRELIC_OTLP_ENDPOINT>"
    headers:
      api-key: "<YOUR_NEWRELIC_LICENSE_KEY>"
    compression: gzip
    retry_on_failure:
      enabled: true
      initial_interval: 5s
      max_interval: 30s
      max_elapsed_time: 300s

service:
  telemetry:
    metrics:
      level: none

  extensions: [health_check]

  pipelines:
    metrics/host:
      receivers: [host_metrics]
      processors:
        - metrics_transform
        - filter/exclude_cpu_utilization
        - filter/exclude_memory_utilization
        - filter/exclude_memory_usage
        - filter/exclude_filesystem_utilization
        - filter/exclude_filesystem_usage
        - filter/exclude_filesystem_inodes_usage
        - filter/exclude_system_disk
        - filter/exclude_network
        - attributes/exclude_system_paging
        - transform/host
        - resource_detection
        - resource_detection/cloud
        - resource_detection/env
        - cumulative_to_delta
        - batch
      exporters: [otlp/newrelic]

    metrics/mysql:
      receivers: [nrmysql]
      processors:
        - resource/mysql
        - resource_detection
        - resource_detection/cloud
        - resource_detection/env
        - batch
      exporters: [otlp/newrelic]

    logs/mysql:
      receivers: [nrmysql]
      processors:
        - resource/mysql
        - resource_detection
        - resource_detection/cloud
        - resource_detection/env
        - batch
      exporters: [otlp/newrelic]

    traces:
      receivers: [otlp]
      processors: [transform, resource_detection, resource_detection/cloud, resource_detection/env, batch]
      exporters: [otlp/newrelic]

    metrics:
      receivers: [otlp]
      processors: [resource_detection, resource_detection/cloud, resource_detection/env, batch]
      exporters: [otlp/newrelic]

    logs:
      receivers: [otlp]
      processors: [resource_detection, resource_detection/cloud, resource_detection/env, batch]
      exporters: [otlp/newrelic]

Important

MySQL integration via NRDOT Collector follows standard data ingest pricing. Note that full feature configuration ingests more data than a standard setup, which may increase your overall bill.

Configuration parameters

The following table describes the key configuration parameters for the nrmysql receiver:

Parameter	Description
`<YOUR_DB_HOST>`	Enter your MySQL host name or IP address.
`<YOUR_DB_PORT>`	Enter your MySQL port number. The default value is `3306`.
`<YOUR_DB_USERNAME>`	Enter the username of the monitoring user you created in Configure database user.
`<YOUR_DB_PASSWORD>`	Enter the password of the monitoring user you created in Configure database user.
`<YOUR_DATABASE_NAME>`	Optional. Enter a specific database name to restrict monitoring to it. Omit this parameter to monitor every database the monitoring user can access.
`<YOUR_NEWRELIC_OTLP_ENDPOINT>`	Enter the New Relic OTLP endpoint. For more information, see New Relic OTLP endpoints.
`<YOUR_NEWRELIC_LICENSE_KEY>`	Enter your New Relic license key.
`transport`	Default value is set to `tcp` to connect over the network. If your NRDOT Collector runs on the same host as MySQL, use `unix` to connect through a Unix domain socket instead.
`collection_interval`	Enter the interval between metric scrapes. Default: `10s`.
`explain_mode`	Default value is set to `inline`. Set the value to `procedure` to collect query plans for write statements without granting DML privileges to the monitoring user. See Query plans for write statements.

Validate NRDOT Collector configuration

Update the config path to point to your new mysql-config.yaml file:
bash
```
$OTELCOL_OPTIONS="/etc/nrdot-collector/mysql-config.yaml"
```
Validate the NRDOT Collector configuration to ensure it's correctly formatted and will work properly:
bash
```
$sudo /usr/bin/nrdot-collector validate --config=/etc/nrdot-collector/mysql-config.yaml
```

Tip

You can also:

Configure multiple receivers: To monitor multiple MySQL instances from one collector.
Link your MySQL database with APM: To correlate your application performance with database operations. This allows you to see exactly which applications are generating specific database workloads.
Set up secret management: To securely manage sensitive information, such as database credentials. This helps to enhance the security of your monitoring setup by avoiding hardcoding sensitive data in configuration files.

Restart NRDOT Collector

After updating your configuration, restart the NRDOT Collector service:

bash

$sudo systemctl restart nrdot-collector

Tip

Always restart the NRDOT collector service after making configuration changes to ensure the new settings take effect.

To verify that the collector is running properly, check the service status:

bash

$sudo systemctl status nrdot-collector

Find and use your data

Once your data is being collected, you can access comprehensive MySQL database monitoring through New Relic's UI.

To find your MySQL database entity in New Relic:

Go to https://one.newrelic.com > All Capabilities > Databases.
From the Entity type dropdown, select MySQL instance, then click Apply.
Select your MySQL database from the list of entities.
After setting up MySQL database monitoring with NRDOT:
- Create custom dashboards to visualize your database metrics
- Set up alerts for critical database performance thresholds

Troubleshooting guide

Learn how to troubleshoot common issues with MySQL monitoring.

Metrics reference

Learn about the available metrics collected by the NRDOT Collector.

Instrumentation in RDS environments

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

Install & configure NRDOT for Self-hosted MySQL

Preview

Prerequisites

Set up NRDOT Collector

For AMD64 architecture

For ARM64 architecture

Configure database user

Configure NRDOT Collector

Standard configuration

Full-feature configuration

Important

Configuration parameters

Validate NRDOT Collector configuration

Tip

Restart NRDOT Collector

Tip

Find and use your data

Troubleshooting guide

Metrics reference

Instrumentation in RDS environments

Install & configure NRDOT for Self-hosted MySQL

Preview

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

Set up NRDOT Collector

For ARM64 architecture

Configure database user

Configure NRDOT Collector

Standard configuration

Full-feature configuration

Configuration parameters

Validate NRDOT Collector configuration

Tip

Restart NRDOT Collector

Tip

Find and use your data

Related documentation

Troubleshooting guide

Metrics reference

Instrumentation in RDS environments

Prerequisites