---
title: Install & configure NRDOT for MySQL monitoring with Self-hosted
source: https://docs.newrelic.com/docs/opentelemetry/db360/mysql/hosted
---

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

## Prerequisites [#prerequisites]

Before you install, make sure you have:

-   A New Relic [license key](https://docs.newrelic.com/docs/apis/intro-apis/new-relic-api-keys/#ingest-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](https://docs.newrelic.com/docs/opentelemetry/best-practices/opentelemetry-otlp/)

For supported MySQL versions, required grants, and `performance_schema` requirements, see [Compatibility and prerequisites](https://docs.newrelic.com/docs/opentelemetry/db360/mysql/compatibility).

## Set up NRDOT Collector [#setup]

Install the NRDOT Collector on your system:

**For AMD64 architecture**

-   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 ARM64 architecture**

-   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 [#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:

    ```sql
    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:

    ```sql
    GRANT SELECT ON performance_schema.* TO '<YOUR_DB_USERNAME>'@'%';
    GRANT SELECT ON *.* TO '<YOUR_DB_USERNAME>'@'%';
    GRANT REPLICATION CLIENT ON *.* TO '<YOUR_DB_USERNAME>'@'%';
    GRANT PROCESS ON *.* TO '<YOUR_DB_USERNAME>'@'%';
    ```

-   (Optional) To view the wait-time data in New Relic platform, grant the following privileges to the monitoring user:

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

-   (Optional) To verify the connection and grants, run:

    ```shell
    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]

Configure the NRDOT Collector with your MySQL-specific settings.

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

> #### 💡 FULL CONFIGURATION
>
> This baseline configuration captures essential metrics. To see the complete metric catalog, refer to the [configuration reference](https://docs.newrelic.com/docs/opentelemetry/db360/mysql/config-reference/#hosted-full).

1.  Create a configuration file named `mysql-config.yaml`:

    ```bash
      sudo nano /etc/nrdot-collector/mysql-config.yaml
    ```

2.  Add the following configuration to the `mysql-config.yaml` file you created in the previous step.

```yaml
receivers:
  nrmysql:
    endpoint: "<YOUR_DB_HOST>:<YOUR_DB_PORT>"
    transport: tcp
    username: "<YOUR_DB_USERNAME>"
    password: "<YOUR_DB_PASSWORD>"
    allow_native_passwords: true
    collection_interval: 15s
    initial_delay: 1s
    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: 60
      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
      db.server.query_plan:
        enabled: true
    resource_attributes:
      db.system.version:
        enabled: true
    metrics:
      mysql.query.count:
        enabled: true
      mysql.query.slow.count:
        enabled: true
      mysql.commands:
        enabled: true
      mysql.innodb.data_file.io:
        enabled: true

processors:
  batch:

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: [batch]
      exporters: [otlp/newrelic]
    logs:
      receivers: [nrmysql]
      processors: [batch]
      exporters: [otlp/newrelic]
```

> #### 💡 TIP
>
> This configuration omits the optional `database` and `tls` fields. By default, the receiver monitors every database the monitoring user can access, and connects without TLS. To [monitor a specific database](https://docs.newrelic.com/docs/opentelemetry/db360/mysql/optional#database), or to [enable TLS](https://docs.newrelic.com/docs/opentelemetry/db360/mysql/optional#tls) (required for most Amazon RDS/Aurora instances), see Enable detailed insights.

### 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](#user).                                                                                                                                                                                          |
| `<YOUR_DB_PASSWORD>`            | Enter the password of the monitoring user you created in [Configure database user](#user).                                                                                                                                                                                          |
| `<YOUR_NEWRELIC_OTLP_ENDPOINT>` | Enter the New Relic OTLP endpoint. For more information, see [New Relic OTLP endpoints](https://docs.newrelic.com/docs/opentelemetry/best-practices/opentelemetry-otlp/).                                                                                                           |
| `<YOUR_NEWRELIC_LICENSE_KEY>`   | Enter your New Relic [license key](https://docs.newrelic.com/docs/apis/intro-apis/new-relic-api-keys/#ingest-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: `15s`.                                                                                                                                                                                                                          |
| `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](https://docs.newrelic.com/docs/opentelemetry/db360/mysql/optional#query). |

## Validate NRDOT Collector configuration [#validate]

1.  Update the config path to point to your new `mysql-config.yaml` file:

    ```bash
      sudo sed -i 's|OTELCOL_OPTIONS="--config=/etc/nrdot-collector/config.yaml"|OTELCOL_OPTIONS="--config=/etc/nrdot-collector/mysql-config.yaml"|' /etc/nrdot-collector/nrdot-collector.conf
    ```
2.  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](https://docs.newrelic.com/docs/opentelemetry/db360/mysql/multi-receiver): To monitor multiple MySQL instances from one collector.
> -   [Link your MySQL database with APM](https://docs.newrelic.com/docs/opentelemetry/db360/capabilities/db-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](https://docs.newrelic.com/docs/opentelemetry/db360/capabilities/db-apm/#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 [#restart]

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 [#find]

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

To find your MySQL database entity in New Relic:

1.  Go to **<https://one.newrelic.com> > All Capabilities > Databases**.
2.  From the **Entity type** dropdown, select **MySQL instance**, then click **Apply**.
3.  Select your MySQL database from the list of entities.

    After setting up MySQL database monitoring with NRDOT:

    -   [Create custom dashboards](https://docs.newrelic.com/docs/query-your-data/explore-query-data/dashboards/introduction-dashboards/) to visualize your database metrics
    -   [Set up alerts](https://docs.newrelic.com/docs/alerts/create-alert/create-alert-condition/alert-conditions/) for critical database performance thresholds

## Related documentation [#related]

[Troubleshooting guide](https://docs.newrelic.com/docs/opentelemetry/db360/mysql/troubleshooting)

Learn how to troubleshoot common issues with MySQL monitoring.

[Metrics reference](https://docs.newrelic.com/docs/opentelemetry/db360/mysql/metrics-reference)

Learn about the available metrics collected by the NRDOT Collector.

[Instrumentation in RDS environments](https://docs.newrelic.com/docs/opentelemetry/db360/mysql/rds)

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