---
title: PGBouncer
description: >-
  Track connection pool metrics and monitor traffic to and from your
  application.
breadcrumbs: Docs > Integrations > PGBouncer
---

# PGBouncer
Supported OS Integration version8.9.0
## Overview{% #overview %}

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

**Minimum Agent version:** 6.0.0

## Setup{% #setup %}

### Installation{% #installation %}

The PgBouncer check is included in the [Datadog Agent](https://app.datadoghq.com/account/settings/agent/latest) 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:

   ```ini
   stats_users = datadog
   ```

1. Add an associated password for the `datadog` user in your PgBouncer `userlist.txt` file:

   ```text
   "datadog" "<PASSWORD>"
   ```

1. To verify the credentials, run the following command:

   ```shell
   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{% #configuration %}

{% tab title="Host" %}
#### Host{% #host %}

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

##### Metric collection{% #metric-collection %}

1. Edit the `pgbouncer.d/conf.yaml` file, in the `conf.d/` folder at the root of your [Agent's configuration directory](https://docs.datadoghq.com/agent/guide/agent-configuration-files/#agent-configuration-directory). See the [sample pgbouncer.d/conf.yaml](https://github.com/DataDog/integrations-core/blob/master/pgbouncer/datadog_checks/pgbouncer/data/conf.yaml.example) for all available configuration options:

   ```yaml
   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](https://www.postgresql.org/docs/9.1/libpq-ssl.html).

1. [Restart the Agent](https://docs.datadoghq.com/agent/guide/agent-commands/#start-stop-and-restart-the-agent).

##### Log collection{% #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:

   ```yaml
   logs_enabled: true
   ```

1. Add this configuration block to your `pgbouncer.d/conf.yaml` file to start collecting your Pgbouncer logs:

   ```yaml
   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](https://github.com/DataDog/integrations-core/blob/master/pgbouncer/datadog_checks/pgbouncer/data/conf.yaml.example) for all available configuration options.

1. [Restart the Agent](https://docs.datadoghq.com/agent/guide/agent-commands/#agent-status-and-information).

{% /tab %}

{% tab title="Containerized" %}
#### Containerized{% #containerized %}

For containerized environments, see the [Autodiscovery Integration Templates](https://docs.datadoghq.com/agent/kubernetes/integrations/) for guidance on applying the parameters below.

##### Metric collection{% #metric-collection %}

| Parameter            | Value                                                                                                  |
| -------------------- | ------------------------------------------------------------------------------------------------------ |
| `<INTEGRATION_NAME>` | `pgbouncer`                                                                                            |
| `<INIT_CONFIG>`      | blank or `{}`                                                                                          |
| `<INSTANCE_CONFIG>`  | `{"database_url": "postgresql://datadog:<PASSWORD>@%%host%%:%%port%%/<DATABASE_URL>?sslmode=require"}` |

##### Log collection{% #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](https://docs.datadoghq.com/agent/kubernetes/log/).

| Parameter      | Value                                           |
| -------------- | ----------------------------------------------- |
| `<LOG_CONFIG>` | {"source": "pgbouncer", "service": "pgbouncer"} |

{% /tab %}

### Validation{% #validation %}

[Run the Agent's status subcommand](https://docs.datadoghq.com/agent/guide/agent-commands/#agent-status-and-information) and look for `pgbouncer` under the Checks section.

## Data Collected{% #data-collected %}

### Metrics{% #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 server_reset_query or server_check_query*Shown as connection* |
| **pgbouncer.pools.sv\_used**(gauge)                    | Server connections idle more than server_check_delay, needing server_check_query*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{% #events %}

The PgBouncer check does not include any events.

### Service Checks{% #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{% #troubleshooting %}

Need help? Contact [Datadog support](https://docs.datadoghq.com/help/).