Note: When generating custom metrics that require querying additional tables, you may need to grant the SELECT permission on those tables to the datadog user. Example: grant SELECT on <TABLE_NAME> to datadog;. Check the FAQ section for more information.

Host

To configure this check for an Agent running on a host:

Metric collection

1. Edit the postgres.d/conf.yaml file to point to your host / port and set the masters to monitor. See the sample postgres.d/conf.yaml for all available configuration options.

   init_config:
   
   instances:
     ## @param host - string - required
     ## The hostname to connect to.
     ## NOTE: Even if the server name is "localhost", the agent connects to
     ## PostgreSQL using TCP/IP, unless you also provide a value for the sock key.
     #
     - host: localhost
   
       ## @param port - integer - required
       ## Port to use when connecting to PostgreSQL.
       #
       port: 5432
   
       ## @param user - string - required
       ## Datadog Username created to connect to PostgreSQL.
       #
       username: datadog
   
       ## @param pass - string - required
       ## Password associated with the Datadog user.
       #
       password: "<PASSWORD>"
   
       ## @param dbname - string - optional - default: postgres
       ## Name of the PostgresSQL database to monitor.
       ## Note: If omitted, the default system postgres database is queried.
       #
       dbname: "<DB_NAME>"
   
       # @param disable_generic_tags - boolean - optional - default: false
       # The integration will stop sending server tag as is redundant with host tag
       disable_generic_tags: true
   

2. To collect relation metrics, connect the Agent to every logical database. These databases can be discovered automatically, or each one can be listed explicitly in the configuration.

   • To discover logical databases automatically on a given instance, enable autodiscovery on that instance:

   instances:
     - host: localhost
       port: 5432
       database_autodiscovery:
         enabled: true
         # Optionally, set the include field to specify
         # a set of databases you are interested in discovering
         include:
           - mydb.*
           - example.*
       relations:
         - relation_regex: .*
   

   • Alternatively, you can list each logical database as an instance in the configuration:

   instances:
     - host: example-service-primary.example-host.com
       port: 5432
       username: datadog
       password: '<PASSWORD>'
       relations:
         - relation_name: products
         - relation_name: external_seller_products
     - host: example-service-replica-1.example-host.com
       port: 5432
       username: datadog
       password: '<PASSWORD>'
       relations:
         - relation_regex: inventory_.*
           relkind:
             - r
             - i
     - host: example-service-replica-2.example-host.com
       port: 5432
       username: datadog
       password: '<PASSWORD>'
       relations:
         - relation_regex: .*
   

3. Restart the Agent.

Trace collection

Datadog APM integrates with Postgres to see the traces across your distributed system. Trace collection is enabled by default in the Datadog Agent v6+. To start collecting traces:

1. Enable trace collection in Datadog.
2. Instrument your application that makes requests to Postgres.

Log collection

Available for Agent versions >6.0

PostgreSQL default logging is to stderr, and logs do not include detailed information. It is recommended to log into a file with additional details specified in the log line prefix. See the PostgreSQL documentation onError Reporting and Logging for more information.

1. Logging is configured within the file /etc/postgresql/<VERSION>/main/postgresql.conf. For regular log results, including statement outputs, uncomment the following parameters in the log section:

     logging_collector = on
     log_directory = 'pg_log'  # directory where log files are written,
                               # can be absolute or relative to PGDATA
     log_filename = 'pg.log'   # log file name, can include pattern
     log_statement = 'all'     # log all queries
     #log_duration = on
     log_line_prefix= '%m [%p] %d %a %u %h %c '
     log_file_mode = 0644
     ## For Windows
     #log_destination = 'eventlog'
   

2. To gather detailed duration metrics and make them searchable in the Datadog interface, they should be configured inline with the statement themselves. See below for the recommended configuration differences from above. Note: Both log_statement and log_duration options are commented out. See Logging statement/duration on the same line for discussion on this topic.

   This config logs all statements. To reduce the output based on duration, set the log_min_duration_statement value to the desired minimum duration (in milliseconds):

     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. Collecting logs is disabled by default in the Datadog Agent, enable it in your datadog.yaml file:

   logs_enabled: true
   

4. Add and edit this configuration block to your postgres.d/conf.yaml file to start collecting your PostgreSQL logs:

   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
   

   Change the service and path parameter values to configure for your environment. See the sample postgres.d/conf.yaml for all available configuration options.

5. Restart the Agent.

Docker

