La solution Database Monitoring vous permet de bénéficier d’une visibilité complète sur vos bases de données MySQL, en exposant des métriques de requête, des échantillons de requête, des plans d’exécution, des données sur les connexions, des métriques système et des données de télémétrie à propos du moteur de stockage InnoDB.

L’Agent recueille la télémétrie directement depuis la base de données, en se connectant en tant qu’utilisateur en lecture seule. Suivez les étapes ci-dessous pour activer la solution Database Monitoring avec votre base de données MySQL :

1. Configurer les paramètres de base de données
2. Autoriser l’Agent à accéder à la base de données
3. Installer l’Agent

Avant de commencer

Versions de MySQL prises en charge

5.6, 5.7 et 8.0+

Versions de l’Agent prises en charge

7.36.1 et versions ultérieures

Incidence sur les performances

La configuration par défaut de l’Agent pour Database Monitoring est relativement souple. Néanmoins, vous pouvez ajuster certains paramètres comme l’intervalle de collecte et le taux d’échantillonnage des requêtes pour mieux répondre à vos besoins. Pour la plupart des workloads, l’Agent monopolise moins d’un pour cent du temps d’exécution des requêtes sur la base de données, et moins d’un pour cent du CPU.

La solution Database Monitoring de Datadog fonctionne comme une intégration et vient compléter l’Agent de base (voir les benchmarks).

Proxies, répartiteurs de charge et outils de regroupement de connexions

L’Agent doit se connecter directement au host surveillé. Pour les bases de données auto-hébergées, il est préférable d’utiliser 127.0.0.1 ou le socket. L’Agent ne doit pas se connecter aux bases de données via un proxy, un répartiteur de charge ni un outil de groupement de connexions. Bien qu’il puisse s’agir d’un antipattern pour des applications client, chaque Agent doit connaître le hostname sous-jacent et rester sur un seul host pendant toute sa durée de vie, même en cas de failover. Si l’Agent Datadog se connecte à plusieurs hosts pendant son exécution, les valeurs des métriques seront incorrectes.

Considérations relatives à la sécurité des données

Consultez la rubrique Informations sensibles pour découvrir les données recueillies par l’Agent à partir de vos bases de données et la méthode à suivre pour garantir leur sécurité.

Configurer les paramètres MySQL

Pour recueillir des métriques de requête, des échantillons et des plans d’exécution, activez le schéma de performance MySQL et configurez les options connexes suivantes, que ce soit dans l’interface de ligne de commande ou dans les fichiers de configuration (comme mysql.conf) :

Remarque : nous vous recommandons d’autoriser l’Agent à activer les paramètres performance-schema-consumer-* de façon dynamique lors de l’exécution, durant l’étape d’attribution d’un accès à l’Agent. Consultez la rubrique Exécuter les consommateurs de configuration.

Accorder un accès à l’Agent

L’Agent Datadog requiert un accès en lecture seule pour la base de données, afin de pouvoir recueillir les statistiques et requêtes.

Les instructions suivantes autorisent l’Agent à se connecter depuis n’importe quel host à l’aide de datadog@'%'. Vous pouvez restreindre l’utilisateur datadog avec datadog@'localhost', de façon à ce qu’il soit uniquement autorisé à se connecter depuis localhost. Consultez la documentation MYSQL (en anglais) pour en savoir plus.

CREATE USER datadog@'%' IDENTIFIED by '<MOT_DE_PASSE_UNIQUE>';
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 USER datadog@'%' IDENTIFIED BY '<MOT_DE_PASSE_UNIQUE>';
GRANT REPLICATION CLIENT ON *.* TO datadog@'%' WITH MAX_USER_CONNECTIONS 5;
GRANT PROCESS ON *.* TO datadog@'%';
GRANT SELECT ON performance_schema.* TO datadog@'%';

Créez le schéma suivant :

CREATE SCHEMA IF NOT EXISTS datadog;
GRANT EXECUTE ON datadog.* to datadog@'%';
GRANT CREATE TEMPORARY TABLES ON datadog.* TO datadog@'%';

Créez la procédure explain_statement afin d’activer la collecte de plans d’exécution par l’Agent :

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 ;

Créez également la procédure suivante dans chaque schéma pour lesquels vous souhaitez recueillir des plans d’exécution. Remplacez <VOTRE_SCHÉMA> par le schéma de votre base de données :

DELIMITER $$
CREATE PROCEDURE <VOTRE_SCHÉMA>.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 <VOTRE_SCHÉMA>.explain_statement TO datadog@'%';

Exécuter les consommateurs de configuration

Datadog vous conseille de créer la procédure suivante afin d’autoriser l’Agent à activer les consommateurs performance_schema.events_* lors de l’exécution.

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@'%';

Installer l’Agent

L’installation de l’Agent Datadog entraîne également l’installation du check MySQL requis pour utiliser la solution Database Monitoring sur MySQL. Si vous n’avez pas encore installé l’Agent pour le host de votre base de données MySQL, consultez les instructions d’installation de l’Agent.

Pour configurer ce check lorsque l’Agent est exécuté sur un host :

Modifiez le fichier mysql.d/conf.yaml dans le dossier conf.d/ à la racine du répertoire de configuration de votre Agent pour commencer à recueillir vos métriques et logs MySQL. Consultez le fichier d’exemple mysql.d/conf.yaml pour découvrir toutes les options de configuration disponibles, y compris pour les métriques custom.

Collecte de métriques

