Skip to content

PG Exporter v1.5.0

Latest
Latest

Choose a tag to compare

View all tags
@github-actions github-actions released this 23 Oct 01:36
v1.5.0
1891254

PG Exporter v1.5.0 improves connection safety, replication metric accuracy, database discovery, and health reporting. It is built with Go 1.27.3 and refreshed dependencies.

Highlights

  • Reject malformed connection URLs and invalid query parameters before connecting, report errors without exposing credentials, and reject empty URL key files. Explicit TLS settings are no longer silently discarded after a query-decoding error.
  • Resolve database identity through lib/pq, including dbname / database overrides. Auto-discovery now replaces conflicting database parameters correctly and preserves special database names, preventing duplicate series and failed scrapes.
  • Read one atomic health state per HTTP response, keeping status codes and response bodies consistent during concurrent role or connectivity changes.
  • Replan collectors when the connected user, schemas, or extension set changes; preserve cached results when those sets are unchanged.
  • Reject non-finite and overflowing collector/predicate TTLs and query timeouts during configuration parsing. Existing zero-value and finite negative-timeout semantics remain.
  • Validate the actual metrics route against the active Go HTTP mux, including escaped paths, so accepted telemetry paths reach the metrics handler.
  • Correct replication monitoring: add the owning database label to pg_sub_*, map WAL receiver states accurately, and clarify publication table counts, subscription relation states, and replication-origin privileges.

Metric and dashboard compatibility

Compared with v1.4.1 on the same PostgreSQL version, v1.5.0 does not add, remove, or rename bundled SQL metric names. Types and units remain unchanged, but labels and state mappings do change. PostgreSQL 19 support first shipped in v1.3.0; upgrading the database can also change the selected SQL branch and a metric's meaning.

Scope Metrics Compatibility action
v1.5.0 configuration pg_sub_* Adds datname to every sample. Keep database and subscription identity in joins and aggregations; new label sets create new time series.
v1.5.0 configuration pg_recv_state Real receiver states starting, waiting, restarting, and stopped now map to 6–9 instead of -1. Update value mappings and state alerts; codes 1–3 are reserved.
PG18 → PG19 Existing PG18 metric names None are removed or renamed by the PG19 branches in this bundle. This does not guarantee unchanged semantics or labels from PostgreSQL itself.
PG19 pg_sub_sync_error_count Keeps the name but becomes the sum of table and sequence synchronization errors. For table-only alerts, use pg_sub_sync_table_error_count; pg_sub_sync_seq_error_count reports the sequence component. Do not double-count the components and their sum.
PG19 pg_sub_has_worker, pg_sub_reset_time, pg_sub_confl_* Adds worker presence, reset time, and eight conflict counters. The subscription row can remain without an apply worker; metric presence alone is not a worker-health check.
PG19 pg_subrel_count Includes sequences as well as tables; pg_pubrel_count still counts tables only. Review panel labels and count comparisons.
PG19 pg_wal_fpi_bytes, pg_lock_stat_*, pg_recovery_state_*, pg_vacuum_score_* Additive metrics. Recovery state is replica-only; autovacuum scores are primary-only. Existing WAL, lock-distribution, and recovery families remain.

Users upgrading from PG17 or earlier must also migrate older names: checkpoint metrics left pg_bgwriter_* in PG17, and pg_wal_write, pg_wal_sync, pg_wal_write_time, and pg_wal_sync_time are absent from PG18 onward. The full compatibility guide lists each replacement, label/aggregation differences, and mixed-version PromQL.

Before rollout, evaluate the actual dashboard and alert expressions and test missing-series input. A successful scrape does not ensure every expected metric exists; an empty alert expression can silently stop firing. The missing-metric checks include a per-target rule and explain when absence is expected. The full PG19 metric table links to the tagged collector definitions; PostgreSQL validation remains scoped to 19 RC1.

Security and dependencies

The Go toolchain moves from Go 1.26.5 to 1.27.3. This includes CVE-2026-111943, which rejects certificate chains containing a small set of untrusted intermediates, plus the cumulative HTTP, TLS, template, parser, and build-tool fixes in Go 1.26.6 and Go 1.27.2.

The independent golang.org/x/net dependency moves 0.57.0 → 0.61.0, incorporating the HTTP/2 fixes released in 0.60.0:

x/crypto 0.54.0 → 0.58.0 also incorporates SSH fixes CVE-2026-56854, CVE-2026-56855, and CVE-2026-78662; x/text 0.40.0 → 0.43.0 incorporates the precis fix CVE-2026-56851. PG Exporter does not import those SSH/precis packages. These are dependency-version fixes, not evidence that those vulnerabilities were exploitable through this exporter.

Other maintenance updates include Prometheus client_golang 1.25.0, client_model 0.6.3, common 0.72.1, exporter-toolkit 0.20.0, klauspost/compress 1.20.3, and the maintained YAML v3 module go.yaml.in/yaml/v3 3.0.5. The database driver remains lib/pq 1.12.3.

Source scans on Linux amd64, Darwin arm64, and Windows amd64 found no known symbol-level or imported-package findings in this release candidate as of 2026-10-23. An unimported OpenPGP module advisory (GO-2026-5932) remains. Static symbol matches in older versions are not proof of exploitation. Upgrading the host's Go installation alone does not update an existing exporter binary: install the rebuilt v1.5.0 artifact.

The bilingual release articles provide the full CVE/version table and scope: English · 简体中文.

Upgrade notes

  • Upgrade the binary and the collector configuration to obtain the replication fixes. Package managers preserve locally modified configuration; merge the updated definitions deliberately.

  • pg_sub_* now carries a datname label. Review recording rules and dashboards that assume the previous label set, especially where subscription names repeat across databases.

  • On PostgreSQL 10–13, grant the monitoring role access to the subscription OID in the exporter's main connection database:

    GRANT SELECT (oid) ON pg_catalog.pg_subscription TO monitor;

  • pg_recv_state retains 0=streaming, 4=stopping, and 5=connecting (PG19+); it adds 6=starting, 7=waiting, 8=restarting, and 9=stopped. Values 1–3 remain reserved, and -1 means unknown.

  • Keep pg_origin disabled unless the documented privileges have been provisioned. On PostgreSQL 13 and older, granting function execution alone does not remove its internal superuser check.

  • Fix malformed URLs and non-finite/overflowing durations before upgrading; these inputs now fail explicitly. TLS remains opt-in when sslmode is omitted, so set sslmode=verify-full and the appropriate CA for remote targets.

  • Existing behavior is retained: an empty YAML configuration successfully installs zero collectors; SIGTERM does not drain active HTTP requests.

Configuration and validation

The regular bundle contains 58 YAML files including the schema reference, 96 query branches, 59 namespaces, and 460 distinct metric definitions. This replaces the imprecise “600+ metrics” wording; it is not a reduction in collectors. Actual time-series counts vary with versions, configuration, objects, and labels.

Validation covered PostgreSQL 9.1–9.6, 10–18, and 19 RC1, plus PgBouncer 1.26.1, using non-superuser monitoring accounts. It also covered real standby promotion, disconnection/recovery, metadata and cache changes, failed reloads, concurrent requests, race tests, both HTTP mux modes, and approximately 600,000 fuzz executions.

Release targets: Linux amd64/arm64/ppc64le, macOS amd64/arm64, and Windows amd64. Docker images use pgsty/pg_exporter:1.5.0 for amd64 and arm64. PostgreSQL 9.1–9.6 requires the legacy configuration.

Full diff: v1.4.1...v1.5.0

Assets 15
Loading