La solution Database Monitoring vous permet de bénéficier d’une visibilité complète sur vos bases de données Postgres, en exposant des métriques de requête, des échantillons de requête, des plans d’exécution, des états, des failovers et des événements de base de données.

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 Postgres :

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 PostgreSQL prises en charge

9.6, 10, 11, 12, 13, 14, 15, 16, 17, 18

Prérequis

Des modules Postgres supplémentaires doivent être installés. Ils sont fournis par défaut pour la plupart des installations. Pour les installations peu courantes, il est possible que vous deviez installer votre version du package postgresql-contrib.

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 poolers de connexion

L’Agent Datadog doit se connecter directement au host surveillé. Pour les bases de données auto-hébergées, 127.0.0.1 ou le socket est préférable. L’Agent ne doit pas se connecter à la base de données via un proxy, un répartiteur de charge ou un pooler de connexion tel que pgbouncer. Si l’Agent se connecte à différents hosts pendant son exécution (comme dans le cas d’un basculement, d’un équilibrage de charge, etc.), il calcule la différence de statistiques entre deux hosts, ce qui produit des métriques inexactes.

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 Postgres

Configurez les paramètres suivants dans le fichier postgresql.conf. Redémarrez ensuite le serveur pour appliquer la configuration. Pour en savoir plus sur ces paramètres, consultez la documentation Postgres (en anglais).

Accorder un accès à l’Agent

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

Les commandes SQL suivantes doivent être exécutées sur le serveur de base de données primaire (le writer) du cluster si Postgres est répliqué. Choisissez une base de données PostgreSQL sur le serveur de base de données à laquelle l’Agent se connectera. L’Agent peut collecter des données de télémétrie depuis toutes les bases de données du serveur de base de données, quelle que soit celle à laquelle il se connecte ; il est donc conseillé d’utiliser la base de données postgres par défaut. Ne choisissez une base de données différente que si vous avez besoin que l’Agent exécute des requêtes custom sur des données propres à cette base de données.

Connectez-vous à la base de données en tant que super-utilisateur (ou en tant qu’un autre utilisateur avec les autorisations nécessaires). Par exemple, pour la base de données postgres, exécutez ce qui suit pour vous connecter en tant qu’utilisateur postgres avec psql :

psql -h mydb.example.com -d postgres -U postgres

Créez l’utilisateur datadog :

CREATE USER datadog WITH password '<PASSWORD>';

ALTER ROLE datadog INHERIT;

CREATE SCHEMA datadog;
GRANT USAGE ON SCHEMA datadog TO datadog;
GRANT USAGE ON SCHEMA public TO datadog;
GRANT pg_monitor TO datadog;
CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

CREATE SCHEMA datadog;
GRANT USAGE ON SCHEMA datadog TO datadog;
GRANT USAGE ON SCHEMA public TO datadog;
GRANT pg_monitor TO datadog;
CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

CREATE SCHEMA datadog;
GRANT USAGE ON SCHEMA datadog TO datadog;
GRANT USAGE ON SCHEMA public TO datadog;
GRANT SELECT ON pg_stat_database TO datadog;
CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

CREATE OR REPLACE FUNCTION datadog.pg_stat_activity() RETURNS SETOF pg_stat_activity AS
  $$ SELECT * FROM pg_catalog.pg_stat_activity; $$
LANGUAGE sql
SECURITY DEFINER;
CREATE OR REPLACE FUNCTION datadog.pg_stat_statements() RETURNS SETOF pg_stat_statements AS
    $$ SELECT * FROM pg_stat_statements; $$
LANGUAGE sql
SECURITY DEFINER;

Créez la fonction dans chaque base de données pour permettre à l’Agent de recueillir les plans d’exécution.

CREATE OR REPLACE FUNCTION datadog.explain_statement(
   l_query TEXT,
   OUT explain JSON
)
RETURNS SETOF JSON AS
$$
DECLARE
curs REFCURSOR;
plan JSON;

BEGIN
   SET TRANSACTION READ ONLY;

   OPEN curs FOR EXECUTE pg_catalog.concat('EXPLAIN (FORMAT JSON) ', l_query);
   FETCH curs INTO plan;
   CLOSE curs;
   RETURN QUERY SELECT plan;
