https://github.com/pgx-contrib/pgxprom
A Prometheus adapter for pgx
https://github.com/pgx-contrib/pgxprom
pgx postgresql prometheus
Last synced: about 1 month ago
JSON representation
A Prometheus adapter for pgx
- Host: GitHub
- URL: https://github.com/pgx-contrib/pgxprom
- Owner: pgx-contrib
- License: mit
- Created: 2024-03-03T05:08:40.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2025-03-24T05:32:16.000Z (about 1 year ago)
- Last Synced: 2025-03-24T06:28:13.874Z (about 1 year ago)
- Topics: pgx, postgresql, prometheus
- Language: Go
- Homepage:
- Size: 45.9 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# pgxprom
[](https://github.com/pgx-contrib/pgxprom/actions/workflows/ci.yml)
[](https://github.com/pgx-contrib/pgxprom/releases)
[](https://pkg.go.dev/github.com/pgx-contrib/pgxprom)
[](LICENSE)
[](https://go.dev)
[](https://github.com/jackc/pgx)
[](https://prometheus.io)
Prometheus instrumentation for [pgx v5](https://github.com/jackc/pgx). Provides
two collectors: `PoolCollector` exposes connection pool metrics, and
`QueryCollector` records per-query request counts, error counts, and latency
histograms as Prometheus metrics.
## Installation
```bash
go get github.com/pgx-contrib/pgxprom
```
## Usage
### PoolCollector
`PoolCollector` implements `prometheus.Collector` and exposes connection pool
statistics for one or more `pgxpool.Pool` instances.
```go
config, err := pgxpool.ParseConfig(os.Getenv("PGX_DATABASE_URL"))
if err != nil {
panic(err)
}
pool, err := pgxpool.NewWithConfig(context.Background(), config)
if err != nil {
panic(err)
}
collector := pgxprom.NewPoolCollector()
// register the pool with the collector
collector.Add(pool)
// register the collector with Prometheus
if err := prometheus.Register(collector); err != nil {
panic(err)
}
```
To stop tracking a pool (e.g. on graceful shutdown):
```go
collector.Remove(pool)
```
### QueryCollector
`QueryCollector` implements both `pgx.QueryTracer` (and `pgx.BatchTracer`) and
`prometheus.Collector`. Attach it to `ConnConfig.Tracer` to record metrics for
every query and batch operation.
```go
config, err := pgxpool.ParseConfig(os.Getenv("PGX_DATABASE_URL"))
if err != nil {
panic(err)
}
collector := pgxprom.NewQueryCollector()
// register with Prometheus
if err := prometheus.Register(collector); err != nil {
panic(err)
}
// attach as the pgx tracer
config.ConnConfig.Tracer = collector
pool, err := pgxpool.NewWithConfig(context.Background(), config)
if err != nil {
panic(err)
}
defer pool.Close()
rows, err := pool.Query(context.Background(), "SELECT * FROM customer")
if err != nil {
panic(err)
}
defer rows.Close()
```
### Named queries
Prefix any SQL string with `-- name: ` to set a low-cardinality
`db_operation` label instead of `unknown`:
```go
rows, err := pool.Query(ctx,
"-- name: ListActiveCustomers\nSELECT * FROM customer WHERE active = true",
)
```
This records the metric with `db_operation="ListActiveCustomers"`.
## Metrics reference
### PoolCollector — `pgx_pool_*`
All pool metrics carry a single `database` label (the database name from the
connection config).
| Metric | Type | Description |
|--------|------|-------------|
| `pgx_pool_acquire_connections` | Gauge | Connections currently being acquired |
| `pgx_pool_canceled_acquires_total` | Counter | Acquire attempts that were canceled |
| `pgx_pool_constructing_connections` | Gauge | Connections currently being constructed |
| `pgx_pool_empty_acquires_total` | Counter | Acquire attempts that waited on an empty pool |
| `pgx_pool_idle_connections` | Gauge | Idle connections in the pool |
| `pgx_pool_max_connections` | Gauge | Maximum connections allowed in the pool |
| `pgx_pool_total_connections` | Gauge | Total connections in the pool |
| `pgx_pool_new_connections_total` | Counter | New connections created |
| `pgx_pool_max_lifetime_destroys_total` | Counter | Connections destroyed due to MaxLifetime |
| `pgx_pool_max_idle_destroys_total` | Counter | Connections destroyed due to MaxIdleTime |
### QueryCollector — `pgx_conn_*`
All query metrics carry two labels:
| Label | Description |
|-------|-------------|
| `database` | Database name from the connection config |
| `db_operation` | Name extracted from `-- name: ` comment, or `unknown` |
| Metric | Type | Description |
|--------|------|-------------|
| `pgx_conn_requests_total` | Counter | Total database requests |
| `pgx_conn_request_errors_total` | Counter | Total database request errors |
| `pgx_conn_request_duration_seconds` | Histogram | Request latency in seconds |
## Development
### DevContainer
Open in VS Code with the Dev Containers extension. The environment provides Go,
PostgreSQL 18, and Nix automatically.
```
PGX_DATABASE_URL=postgres://vscode@postgres:5432/pgxprom?sslmode=disable
```
### Nix
```bash
nix develop # enter shell with Go
go tool ginkgo run -r
```
### Run tests
```bash
# Unit tests only (no database required)
go tool ginkgo run -r
# With integration tests
export PGX_DATABASE_URL="postgres://localhost/pgxprom?sslmode=disable"
go tool ginkgo run -r
```
## License
[MIT](LICENSE)