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 les données de télémétrie directement depuis la base de données, en se connectant en tant qu’utilisateur en lecture seule. Effectuez la configuration suivante pour activer la surveillance de base de données avec votre base de données Postgres :

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

Avant de commencer

Versions PostgreSQL prises en charge

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

Prérequis

Des modules supplémentaires fournis par Postgres doivent être installés. Pour la plupart des installations, cela est inclus par défaut, mais les installations moins conventionnelles peuvent nécessiter une installation supplémentaire de votre version du package postgresql-contrib.

Versions de l’Agent prises en charge

7.36.1+

Impact sur la performance

La configuration par défaut de l’Agent pour la surveillance de base de données est conservatrice, mais vous pouvez ajuster des paramètres tels que l’intervalle de collecte et le taux d’échantillonnage des requêtes pour mieux répondre à vos besoins. Pour la plupart des charges de travail, l’Agent représente 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 surveillance de base de données fonctionne comme une intégration au-dessus de l’Agent de base (voir les benchmarks).

Proxies, équilibreurs de charge et gestionnaires de connexions

L’Agent Datadog doit se connecter directement à l’hôte surveillé. Pour les bases de données auto-hébergées, utilisez 127.0.0.1 ou le socket. L’Agent ne doit pas se connecter à la base de données via un proxy, un équilibreur de charge ou un pool de connexions tel que pgbouncer. Si l’Agent se connecte à différents hôtes pendant son fonctionnement (comme dans le cas d’un basculement, d’un équilibrage de charge, etc.), l’Agent calcule la différence de statistiques entre deux hôtes, produisant des métriques inexactes.

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

Voir Informations sensibles pour des informations sur les données que l’Agent collecte de vos bases de données et comment s’assurer qu’elles sont sécurisées.

Configurer les paramètres Postgres

Configurez les paramètres suivants dans le fichier postgresql.conf puis redémarrez le serveur pour que les paramètres prennent effet. Pour plus d’informations sur ces paramètres, consultez la documentation Postgres.

Paramètres requis

Paramètres optionnels

Accorder l’accès à l’Agent

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

Exécutez les commandes SQL suivantes sur le serveur de base de données principal (le nœud d’écriture) dans le cluster, si Postgres est répliqué. L’Agent peut collecter la télémétrie de toutes les bases de données sur le serveur, peu importe à quelle base de données il se connecte. Utilisez la base de données par défaut postgres à moins que vous n’ayez besoin que l’Agent exécute des requêtes personnalisées sur des données uniques à une autre base de données.

Connectez-vous à votre base de données choisie en tant que superutilisateur (ou un autre utilisateur avec des autorisations suffisantes). Par exemple, pour se connecter à la base de données postgres en utilisant 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 de plan d’explication

Créez la fonction suivante dans chaque base de données pour permettre à l’Agent de collecter des plans d’explication :

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;

Stockez votre mot de passe en toute sécurité

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érifiez les autorisations de la base de données

Pour vérifier que les permissions sont correctes, exécutez les commandes suivantes pour confirmer que l’utilisateur Agent est capable de se connecter à la base de données et lire les tables principales :

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 datadog.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 datadog.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"

Lorsqu’il vous demande un mot de passe, utilisez le mot de passe que vous avez saisi lors de la création de l’utilisateur datadog.

Installez l’Agent

L’installation de l’Agent Datadog installe également le contrôle Postgres, qui est requis pour la surveillance des bases de données sur Postgres. Si vous n’avez pas installé l’Agent, consultez les instructions d’installation de l’Agent. Ensuite, continuez avec les instructions pour votre méthode d’installation.

Modifiez le fichier conf.d/postgres.d/conf.yaml de l’Agent pour pointer vers l’instance Postgres que vous souhaitez surveiller. Pour une liste complète des options de configuration, consultez l’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, entourez-le de guillemets simples.

Redémarrez l’Agent pour appliquer les modifications.

Collecte des journaux (optionnel)

La journalisation par défaut de PostgreSQL est à stderr, et les journaux ne contiennent pas d’informations détaillées. Enregistrez dans un fichier avec des détails supplémentaires spécifiés dans le préfixe de la ligne de journal. Consultez la documentation de PostgreSQL pour plus de détails.

1. La journalisation est configurée dans le fichier /etc/postgresql/<VERSION>/main/postgresql.conf. Pour des résultats de journal réguliers, y compris les sorties des instructions, définissez les paramètres suivants dans la section des journaux :

     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 rendre consultables dans l’interface Datadog, configurez-les en ligne avec l’instruction. La configuration recommandée ci-dessous journalise toutes les instructions et leurs durées. Pour réduire la sortie aux instructions dépassant une certaine durée, définissez log_min_duration_statement sur le minimum souhaité en millisecondes. Vérifiez que l’enregistrement de l’instruction SQL complète respecte les exigences de confidentialité de votre organisation.

   Remarque : Les options log_statement et log_duration sont commentées. Voir la discussion sur ce sujet ici.

     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 des journaux est désactivée par défaut dans l’Agent Datadog. Activez-le dans votre fichier datadog.yaml :

   logs_enabled: true
   

4. Ajoutez et modifiez ce bloc de configuration dans votre fichier conf.d/postgres.d/conf.yaml pour commencer à collecter vos journaux 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
   

   Changez les valeurs des paramètres service et path pour configurer votre environnement. Consultez l’exemple postgres.d/conf.yaml pour toutes les options de configuration disponibles.

5. Redémarrez l’Agent.

Collecte des plans avec auto_explain (optionnel)

Par défaut, l’agent ne collecte que les plans EXPLAIN pour un échantillonnage de requêtes en cours d’exécution. Ces plans sont de nature plus générale, surtout lorsque le code de l’application utilise des instructions préparées.

Pour collecter des plans EXPLAIN ANALYZE complets issus de toutes les requêtes, vous devez utiliser auto_explain, une extension de première partie fournie avec PostgreSQL disponible chez tous les principaux fournisseurs. La collecte des journaux est une condition préalable à la collecte de auto_explain, donc activez-la avant de continuer.

Après avoir activé la collecte des journaux :

1. Ajoutez auto_explain à votre liste de shared_preload_libraries dans postgresql.conf. Par exemple, si shared_preload_libraries est défini sur pg_stat_statements, changez-le en pg_stat_statements,auto_explain.

2. Changez le log_line_prefix pour activer une corrélation d’événements plus riche. Ce modèle est requis pour ingérer des plans auto_explain.

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

3. Configurez les paramètres de auto_explain. Le format de journal _ doit_ être json, mais d’autres paramètres peuvent varier en fonction de votre application. Cet exemple enregistre un plan EXPLAIN ANALYZE pour toutes les requêtes de plus d’une seconde, y compris les informations de tampon, mais omettant le timing (qui peut entraîner un surcoût).

    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.

Vérifiez la configuration de l’Agent

Exécutez la sous-commande d’état de l’Agent et recherchez postgres dans la section Vérifications. Ou visitez la page Bases de données pour commencer !

Exemples de configurations d’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 installé et configuré les intégrations et l’Agent comme décrit et que cela ne fonctionne pas comme prévu, consultez Dépannage.

Lectures complémentaires

Documentation, liens et articles supplémentaires utiles:

Intégation Postgres basiqueDOCUMENTATION Capturer les valeurs des paramètres de requête SQLDOCUMENTATION Déboguer la latence des requêtes PostgreSQL plus rapidement avec EXPLAIN ANALYZE dans la surveillance de base de données DatadogBLOG