END;
$$
LANGUAGE 'plpgsql'
RETURNS NULL ON NULL INPUT
SECURITY DEFINER;

Stocker votre mot de passe de manière sécurisée

Store your password using secret management software such as Vault. You can then reference this password as ENC[<SECRET_NAME>] in your Agent configuration files: for example, ENC[datadog_user_database_password]. See Secrets Management for more information.

The examples on this page use datadog_user_database_password to refer to the name of the secret where your password is stored. It is possible to reference your password in plain text, but this is not recommended.

Vérification

Pour vérifier que l’utilisateur de l’Agent possède les autorisations adéquates et qu’il parvient à se connecter à la base de données et à lire les principales tables, exécutez ce qui suit :

psql -h localhost -U datadog postgres -A \
  -c "select * from pg_stat_database limit 1;" \
  && echo -e "\e[0;32mPostgres connection - OK\e[0m" \
  || echo -e "\e[0;31mCannot connect to Postgres\e[0m"
psql -h localhost -U datadog postgres -A \
  -c "select * from pg_stat_activity limit 1;" \
  && echo -e "\e[0;32mPostgres pg_stat_activity read OK\e[0m" \
  || echo -e "\e[0;31mCannot read from pg_stat_activity\e[0m"
psql -h localhost -U datadog postgres -A \
  -c "select * from pg_stat_statements limit 1;" \
  && echo -e "\e[0;32mPostgres pg_stat_statements read OK\e[0m" \
  || echo -e "\e[0;31mCannot read from pg_stat_statements\e[0m"

psql -h localhost -U datadog postgres -A \
  -c "select * from pg_stat_database limit 1;" \
  && echo -e "\e[0;32mPostgres connection - OK\e[0m" \
  || echo -e "\e[0;31mCannot connect to Postgres\e[0m"
psql -h localhost -U datadog postgres -A \
  -c "select * from pg_stat_activity limit 1;" \
  && echo -e "\e[0;32mPostgres pg_stat_activity read OK\e[0m" \
  || echo -e "\e[0;31mCannot read from pg_stat_activity\e[0m"
psql -h localhost -U datadog postgres -A \
  -c "select * from pg_stat_statements limit 1;" \
  && echo -e "\e[0;32mPostgres pg_stat_statements read OK\e[0m" \
  || echo -e "\e[0;31mCannot read from pg_stat_statements\e[0m"

Lorsque vous êtes invité à saisir un mot de passe, indiquez celui que vous avez défini lors de la création de l’utilisateur datadog.

Installer l’Agent

L’installation de l’Agent Datadog installe également le check Postgres, requis pour Database Monitoring sur Postgres. Si vous n’avez pas encore installé l’Agent, consultez les instructions d’installation de l’Agent. Revenez ensuite ici pour continuer avec les instructions correspondant à votre méthode d’installation.

Modifiez le fichier conf.d/postgres.d/conf.yaml de l’Agent pour le faire pointer vers l’instance Postgres que vous souhaitez surveiller. Pour obtenir la liste complète des options de configuration, consultez le fichier d’exemple postgres.d/conf.yaml.

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

  ## Optional: Connect to a different database if needed for `custom_queries`
  # dbname: '<DB_NAME>'

Remarque : si votre mot de passe contient des caractères spéciaux, placez-le entre guillemets simples.

Redémarrez l’Agent pour appliquer les modifications.

Collecte de logs (facultatif)

Par défaut, les logs PostgreSQL sont envoyés vers stderr et n’incluent aucune information détaillée. Il est conseillé d’enregistrer les logs dans un fichier en ajoutant des détails supplémentaires spécifiés en tant que préfixe dans la ligne de log. Consultez la documentation PostgresSQL (en anglais) à ce sujet pour en savoir plus.

1. La journalisation est configurée dans le fichier /etc/postgresql/<VERSION>/main/postgresql.conf. Pour obtenir des résultats de log standard, y compris les sorties des requêtes, définissez les paramètres suivants dans la section log :

     logging_collector = on
     log_line_prefix = '%m [%p] %d %a %u %h %c ' # this pattern is required to correlate metrics in the Datadog product
     log_file_mode = 0644
   
     ## For Windows
     #log_destination = 'eventlog'
   

