- Essentials
- In The App
- Infrastructure
- Application Performance
- Log Management
- Security Platform
- UX Monitoring
- Administration
Database Monitoring provides deep visibility into your MySQL databases by exposing query metrics, query samples, explain plans, connection data, system metrics, and telemetry for the InnoDB storage engine.
The Agent collects telemetry directly from the database by logging in as a read-only user. Do the following setup to enable Database Monitoring with your MySQL database:
127.0.0.1
or the socket is preferred. The Agent should not connect to the database through a proxy, load balancer, or connection pooler. While this can be an anti-pattern for client applications, each Agent must have knowledge of the underlying hostname and should stick to a single host for its lifetime, even in cases of failover. If the Datadog Agent connects to different hosts while it is running, the values of metrics will be incorrect.To collect query metrics, samples, and explain plans, enable the MySQL Performance Schema and configure the following Performance Schema Options, either on the command line or in configuration files (for example, mysql.conf
):
Parameter | Value | Description |
---|---|---|
performance_schema | ON | Required. Enables the Performance Schema. |
max_digest_length | 4096 | Required for collection of larger queries. If left at the default value then queries longer than 1024 characters will not be collected. |
| 4096 | Must match max_digest_length . |
performance-schema-consumer-events-statements-current | ON | Required. Enables monitoring of currently running queries. |
performance-schema-consumer-events-waits-current | ON | Required. Enables the collection of wait events. |
performance-schema-consumer-events-statements-history-long | ON | Recommended. Enables tracking of a larger number of recent queries across all threads. If enabled it increases the likelihood of capturing execution details from infrequent queries. |
performance-schema-consumer-events-statements-history | ON | Optional. Enables tracking recent query history per thread. If enabled it increases the likelihood of capturing execution details from infrequent queries. |
Parameter | Value | Description |
---|---|---|
performance_schema | ON | Required. Enables the Performance Schema. |
max_digest_length | 4096 | Required for collection of larger queries. If left at the default value then queries longer than 1024 characters will not be collected. |
| 4096 | Must match max_digest_length . |
| 4096 | Must match max_digest_length . |
performance-schema-consumer-events-statements-current | ON | Required. Enables monitoring of currently running queries. |
performance-schema-consumer-events-waits-current | ON | Required. Enables the collection of wait events. |
performance-schema-consumer-events-statements-history-long | ON | Recommended. Enables tracking of a larger number of recent queries across all threads. If enabled it increases the likelihood of capturing execution details from infrequent queries. |
performance-schema-consumer-events-statements-history | ON | Optional. Enables tracking recent query history per thread. If enabled it increases the likelihood of capturing execution details from infrequent queries. |
Note: A recommended practice is to allow the agent to enable the performance-schema-consumer-*
settings dynamically at runtime, as part of granting the Agent access. See Runtime setup consumers.
The Datadog Agent requires read-only access to the database in order to collect statistics and queries.
The following instructions grant the Agent permission to login from any host using datadog@'%'
. You can restrict the datadog
user to be allowed to login only from localhost by using datadog@'localhost'
. See the MySQL documentation for more info.
Create the datadog
user and grant basic permissions:
CREATE USER datadog@'%' IDENTIFIED WITH mysql_native_password by '<UNIQUEPASSWORD>';
ALTER USER datadog@'%' WITH MAX_USER_CONNECTIONS 5;
GRANT REPLICATION CLIENT ON *.* TO datadog@'%';
GRANT PROCESS ON *.* TO datadog@'%';
GRANT SELECT ON performance_schema.* TO datadog@'%';
Create the datadog
user and grant basic permissions:
CREATE USER datadog@'%' IDENTIFIED BY '<UNIQUEPASSWORD>';
GRANT REPLICATION CLIENT ON *.* TO datadog@'%' WITH MAX_USER_CONNECTIONS 5;
GRANT PROCESS ON *.* TO datadog@'%';
GRANT SELECT ON performance_schema.* TO datadog@'%';
Create the following schema:
CREATE SCHEMA IF NOT EXISTS datadog;
GRANT EXECUTE ON datadog.* to datadog@'%';
GRANT CREATE TEMPORARY TABLES ON datadog.* TO datadog@'%';
Create the the explain_statement
procedure to enable the Agent to collect explain plans:
DELIMITER $$
CREATE PROCEDURE datadog.explain_statement(IN query TEXT)
SQL SECURITY DEFINER
BEGIN
SET @explain := CONCAT('EXPLAIN FORMAT=json ', query);
PREPARE stmt FROM @explain;
EXECUTE stmt;
DEALLOCATE PREPARE stmt;
END $$
DELIMITER ;
Additionally, create this procedure in every schema from which you want to collect explain plans. Replace <YOUR_SCHEMA>
with your database schema:
DELIMITER $$
CREATE PROCEDURE <YOUR_SCHEMA>.explain_statement(IN query TEXT)
SQL SECURITY DEFINER
BEGIN
SET @explain := CONCAT('EXPLAIN FORMAT=json ', query);
PREPARE stmt FROM @explain;
EXECUTE stmt;
DEALLOCATE PREPARE stmt;
END $$
DELIMITER ;
GRANT EXECUTE ON PROCEDURE <YOUR_SCHEMA>.explain_statement TO datadog@'%';
Datadog recommends that you create the following procedure to give the Agent the ability to enable performance_schema.events_*
consumers at runtime.
DELIMITER $$
CREATE PROCEDURE datadog.enable_events_statements_consumers()
SQL SECURITY DEFINER
BEGIN
UPDATE performance_schema.setup_consumers SET enabled='YES' WHERE name LIKE 'events_statements_%';
UPDATE performance_schema.setup_consumers SET enabled='YES' WHERE name = 'events_waits_current';
END $$
DELIMITER ;
GRANT EXECUTE ON PROCEDURE datadog.enable_events_statements_consumers TO datadog@'%';
Installing the Datadog Agent also installs the MySQL check which is required for Database Monitoring on MySQL. If you haven’t already installed the Agent for your MySQL database host, see the Agent installation instructions.
To configure this check for an Agent running on a host:
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, including those for custom metrics.
Add this configuration block to your mysql.d/conf.yaml
to collect MySQL metrics:
init_config:
instances:
- dbm: true
host: 127.0.0.1
port: 3306
username: datadog
password: '<YOUR_CHOSEN_PASSWORD>' # from the CREATE USER step earlier
Note: Wrap your password in single quotes in case a special character is present.
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
.
Restart the Agent to start sending MySQL metrics to Datadog.
In addition to telemetry collected from the database by the Agent, you can also choose to send your database logs directly to Datadog.
By default MySQL logs everything in /var/log/syslog
which requires root access to read. To make the logs more accessible, follow these steps:
/etc/mysql/conf.d/mysqld_safe_syslog.cnf
and comment out all lines./etc/mysql/my.cnf
to enable the desired logging settings. For example, to enable general, error, and slow query logs, use the following configuration: [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 = 3
/var/log/mysql
directory and all of the files within. Double-check your logrotate
configuration to make sure these files are taken into account and that the permissions are correctly set.
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
}
Collecting logs is disabled by default in the Datadog Agent, enable it in your datadog.yaml
file:
logs_enabled: true
Add this configuration block to your mysql.d/conf.yaml
file to start collecting your MySQL logs:
logs:
- type: file
path: "<ERROR_LOG_FILE_PATH>"
source: mysql
service: "<SERVICE_NAME>"
- type: file
path: "<SLOW_QUERY_LOG_FILE_PATH>"
source: mysql
service: "<SERVICE_NAME>"
log_processing_rules:
- type: multi_line
name: new_slow_query_log_entry
pattern: "# Time:"
# If mysqld was started with `--log-short-format`, use:
# pattern: "# Query_time:"
# If using mysql version <5.7, use the following rules instead:
# - type: multi_line
# name: new_slow_query_log_entry
# pattern: "# Time|# User@Host"
# - type: exclude_at_match
# name: exclude_timestamp_only_line
# pattern: "# Time:"
- type: file
path: "<GENERAL_LOG_FILE_PATH>"
source: mysql
service: "<SERVICE_NAME>"
# 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])
# If the logs start with a date with the format yymmdd but include a timestamp with each new second, rather than with each log, uncomment the following processing rule
# log_processing_rules:
# - type: multi_line
# name: new_logs_do_not_always_start_with_timestamp
# pattern: \t\t\s*\d+\s+|\d{6}\s+\d{,2}:\d{2}:\d{2}\t\s*\d+\s+
Run the Agent’s status subcommand and look for mysql
under the Checks section. Or visit the Databases page to get started!
If you have installed and configured the integrations and Agent as described and it is not working as expected, see Troubleshooting.
Additional helpful documentation, links, and articles: