The Datadog Agent can collect many metrics from MySQL databases, including (but not limited to):

• Query throughput
• Query performance (e.g. average query run time, slow queries, etc.)
• Connections (e.g. currently open connections, aborted connections, errors, etc.)
• InnoDB (e.g. buffer pool metrics, etc.)

You can also create your own metrics using custom SQL queries.

Note: This integration is also compatible with MariaDB, as it serves as a "drop-in replacement" for MySQL.

The MySQL check is included in the Datadog Agent package. No additional installation is needed on your MySQL server.

On each MySQL server, create a database user for the Datadog Agent:

mysql> CREATE USER 'datadog'@'localhost' IDENTIFIED BY '<UNIQUEPASSWORD>';
Query OK, 0 rows affected (0.00 sec)

For mySQL 8.0+ create the datadog user with the native password hashing method:

mysql> CREATE USER 'datadog'@'localhost' IDENTIFIED WITH mysql_native_password by '<UNIQUEPASSWORD>';
Query OK, 0 rows affected (0.00 sec)

Note: @'localhost' is only for local connections - use the hostname/IP of your Agent for remote connections. For more information, see the MySQL documentation.

Verify the user was created successfully using the following commands - replace <UNIQUEPASSWORD> with the password you created above:

mysql -u datadog --password=<UNIQUEPASSWORD> -e "show status" | \
grep Uptime && echo -e "\033[0;32mMySQL user - OK\033[0m" || \
echo -e "\033[0;31mCannot connect to MySQL\033[0m"

mysql -u datadog --password=<UNIQUEPASSWORD> -e "show slave status" && \
echo -e "\033[0;32mMySQL grant - OK\033[0m" || \
echo -e "\033[0;31mMissing REPLICATION CLIENT grant\033[0m"

The Agent needs a few privileges to collect metrics. Grant the user the following limited privileges ONLY:

mysql> GRANT REPLICATION CLIENT ON *.* TO 'datadog'@'localhost' WITH MAX_USER_CONNECTIONS 5;
Query OK, 0 rows affected, 1 warning (0.00 sec)

mysql> GRANT PROCESS ON *.* TO 'datadog'@'localhost';
Query OK, 0 rows affected (0.00 sec)

For mySQL 8.0+ set max_user_connections with:

mysql> ALTER USER 'datadog'@'localhost' WITH MAX_USER_CONNECTIONS 5;
Query OK, 0 rows affected (0.00 sec)

If enabled, metrics can be collected from the performance_schema database by granting an additional privilege:

mysql> show databases like 'performance_schema';
+-------------------------------+
| Database (performance_schema) |
+-------------------------------+
| performance_schema            |
+-------------------------------+
1 row in set (0.00 sec)

mysql> GRANT SELECT ON performance_schema.* TO 'datadog'@'localhost';
Query OK, 0 rows affected (0.00 sec)

Follow the instructions below to configure this check for an Agent running on a host. For containerized environments, see the Containerized section.

Edit the mysql.d/conf.yaml file, in the conf.d/ folder at the root of your Agent's configuration directory to start collecting your MySQL metrics and logs. See the sample mysql.d/conf.yaml for all available configuration options.

• Add this configuration block to your mysql.d/conf.yaml to collect your MySQL metrics:

  init_config:
  
  instances:
    - server: 127.0.0.1
      user: datadog
      pass: '<YOUR_CHOSEN_PASSWORD>' # from the CREATE USER step earlier
      port: <YOUR_MYSQL_PORT> # e.g. 3306
      options:
          replication: 0
          galera_cluster: true
          extra_status_metrics: true
          extra_innodb_metrics: true
          extra_performance_metrics: true
          schema_size_metrics: false
          disable_innodb_metrics: false
  

Note: Wrap your password in single quotes in case a special character is present.

To collect extra_performance_metrics, your MySQL server must have performance_schema enabled - otherwise set extra_performance_metrics to false. For more information on performance_schema, see the MySQL documentation.

Note that the datadog user should be set up in the MySQL integration configuration as host: 127.0.0.1 instead of localhost. Alternatively, you may also use sock.