Ajoutez ce bloc de configuration à votre fichier mysql.d/conf.yaml pour recueillir des métriques MySQL :

init_config:

instances:
  - dbm: true
    host: 127.0.0.1
    port: 3306
    username: datadog
    password: '<MOT_DE_PASSE_CHOISI>' # Le mot de passé créé auparavant lors de l'étape CREATE USER

Remarque : ajoutez des guillemets simples autour de votre mot de passe s’il contient un caractère spécial.

Notez que l’utilisateur datadog doit être défini dans la configuration de l’intégration MySQL en tant que host: 127.0.0.1 au lieu de localhost. Vous pouvez également utiliser sock.

Redémarrez l’Agent pour commencer à envoyer des métriques MySQL à Datadog.

Collecte de logs (facultatif)

Pour venir compléter la télémétrie recueillie depuis la base de données par l’Agent, vous pouvez envoyer directement à Datadog les logs de votre base de données.

1. Par défaut, MySQL enregistre tous ses logs dans /var/log/syslog, dont la lecture nécessite un accès root. Pour rendre les logs plus accessibles, voici les étapes à suivre :

   1. Modifiez /etc/mysql/conf.d/mysqld_safe_syslog.cnf et mettez en commentaire toutes les lignes.
   2. Modifiez /etc/mysql/my.cnf pour activer les paramètres de journalisation de votre choix. Par exemple, pour activer les logs globaux, d’erreur et de requêtes lentes, utilisez la configuration suivante :

     [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
   

   3. Enregistrez le fichier et redémarrez MySQL.
   4. Assurez-vous que l’Agent dispose d’une autorisation de lecture pour le répertoire /var/log/mysql et tous ses fichiers. Vérifiez votre configuration logrotate pour vous assurer que ces fichiers sont pris en compte et que les autorisations sont correctement définies. Dans /etc/logrotate.d/mysql-server, vous devriez voir des lignes similaires à ce qui suit :

     /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. La collecte de logs est désactivée par défaut dans l’Agent Datadog. Vous devez l’activer dans datadog.yaml :

   logs_enabled: true
   

3. Ajoutez ce bloc de configuration à votre fichier mysql.d/conf.yaml pour commencer à recueillir vos logs MySQL :

   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+
   

4. Redémarrez l’Agent.

Validation

Lancez la sous-commande status de l’Agent et cherchez mysql dans la section Checks. Vous pouvez également visiter la page Databases pour commencer à surveiller vos bases de données.

Exemple de configurations de l’Agent

One agent connecting to multiple hosts

It is common to configure a single Agent host to connect to multiple remote database instances (see Agent installation architectures for DBM). To connect to multiple hosts, create an entry for each host in the MySQL integration config. In these cases, Datadog recommends limiting the number of instances per Agent to a maximum of 10 database instances to guarantee reliable performance.

init_config:
instances:
  - dbm: true
    host: example-service-primary.example-host.com
    port: 3306
    username: datadog
    password: '<PASSWORD>'
    tags:
      - 'env:prod'
      - 'team:team-discovery'
      - 'service:example-service'
  - dbm: true
    host: example-service-replica-1.example-host.com
    port: 3306
    username: datadog
    password: '<PASSWORD>'
    options:
      replication: true
    tags:
      - 'env:prod'
      - 'team:team-discovery'
      - 'service:example-service'
  - dbm: true
    host: example-service-replica-2.example-host.com
    port: 3306
    username: datadog
    password: '<PASSWORD>'
    options:
      replication: true
    tags:
      - 'env:prod'
      - 'team:team-discovery'
      - 'service:example-service'
    [...]

Storing passwords securely

While it is possible to declare passwords directly in the Agent configuration files, it is a more secure practice to encrypt and store database credentials elsewhere using secret management software such as Vault. The Agent is able to read these credentials using the ENC[] syntax. Review the secrets management documentation for the required setup to store these credentials. The following example shows how to declare and use those credentials:

init_config:
instances:
  - dbm: true
    host: localhost
    port: 3306
    username: datadog
    password: 'ENC[datadog_user_database_password]'

Running custom queries

To collect custom metrics, use the custom_queries option. See the sample mysql.d/conf.yaml for more details.

init_config:
instances:
  - dbm: true
    host: localhost
    port: 3306
    username: datadog
    password: '<PASSWORD>'
    custom_queries:
    - query: SELECT age, salary, hours_worked, name FROM hr.employees;
      columns:
        - name: custom.employee_age
          type: gauge
        - name: custom.employee_salary
           type: gauge
        - name: custom.employee_hours
           type: count
        - name: name
           type: tag
      tags:
        - 'table:employees'

Working with hosts through a proxy

If the Agent must connect through a proxy such as the Cloud SQL Auth proxy, all telemetry is tagged with the hostname of the proxy rather than the database instance. Use the reported_hostname option to set a custom override of the hostname detected by the Agent.

init_config:
instances:
  - dbm: true
    host: localhost
    port: 5000
    username: datadog
    password: '<PASSWORD>'
    reported_hostname: example-service-primary
  - dbm: true
    host: localhost
    port: 5001
    username: datadog
    password: '<PASSWORD>'
    reported_hostname: example-service-replica-1

Dépannage

Si vous avez respecté les instructions d’installation et de configuration des intégrations et de l’Agent, mais que vous rencontrez un problème, consultez la section Dépannage.

Pour aller plus loin

Documentation, liens et articles supplémentaires utiles:

Intégration MySQL basiqueDOCUMENTATION