To configure this check for an Agent running on a container:

Metric collection

Set Autodiscovery Integrations Templates as Docker labels on your application container:

LABEL "com.datadoghq.ad.check_names"='["postgres"]'
LABEL "com.datadoghq.ad.init_configs"='[{}]'
LABEL "com.datadoghq.ad.instances"='[{"host":"%%host%%", "port":5432,"username":"datadog","password":"<PASSWORD>"}]'

Log collection

Collecting logs is disabled by default in the Datadog Agent. To enable it, see Docker Log Collection.

Then, set Log Integrations as Docker labels:

LABEL "com.datadoghq.ad.logs"='[{"source":"postgresql","service":"postgresql"}]'

Trace collection

APM for containerized apps is supported on Agent v6+ but requires extra configuration to begin collecting traces.

Required environment variables on the Agent container:

See Tracing Docker Applications for a complete list of available environment variables and configuration.

Then, instrument your application container that makes requests to Postgres and set DD_AGENT_HOST to the name of your Agent container.

Kubernetes

To configure this check for an Agent running on Kubernetes:

Metric collection

Set Autodiscovery Integrations Templates as pod annotations on your application container. Aside from this, templates can also be configured with a file, a configmap, or a key-value store.

Annotations v1 (for Datadog Agent < v7.36)

apiVersion: v1
kind: Pod
metadata:
  name: postgres
  annotations:
    ad.datadoghq.com/postgresql.check_names: '["postgres"]'
    ad.datadoghq.com/postgresql.init_configs: '[{}]'
    ad.datadoghq.com/postgresql.instances: |
      [
        {
          "host": "%%host%%",
          "port":"5432",
          "username":"datadog",
          "password":"<PASSWORD>"
        }
      ]      
spec:
  containers:
    - name: postgres

Annotations v2 (for Datadog Agent v7.36+)

apiVersion: v1
kind: Pod
metadata:
  name: postgres
  annotations:
    ad.datadoghq.com/postgres.checks: |
      {
        "postgres": {
          "init_config": {},
          "instances": [
            {
              "host": "%%host%%",
              "port":"5432",
              "username":"datadog",
              "password":"<PASSWORD>"
            }
          ]
        }
      }      
spec:
  containers:
    - name: postgres

Log collection

Collecting logs is disabled by default in the Datadog Agent. To enable it, see Kubernetes Log Collection.

Then, set Log Integrations as pod annotations. This can also be configured with a file, a configmap, or a key-value store.

Annotations v1/v2

apiVersion: v1
kind: Pod
metadata:
  name: postgres
  annotations:
    ad.datadoghq.com/postgres.logs: '[{"source":"postgresql","service":"<SERVICE_NAME>"}]'
spec:
  containers:
    - name: postgres

Trace collection

APM for containerized apps is supported on hosts running Agent v6+ but requires extra configuration to begin collecting traces.

Required environment variables on the Agent container:

See Tracing Kubernetes Applications and the Kubernetes DaemonSet Setup for a complete list of available environment variables and configuration.

Then, instrument your application container that makes requests to Postgres.

ECS

To configure this check for an Agent running on ECS:

Metric collection

Set Autodiscovery Integrations Templates as Docker labels on your application container:

{
  "containerDefinitions": [{
    "name": "postgres",
    "image": "postgres:latest",
    "dockerLabels": {
      "com.datadoghq.ad.check_names": "[\"postgres\"]",
      "com.datadoghq.ad.init_configs": "[{}]",
      "com.datadoghq.ad.instances": "[{\"host\":\"%%host%%\", \"port\":5432,\"username\":\"datadog\",\"password\":\"<PASSWORD>\"}]"
    }
  }]
}

Log collection

Collecting logs is disabled by default in the Datadog Agent. To enable it, see ECS Log Collection.

Then, set Log Integrations as Docker labels:

{
  "containerDefinitions": [{
    "name": "postgres",
    "image": "postgres:latest",
    "dockerLabels": {
      "com.datadoghq.ad.logs": "[{\"source\":\"postgresql\",\"service\":\"postgresql\"}]"
    }
  }]
}

Trace collection

APM for containerized apps is supported on Agent v6+ but requires extra configuration to begin collecting traces.

Required environment variables on the Agent container:

See Tracing Docker Applications for a complete list of available environment variables and configuration.

Then, instrument your application container that makes requests to Postgres and set DD_AGENT_HOST to the EC2 private IP address.