2. Pour recueillir des métriques de durée détaillées et les rechercher depuis l’interface Datadog, vous devez les configurer directement au sein des déclarations. Comparez la configuration recommandée qui suit avec celle ci-dessus : vous noterez que dans les deux cas, les options log_statement et log_duration ont été mises en commentaire. Pour en savoir plus à ce sujet, consultez cette discussion.

   Cette configuration enregistre toutes les déclarations dans les logs, mais vous avez la possibilité d’enregistrer uniquement les déclarations qui dépassent une certaine durée en définissant la valeur log_min_duration_statement sur la durée minimum souhaitée en millisecondes (assurez-vous que l’enregistrement des déclarations SQL complètes est conforme aux exigences de confidentialité de votre organisation) :

     log_min_duration_statement = 0    # -1 is disabled, 0 logs all statements
                                       # and their durations, > 0 logs only
                                       # statements running at least this number
                                       # of milliseconds
     #log_statement = 'all'
     #log_duration = on
   

3. 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
   

4. Ajoutez ce bloc de configuration à votre fichier conf.d/postgres.d/conf.yaml et modifiez-le pour commencer à recueillir vos logs PostgreSQL :

   logs:
     - type: file
       path: "<LOG_FILE_PATH>"
       source: postgresql
       service: "<SERVICE_NAME>"
       #To handle multi line that starts with yyyy-mm-dd use the following pattern
       #log_processing_rules:
       #  - type: multi_line
       #    pattern: \d{4}\-(0?[1-9]|1[012])\-(0?[1-9]|[12][0-9]|3[01])
       #    name: new_log_start_with_date
   

   Modifiez les valeurs des paramètres path et service en fonction de votre environnement. Consultez le fichier d’exemple postgres.d/conf.yaml pour découvrir toutes les options de configuration disponibles.

5. Redémarrez l’Agent.

Collecte de plans avec auto_explain (facultatif)

Par défaut, l’Agent ne recueille des plans EXPLAIN que pour un échantillon de requêtes en cours d’exécution. Ces plans sont de nature plus générale, notamment lorsque le code de l’application utilise des requêtes préparées.

Pour collecter les plans EXPLAIN ANALYZE complets à partir de toutes les requêtes, vous devez utiliser auto_explain, une extension native fournie avec PostgreSQL et disponible chez tous les principaux fournisseurs. La collecte de logs est un prérequis à la collecte auto_explain, veillez donc à l’activer avant de continuer.

Une fois la collecte de logs activée :

1. Ajoutez auto_explain à votre liste shared_preload_libraries dans postgresql.conf. Par exemple, si shared_preload_libraries est défini sur pg_stat_statements, le remplacer par pg_stat_statements,auto_explain

2. Modifiez le paramètre log_line_prefix pour permettre une corrélation d’événements plus riche. Ce pattern est requis pour ingérer les plans auto_explain.

     log_line_prefix = '%m:%r:%u@%d:[%p]:%l:%e:%s:%v:%x:%c:%q%a:'
   

3. Configurez les paramètres auto_explain. Le format de log doit être json, mais les autres paramètres peuvent varier en fonction de votre application. Cet exemple enregistre un plan EXPLAIN ANALYZE dans les logs pour toutes les requêtes dépassant une seconde, y compris les informations relatives aux tampons, mais en omettant les informations de temporisation (ce qui peut engendrer une surcharge).

    auto_explain.log_format: "json"
    auto_explain.log_min_duration: "1000"
    auto_explain.log_analyze: "on"
    auto_explain.log_buffers: "on"
    auto_explain.log_timing: "off"
    auto_explain.log_triggers: "on"
    auto_explain.log_verbose: "on"
    auto_explain.log_nested_statements: "on"
    auto_explain.sample_rate: "1"
   

4. Redémarrez l’Agent.

Validation

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

Exemples de configuration 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 Postgres integration config.

init_config:
instances:
  - dbm: true
    host: example-service-primary.example-host.com
    port: 5432
    username: datadog
    password: 'ENC[datadog_user_database_password]'
    tags:
      - 'env:prod'
      - 'team:team-discovery'
      - 'service:example-service'
  - dbm: true
    host: example-service–replica-1.example-host.com
    port: 5432
    username: datadog
    password: 'ENC[datadog_user_database_password]'
    tags:
      - 'env:prod'
      - 'team:team-discovery'
      - 'service:example-service'
  - dbm: true
    host: example-service–replica-2.example-host.com
    port: 5432
    username: datadog
    password: 'ENC[datadog_user_database_password]'
    tags:
      - 'env:prod'
      - 'team:team-discovery'
      - 'service:example-service'
    [...]

