PGBouncer

Supported OS Linux Mac OS

Integration version6.2.0

Overview

The PgBouncer check tracks connection pool metrics and lets you monitor traffic to and from your application.

Setup

Installation

The PgBouncer check is included in the Datadog Agent package, so you don’t need to install anything else on your PgBouncer nodes.

This check needs an associated user to query your PgBouncer instance:

  1. Create a Datadog user in your PgBouncer pgbouncer.ini file:

    stats_users = datadog
    
  2. Add an associated password for the datadog user in your PgBouncer userlist.txt file:

    "datadog" "<PASSWORD>"
    
  3. To verify the credentials, run the following command:

    psql -h localhost -U datadog -p 6432 pgbouncer -c \
    "SHOW VERSION;" \
    && echo -e "\e[0;32mpgBouncer connection - OK\e[0m" \
    || echo -e "\e[0;31mCannot connect to pgBouncer\e[0m"
    

    When it prompts for a password, enter the password you added to the userlist.txt.

Configuration

Host

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

Metric collection
  1. Edit the pgbouncer.d/conf.yaml file, in the conf.d/ folder at the root of your Agent’s configuration directory. See the sample pgbouncer.d/conf.yaml for all available configuration options:

    init_config:
    
    instances:
      ## @param database_url - string - required
      ## `database_url` parameter should point to PgBouncer stats database url (ie. "pgbouncer")
      #
      - database_url: "postgresql://datadog:<PASSWORD>@<HOSTNAME>:<PORT>/<DATABASE_URL>?sslmode=require"
    

    Note: If your instance of PgBouncer does not have SSL support, replace sslmode=require with sslmode=allow to avoid server errors. For details, see the Postgres documentation on SSL support.

  2. Restart the Agent.

Log collection

Available for Agent versions >6.0

  1. Collecting logs is disabled by default in the Datadog Agent, enable it in your datadog.yaml file:

    logs_enabled: true
    
  2. Add this configuration block to your pgbouncer.d/conf.yaml file to start collecting your Pgbouncer logs:

    logs:
      - type: file
        path: /var/log/postgresql/pgbouncer.log
        source: pgbouncer
        service: "<SERVICE_NAME>"
    

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

  3. Restart the Agent.

Containerized

For containerized environments, see the Autodiscovery Integration Templates for guidance on applying the parameters below.

Metric collection
ParameterValue
<INTEGRATION_NAME>pgbouncer
<INIT_CONFIG>blank or {}
<INSTANCE_CONFIG>{"database_url": "postgresql://datadog:<PASSWORD>@%%host%%:%%port%%/<DATABASE_URL>?sslmode=require"}
Log collection

Available for Agent versions >6.0

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

ParameterValue
<LOG_CONFIG>{“source”: “pgbouncer”, “service”: “pgbouncer”}

Validation

Run the Agent’s status subcommand and look for pgbouncer under the Checks section.

Data Collected

Metrics

pgbouncer.clients.connect_time
(gauge)
When the connection was made (seconds since epoch)
Shown as second
pgbouncer.clients.request_time
(gauge)
When last request was issued (seconds since epoch)
Shown as second
pgbouncer.clients.wait
(gauge)
Current waiting time in seconds
Shown as second
pgbouncer.clients.wait_us
(gauge)
The microsecond portion of the current waiting time
Shown as microsecond
pgbouncer.databases.current_connections
(gauge)
Current number of connections for this database
Shown as connection
pgbouncer.databases.max_connections
(gauge)
Maximum number of allowed connections
Shown as connection
pgbouncer.databases.pool_size
(gauge)
Maximum number of server connections
Shown as connection
pgbouncer.max_client_conn
(gauge)
The maximum number of client connections allowed.
Shown as connection
pgbouncer.pools.cl_active
(gauge)
Client connections linked to server connection and able to process queries
Shown as connection
pgbouncer.pools.cl_waiting
(gauge)
Client connections waiting on a server connection
Shown as connection
pgbouncer.pools.maxwait
(gauge)
How long the first (oldest) client in the queue has waited, in seconds
Shown as second
pgbouncer.pools.maxwait_us
(gauge)
Microsecond part of the maximum waiting time
Shown as microsecond
pgbouncer.pools.sv_active
(gauge)
Server connections linked to a client connection
Shown as connection
pgbouncer.pools.sv_idle
(gauge)
Server connections idle and ready for a client query
Shown as connection
pgbouncer.pools.sv_login
(gauge)
Server connections currently in the process of logging in
Shown as connection
pgbouncer.pools.sv_tested
(gauge)
Server connections currently running either serverresetquery or servercheckquery
Shown as connection
pgbouncer.pools.sv_used
(gauge)
Server connections idle more than servercheckdelay, needing servercheckquery
Shown as connection
pgbouncer.servers.connect_time
(gauge)
When the connection was made (seconds since epoch)
Shown as second
pgbouncer.servers.request_time
(gauge)
When last request was issued (seconds since epoch)
Shown as second
pgbouncer.stats.avg_query
(gauge)
The average query duration
Shown as microsecond
pgbouncer.stats.avg_query_count
(gauge)
The average number of queries per second in last stat period
Shown as query
pgbouncer.stats.avg_query_time
(gauge)
The average query duration
Shown as microsecond
pgbouncer.stats.avg_recv
(gauge)
The client network traffic received
Shown as byte
pgbouncer.stats.avg_req
(gauge)
The average number of requests per second in last stat period
Shown as request
pgbouncer.stats.avg_sent
(gauge)
The client network traffic sent
Shown as byte
pgbouncer.stats.avg_transaction_count
(gauge)
The average number of transactions per second in last stat period
Shown as transaction
pgbouncer.stats.avg_transaction_time
(gauge)
The average transaction duration
Shown as microsecond
pgbouncer.stats.avg_wait_time
(gauge)
Time spent by clients waiting for a server, in microseconds (average per second)
Shown as microsecond
pgbouncer.stats.bytes_received_per_second
(rate)
The total network traffic received
Shown as byte
pgbouncer.stats.bytes_sent_per_second
(rate)
The total network traffic sent
Shown as byte
pgbouncer.stats.queries_per_second
(rate)
The query rate
Shown as query
pgbouncer.stats.requests_per_second
(rate)
The request rate
Shown as request
pgbouncer.stats.total_query_time
(rate)
Time spent by pgbouncer actively querying PostgreSQL
Shown as microsecond
pgbouncer.stats.total_transaction_time
(rate)
Time spent by pgbouncer in transactions
Shown as microsecond
pgbouncer.stats.total_wait_time
(gauge)
Time spent by clients waiting for a server, in microseconds
Shown as microsecond
pgbouncer.stats.transactions_per_second
(rate)
The transaction rate
Shown as transaction

Note: Not all metrics are available with all versions of PgBouncer.

Events

The PgBouncer check does not include any events.

Service Checks

pgbouncer.can_connect
Returns CRITICAL if the Agent is unable to connect to the monitored PGBouncer instance. Returns OK otherwise.
Statuses: ok, critical

Troubleshooting

Need help? Contact Datadog support.

PREVIEWING: may/unit-testing