Database Monitoring proporciona una visibilidad profunda de tus bases de datos Postgres al exponer métricas de consultas, muestras de consultas, planes de explicación, estados de bases de datos, conmutaciones por error y eventos.

El Agente recopila telemetría directamente de la base de datos al iniciar sesión como un usuario de solo lectura. Realiza la siguiente configuración para habilitar Database Monitoring con tu base de datos Postgres:

1. Configura los parámetros de la base de datos
2. Otorga al Agente acceso a la base de datos
3. Instala el Agente

Antes de comenzar

Versiones de PostgreSQL soportadas

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

Requisitos previos

Los módulos adicionales suministrados de Postgres deben estar instalados. Para la mayoría de las instalaciones, esto se incluye por defecto, pero las instalaciones menos convencionales pueden requerir una instalación adicional de tu versión del paquete postgresql-contrib.

Versiones de Agente soportadas

7.36.1+

Impacto en el rendimiento La configuración predeterminada del Agente para Database Monitoring es conservadora, pero puedes ajustar parámetros como el intervalo de recolección y la tasa de muestreo de consultas para adaptarlas mejor a tus necesidades. Para la mayoría de las cargas de trabajo, el Agente representa menos del uno por ciento del tiempo de ejecución de consultas en la base de datos y menos del uno por ciento de la CPU.

Database Monitoring se ejecuta como una integración sobre el Agente base (ver benchmarks).

Proxies, balanceadores de carga y agrupadores de conexiones

El Agente de Datadog debe conectarse directamente al host que se está monitoreando. Para bases de datos autohospedadas, utiliza 127.0.0.1 o el socket. El Agente no debe conectarse a la base de datos a través de un proxy, balanceador de carga o agrupador de conexiones como pgbouncer. Si el Agente se conecta a diferentes hosts mientras está en funcionamiento (como en el caso de conmutación por error, balanceo de carga, etc.), el Agente calcula la diferencia en estadísticas entre dos hosts, produciendo métricas inexactas.

Consideraciones de seguridad de datos

Consulta Información sensible para obtener información sobre qué datos recopila el Agente de tus bases de datos y cómo asegurarte de que estén seguros.

Configura los ajustes de Postgres

Configura los siguientes parámetros en el archivo postgresql.conf y luego reinicia el servidor para que los ajustes surtan efecto. Para más información sobre estos parámetros, consulta la documentación de Postgres.

Parámetros requeridos

Parámetros opcionales

Otorga al Agente de Datadog acceso

El Agente de Datadog requiere acceso de solo lectura al servidor de base de datos para recopilar estadísticas y consultas.

Ejecute los siguientes comandos SQL en el servidor de base de datos primario (el escritor) en el clúster si Postgres está replicado. El Agente de Datadog puede recopilar telemetría de todas las bases de datos en el servidor, independientemente de a cuál base de datos se conecte. Utilice la base de datos postgres predeterminada a menos que necesite que el Agente de Datadog ejecute consultas personalizadas contra datos únicos de otra base de datos.

Conéctese a la base de datos elegida como superusuario (o otro usuario con permisos suficientes). Por ejemplo, para conectarse a la base de datos postgres usando psql:

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

Cree el usuario 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;

Cree la función del plan de explicación

Crea la siguiente función en cada base de datos para permitir que el Agente de Datadog recopile planes de explicación:

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;

Almacena tu contraseña de manera segura

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.

Verifica los permisos de la base de datos

Para verificar que los permisos son correctos, ejecuta los siguientes comandos para confirmar que el usuario del Agente de Datadog puede conectarse a la base de datos y leer las tablas 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"

Cuando se te pida una contraseña, utiliza la contraseña que ingresaste al crear el Agente de Datadog datadog.

Instala el Agente de Datadog

Instalar el Agente de Datadog también instala la verificación de Postgres, que es necesaria para el Monitoreo de Bases de Datos en Postgres. Si no has instalado el Agente, consulta las instrucciones de instalación del Agente. Luego, continúa con las instrucciones para tu método de instalación.