Monitoring multiple databases on a database host

Use the database_autodiscovery option to permit the Agent to discover all databases on your host to monitor. You can specify include or exclude fields to narrow the scope of databases discovered. See the sample postgres.d/conf.yaml for more details.

init_config:
instances:
  - dbm: true
    host: example-service-primary.example-host.com
    port: 5432
    username: datadog
    password: 'ENC[datadog_user_database_password]'
    database_autodiscovery:
      enabled: true
      # Optionally, set the include field to specify
      # a set of databases you are interested in discovering
      include:
        - mydb.*
        - example.*
    tags:
      - 'env:prod'
      - 'team:team-discovery'
      - 'service:example-service'

Running custom queries

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

init_config:
instances:
  - dbm: true
    host: localhost
    port: 5432
    username: datadog
    password: 'ENC[datadog_user_database_password]'
    custom_queries:
    - metric_prefix: employee
      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'

Monitoring relation metrics for multiple databases

In order to collect relation metrics (such as postgresql.seq_scans, postgresql.dead_rows, postgresql.index_rows_read, and postgresql.table_size), the Agent must be configured to connect to each database (by default, the Agent only connects to the postgres database).

Specify a single “DBM” instance to collect DBM telemetry from all databases. Use the database_autodiscovery option to avoid specifying each database name.

init_config:
instances:
  # This instance is the "DBM" instance. It will connect to the
  # all logical databases, and send DBM telemetry from all databases
  - dbm: true
    host: example-service-primary.example-host.com
    port: 5432
    username: datadog
    password: 'ENC[datadog_user_database_password]'
    database_autodiscovery:
      enabled: true
      exclude:
        - ^users$
        - ^inventory$
    relations:
      - relation_regex: .*
  # This instance only collects data from the `users` database
  # and collects relation metrics from tables prefixed by "2022_"
  - host: example-service-primary.example-host.com
    port: 5432
    username: datadog
    password: 'ENC[datadog_user_database_password]'
    dbname: users
    dbstrict: true
    relations:
      - relation_regex: 2022_.*
        relkind:
          - r
          - i
  # This instance only collects data from the `inventory` database
  # and collects relation metrics only from the specified tables
  - host: example-service-primary.example-host.com
    port: 5432
    username: datadog
    password: 'ENC[datadog_user_database_password]'
    dbname: inventory
    dbstrict: true
    relations:
      - relation_name: products
      - relation_name: external_seller_products

Collecting schemas

To enable this feature, use the collect_schemas option. You must also configure the Agent to connect to each logical database.

Use the database_autodiscovery option to avoid specifying each logical database. See the sample postgres.d/conf.yaml for more details.

init_config:
# This instance only collects data from the `users` database
# and collects relation metrics only from the specified tables
instances:
  - dbm: true
    host: example-service-primary.example-host.com
    port: 5432
    username: datadog
    password: 'ENC[datadog_user_database_password]'
    dbname: users
    dbstrict: true
    collect_schemas:
      enabled: true
    relations:
      - products
      - external_seller_products
  # This instance detects every logical database automatically
  # and collects relation metrics from every table
  - dbm: true
    host: example-service–replica-1.example-host.com
    port: 5432
    username: datadog
    password: 'ENC[datadog_user_database_password]'
    database_autodiscovery:
      enabled: true
    collect_schemas:
      enabled: true
    relations:
      - relation_regex: .*

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: 'ENC[datadog_user_database_password]'
    reported_hostname: example-service-primary
  - dbm: true
    host: localhost
    port: 5001
    username: datadog
    password: 'ENC[datadog_user_database_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égation Postgres basiqueDOCUMENTATION Capture des valeurs de paramètres de requêtes SQLDOCUMENTATION Déboguer plus rapidement la latence des requêtes PostgreSQL avec EXPLAIN ANALYZE dans Datadog Database MonitoringBLOG