CI Release Go Reference License Go pgx Prometheus
Prometheus instrumentation for pgx v5. Provides
two collectors: PoolCollector exposes connection pool metrics, and
QueryCollector records per-query request counts, error counts, and latency
histograms as Prometheus metrics.
go get github.com/pgx-contrib/pgxprom
PoolCollector implements prometheus.Collector and exposes connection pool
statistics for one or more pgxpool.Pool instances.
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):
collector.Remove(pool)
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.
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()
Prefix any SQL string with -- name: <Identifier> to set a low-cardinality
db_operation label instead of unknown:
rows, err := pool.Query(ctx, "-- name: ListActiveCustomers\nSELECT * FROM customer WHERE active = true", )
This records the metric with db_operation="ListActiveCustomers".
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 |
All query metrics carry two labels:
| Label | Description |
|---|---|
database |
Database name from the connection config |
db_operation |
Name extracted from -- name: <Identifier> 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 |
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 develop # enter shell with Go
go tool ginkgo run -r# 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