Edita el archivo conf.d/postgres.d/conf.yaml del Agente de Datadog para apuntar a la instancia de Postgres que deseas monitorear. Para una lista completa de opciones de configuración, consulta el ejemplo 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>'

Nota: Si tu contraseña incluye caracteres especiales, envuélvela en comillas simples.

Reinicia el Agente de Datadog para aplicar los cambios.

Recolección de registros (opcional)

El registro predeterminado de PostgreSQL es a stderr, y los registros no incluyen información detallada. Registra en un archivo con detalles adicionales especificados en el prefijo de la línea de registro. Consulta la documentación de PostgreSQL para más detalles.

1. La configuración de registro se realiza dentro del archivo /etc/postgresql/<VERSION>/main/postgresql.conf. Para resultados de registro regulares, incluyendo salidas de declaraciones, establece los siguientes parámetros en la sección de registro:

     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. Para recopilar métricas de duración detalladas y hacerlas buscables en la interfaz de Datadog, configúralas en línea con la declaración. La configuración recomendada a continuación registra todas las declaraciones y sus duraciones. Para reducir la salida a declaraciones que superen una cierta duración, establece log_min_duration_statement en el mínimo deseado en milisegundos. Verifica que registrar la declaración SQL completa cumpla con los requisitos de privacidad de tu organización.

   Nota: Ambas opciones log_statement y log_duration están comentadas. Consulta la discusión sobre este tema aquí.

     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 recopilación de registros está desactivada por defecto en el Agente de Datadog. Actívalo en tu archivo datadog.yaml:

   logs_enabled: true
   

4. Agrega y edita este bloque de configuración en tu archivo conf.d/postgres.d/conf.yaml para comenzar a recopilar tus registros de 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
   

   Cambie los valores de los parámetros service y path para configurarlos para su entorno. Consulta el ejemplo postgres.d/conf.yaml para todas las opciones de configuración disponibles.

5. Reinicie el Agent.

Recopilando planes con auto_explain (opcional)

Por defecto, el agente solo recopila EXPLAIN planes para una muestra de consultas en ejecución. Estos planes son de naturaleza más general, especialmente cuando el código de la aplicación utiliza declaraciones preparadas.

Para recopilar planes completos de EXPLAIN ANALYZE tomados de todas las consultas, necesitas usar auto_explain, una extensión propia incluida con PostgreSQL disponible en todos los proveedores principales. La recopilación de registros es un requisito previo para la recopilación de auto_explain, así que actívalo antes de continuar.

Después de habilitar la recolección de registros:

1. Agregue auto_explain a su lista de shared_preload_libraries en postgresql.conf. Por ejemplo, si shared_preload_libraries está configurado en pg_stat_statements, cámbielo a pg_stat_statements,auto_explain

2. Cambie el log_line_prefix para habilitar una correlación de eventos más rica. Este patrón es necesario para ingerir planes de auto_explain.

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

3. Configure los ajustes de auto_explain. El formato de registro debe ser json, pero otras configuraciones pueden variar dependiendo de su aplicación. Este ejemplo registra un EXPLAIN ANALYZE plan para todas las consultas que superan un segundo, incluyendo información de búfer pero omitiendo el tiempo (que puede tener sobrecarga).

    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. Reinicie el Agent.

Verifique la configuración del Agent

Ejecute el subcomando de estado del Agent y busque postgres en la sección de Checks. O visite la página de Databases para comenzar!

Ejemplos de Configuraciones del 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

Solución de problemas

Si has instalado y configurado las integraciones y el Agent como se describe y no está funcionando como se esperaba, consulta Solución de problemas.

Lectura adicional

Más enlaces, artículos y documentación útiles:

Integración básica de PostgresDOCUMENTACIÓN Capturando valores de parámetros de consultas SQLDOCUMENTACIÓN Depura la latencia de consultas de PostgreSQL más rápido con EXPLAIN ANALYZE en Database Monitoring de Datadog.BLOG