See our sample mysql.yaml for all available configuration options, including those for custom metrics.

Restart the Agent to start sending MySQL metrics to Datadog.

Available for Agent >6.0

1. By default MySQL logs everything in /var/log/syslog which requires root access to read. To make the logs more accessible, follow these steps:

   • Edit /etc/mysql/conf.d/mysqld_safe_syslog.cnf and remove or comment the lines.

   • Edit /etc/mysql/my.cnf and add following lines to enable general, error, and slow query logs:

       [mysqld_safe]
       log_error=/var/log/mysql/mysql_error.log
       [mysqld]
       general_log = on
       general_log_file = /var/log/mysql/mysql.log
       log_error=/var/log/mysql/mysql_error.log
       slow_query_log = on
       slow_query_log_file = /var/log/mysql/mysql-slow.log
       long_query_time = 2
     

   • Save the file and restart MySQL using following commands: service mysql restart

   • Make sure the Agent has read access on the /var/log/mysql directory and all of the files within. Double-check your logrotate configuration to make sure those files are taken into account and that the permissions are correctly set there as well.

   • In /etc/logrotate.d/mysql-server there should be something similar to:

       /var/log/mysql.log /var/log/mysql/mysql.log /var/log/mysql/mysql-slow.log {
               daily
               rotate 7
               missingok
               create 644 mysql adm
               Compress
       }
     

2. Collecting logs is disabled by default in the Datadog Agent, enable it in your datadog.yaml file:

     logs_enabled: true

3. Add this configuration block to your mysql.d/conf.yaml file to start collecting your MySQL logs:

     logs:
         - type: file
           path: /var/log/mysql/mysql_error.log
           source: mysql
           sourcecategory: database
           service: myapplication
   
         - type: file
           path: /var/log/mysql/mysql-slow.log
           source: mysql
           sourcecategory: database
           service: myapplication
   
         - type: file
           path: /var/log/mysql/mysql.log
           source: mysql
           sourcecategory: database
           service: myapplication
           # For multiline logs, if they start by the date with the format yyyy-mm-dd uncomment the following processing rule
           # log_processing_rules:
           #   - type: multi_line
           #     name: new_log_start_with_date
           #     pattern: \d{4}\-(0?[1-9]|1[012])\-(0?[1-9]|[12][0-9]|3[01])

   See our sample mysql.yaml for all available configuration options, including those for custom metrics.

4. Restart the Agent.

For containerized environments, see the Autodiscovery Integration Templates for guidance on applying the parameters below.

See the Autodiscovery template variables documentation to learn how to pass <UNIQUEPASSWORD> as an Environment variable instead of a label.

Available for Agent v6.5+

Collecting logs is disabled by default in the Datadog Agent. To enable it, see Docker log collection.

Run the Agent's status subcommand and look for mysql under the Checks section.

See metadata.csv for a list of metrics provided by this integration.

The check does not collect all metrics by default. Set the following boolean configuration options to true to enable the respective metrics:

extra_status_metrics adds the following metrics:

extra_innodb_metrics adds the following metrics:

extra_performance_metrics adds the following metrics:

schema_size_metrics adds the following metric:

The MySQL check does not include any events.

mysql.replication.slave_running:
Returns CRITICAL if the Agent is unable to connect to the monitored MySQL instance, otherwise returns OK. See this for more details.

mysql.can_connect:
Returns CRITICAL if the Agent cannot connect to MySQL to collect metrics, otherwise returns OK.

• Connection Issues with the SQL Server Integration
• MySQL Localhost Error - Localhost VS 127.0.0.1
• Can I use a named instance in the SQL Server integration?
• Can I set up the dd-agent MySQL check on my Google CloudSQL?
• How to collect metrics from custom MySQL queries
• Can I collect SQL Server performance metrics beyond what is available in the sys.dm_os_performance_counters table? Try WMI
• How can I collect more metrics from my SQL Server integration?
• Database user lacks privileges
• How to collect metrics with a SQL Stored Procedure?

Read our series of blog posts about monitoring MySQL with Datadog.