feat(prometheus.exporter.postgres): Update to version `0.19.0` and expose new collectors settings by cristiangreco · Pull Request #4640 · grafana/alloy

cristiangreco · 2025-10-21T17:18:29Z

PR Description

Update the postgres_exporter to version v0.19.0 (but continue to use our fork).

The update adds support for configuring the stat_statements collector flags, including limit, exclude_databases, and exclude_users.

Which issue(s) this PR fixes

Fixes #5502

Notes to the Reviewer

PR Checklist

CHANGELOG.md updated
Documentation added
Tests updated
Config converters updated

github-actions · 2026-01-23T09:28:50Z

💻 Deploy preview available (postgres: add support for stat_statements limit flag):

https://deploy-preview-alloy-4640-zb444pucvq-vp.a.run.app/docs/alloy/latest/

github-actions · 2026-01-27T10:42:05Z

💻 Deploy preview available (feat: Postgres_exporter: update version and add stat_statements flags):

https://deploy-preview-alloy-4640-zb444pucvq-vp.a.run.app/docs/alloy/latest/

github-actions · 2026-02-04T18:43:28Z

💻 Deploy preview available (feat(prometheus.exporter.postgres): Update to version 0.19.0 and add expose new collectors settings ):

https://deploy-preview-alloy-4640-zb444pucvq-vp.a.run.app/docs/alloy/latest/

collector/builder-config.yaml

extension/alloyengine/go.mod

dependency-replacements.yaml

go.mod

cristiangreco · 2026-02-05T14:56:39Z

internal/static/integrations/postgres_exporter/postgres_exporter.go

+		cfg.ExcludeDatabases,
+		dsns[0],
+		cfg.EnabledCollectors,
+		collector.WithCollectionTimeout("10s"),


This last parameter is needed due to a change in upstream signature. We could make it configurable, but I've seen some discussion around the implementation so was a bit hesitant to expose it as an alloy setting for now.

Could we add this default configuration of a 10s timeout to the documentation if it's not there already?

Definitely agree with keeping it hidden if it's not clear that the upstream implementation will be stable.

Have added a notice in 60194ee

github-actions · 2026-02-05T15:00:02Z

🔍 Dependency Review

Below are the dependency changes detected in the provided diffs, along with required code changes (if any), evidence, and example patches to keep behavior consistent.

github.com/prometheus/common v0.67.4 -> v0.67.5 — ✅ Safe

Scope: Patch release only. Used as a transitive/indirect dependency in several modules here.
API impact: No public API changes required for consumers in this repo.

Evidence

Prometheus “common” patch releases typically contain internal fixes and dependency bumps without API changes affecting downstream users.
This repository does not call into any unstable or internal parts of the package directly.

Action

No code changes required.

github.com/prometheus/exporter-toolkit v0.15.0 -> v0.15.1 — ✅ Safe

Scope: Patch release only. Used indirectly here.
API impact: No public API changes required for consumers in this repo.

Evidence

Exporter Toolkit patch releases historically include small fixes (TLS/OpenMetrics helpers, small behavior fixes) without changing public APIs used by exporters.

Action

No code changes required.

github.com/prometheus-community/postgres_exporter (via replace to github.com/grafana/postgres_exporter) v0.0.0-20250930-c8f6a9f4d363 -> v0.0.0-20260212-d256e52d0faf — ❌ Changes Needed

Status

Significant API/behavior changes between the tracked “exporter-package-v0.18.1” branch and the new “exporter-package-v0.19.0” branch on the Grafana fork require code updates. These updates are already partially applied in this PR; ensure all instances are migrated consistently.

Summary of changes requiring code updates

Exporter package entrypoint moved and Kingpin flag hacks must be removed
- Old: github.com/prometheus-community/postgres_exporter/cmd/postgres_exporter
- New: github.com/prometheus-community/postgres_exporter/exporter (programmatic API)
- With this move, the “hack” that poked Kingpin flags at runtime should be deleted and replaced by first‑class option structs.
Logger injection changed
- Old: provide logger via postgres_exporter.WithLogger(...) option.
- New: pass the logger directly as the second argument to exporter.NewExporter(...).
- The option WithLogger is removed.
Collector configuration is now option-driven per instance
- New per-instance collector options are available (e.g., collector.WithCollectionTimeout(...), collector.WithStatStatementsConfig(...)).
- This PR sets a 10s collection timeout. Keep this for parity with the docs change.
stat_statements collector gained more configuration
- New fields: limit, exclude_databases, exclude_users.
- Replace prior Kingpin flag edits with collector.WithStatStatementsConfig(collector.StatStatementsConfig{...}).
New API surface used by this repo
- exporter.NewExporter(dsns, logger, ...exporter.Option)
- collector.NewPostgresCollector(logger, exclude, dsn, enabledCollectors, ...collector.Option)

Evidence (from the updated code in this PR)

Imports switched from cmd/postgres_exporter to exporter.
Kingpin imports and flag mutation code removed.
collector.NewPostgresCollector now consumes new variadic options, including WithCollectionTimeout and WithStatStatementsConfig.
New programmatic fields for stat_statements (Limit, ExcludeDatabases, ExcludeUsers) were plumbed through.

Required code changes (already applied here; ensure they are applied everywhere this exporter is used)

A) Replace cmd package usage with exporter package and remove Kingpin hacks

-   "github.com/alecthomas/kingpin/v2"
    "github.com/go-kit/log"
    "github.com/grafana/alloy/internal/runtime/logging"
    ...
-   "github.com/prometheus-community/postgres_exporter/cmd/postgres_exporter"
    "github.com/prometheus-community/postgres_exporter/collector"
+   postgres_exporter "github.com/prometheus-community/postgres_exporter/exporter"

B) Update programmatic exporter construction and logger injection

-   e := postgres_exporter.NewExporter(
-       dsns,
-       postgres_exporter.DisableDefaultMetrics(cfg.DisableDefaultMetrics),
-       postgres_exporter.WithUserQueriesPath(cfg.QueryPath),
-       postgres_exporter.DisableSettingsMetrics(cfg.DisableSettingsMetrics),
-       postgres_exporter.AutoDiscoverDatabases(cfg.AutodiscoverDatabases),
-       postgres_exporter.ExcludeDatabases(cfg.ExcludeDatabases),
-       postgres_exporter.IncludeDatabases(strings.Join(cfg.IncludeDatabases, ",")),
-       postgres_exporter.WithLogger(logger),
-       postgres_exporter.WithMetricPrefix("pg"),
-   )
+   e := postgres_exporter.NewExporter(
+       dsns,
+       logger,
+       postgres_exporter.DisableDefaultMetrics(cfg.DisableDefaultMetrics),
+       postgres_exporter.WithUserQueriesPath(cfg.QueryPath),
+       postgres_exporter.DisableSettingsMetrics(cfg.DisableSettingsMetrics),
+       postgres_exporter.AutoDiscoverDatabases(cfg.AutodiscoverDatabases),
+       postgres_exporter.ExcludeDatabases(cfg.ExcludeDatabases),
+       postgres_exporter.IncludeDatabases(strings.Join(cfg.IncludeDatabases, ",")),
+       postgres_exporter.WithMetricPrefix("pg"),
+   )

C) Configure per-instance collector options (10s collection timeout + stat_statements config)

-   // Kingpin flag hacks (remove)
-   if cfg.StatStatementFlags != nil && cfg.StatStatementFlags.IncludeQuery {
-       includeQueryFlag := kingpin.CommandLine.GetFlag("collector.stat_statements.include_query")
-       queryLengthFlag := kingpin.CommandLine.GetFlag("collector.stat_statements.query_length")
-       ...
-   }
+   // Per-instance collector options
+   collectorOpts := []collector.Option{
+       collector.WithCollectionTimeout("10s"),
+   }
+   if cfg.StatStatementFlags != nil {
+       collectorOpts = append(collectorOpts, collector.WithStatStatementsConfig(collector.StatStatementsConfig{
+           IncludeQuery:     cfg.StatStatementFlags.IncludeQuery,
+           QueryLength:      cfg.StatStatementFlags.QueryLength,
+           Limit:            cfg.StatStatementFlags.Limit,
+           ExcludeDatabases: cfg.StatStatementFlags.ExcludeDatabases,
+           ExcludeUsers:     cfg.StatStatementFlags.ExcludeUsers,
+       }))
+   }

D) Pass the new collector options to the primary collector

-   c, err := collector.NewPostgresCollector(logger, cfg.ExcludeDatabases, dsns[0], cfg.EnabledCollectors)
+   c, err := collector.NewPostgresCollector(
+       logger,
+       cfg.ExcludeDatabases,
+       dsns[0],
+       cfg.EnabledCollectors,
+       collectorOpts...,
+   )

E) Extend the public config surface for stat_statements flags (internal/component mapping)

 type StatStatementFlags struct {
-    IncludeQuery bool `alloy:"include_query,attr,optional"`
-    QueryLength  uint `alloy:"query_length,attr,optional"`
+    IncludeQuery     bool     `alloy:"include_query,attr,optional"`
+    QueryLength      uint     `alloy:"query_length,attr,optional"`
+    Limit            uint     `alloy:"limit,attr,optional"`
+    ExcludeDatabases []string `alloy:"exclude_databases,attr,optional"`
+    ExcludeUsers     []string `alloy:"exclude_users,attr,optional"`
 }
 
 func (s *StatStatementFlags) Convert() *postgres_exporter.StatStatementFlags {
     if s == nil {
         return nil
     }
     return &postgres_exporter.StatStatementFlags{
-        IncludeQuery: s.IncludeQuery,
-        QueryLength:  s.QueryLength,
+        IncludeQuery:     s.IncludeQuery,
+        QueryLength:      s.QueryLength,
+        Limit:            s.Limit,
+        ExcludeDatabases: s.ExcludeDatabases,
+        ExcludeUsers:     s.ExcludeUsers,
     }
 }

F) Documentation alignment

The docs update in this PR stating “collection timeout of 10 seconds” matches collector.WithCollectionTimeout("10s"); keep that.
New stat_statements options (exclude_databases, exclude_users, limit) are now documented; ensure any user-facing schema and validation match the new fields.

Notes

The constraint that the collector package still only supports the first DSN for certain metrics remains, as noted in the code comment. This is unchanged by this update and tracked upstream.

Notes

The postgres exporter replace now tracks Grafana’s fork branch “exporter-package-v0.19.0”, which introduces a stable programmatic API (exporter + collector options) that replaces prior CLI-flag configuration. This review treated it as a full upgrade and verified all necessary code touch points are updated.
No net-new dependencies were introduced that affect direct code paths in this repo.

dehaansa · 2026-02-09T14:57:52Z

docs/sources/reference/components/prometheus/prometheus.exporter.postgres.md

+| Name                | Type           | Description                                         | Default | Required |
+| ------------------- | -------------- | --------------------------------------------------- | ------- | -------- |
+| `include_query`     | `bool`         | Enable the selection of query ID and SQL statement. | `false` | no       |
+| `query_length`      | `number`       | Maximum length of the statement query text.         | `120`   | no       |


Arguments should be sorted first by required, then alphabetically

I've applied @clayton-cornell's suggestion, which should address your comment.

dehaansa · 2026-02-09T15:00:47Z

internal/static/integrations/postgres_exporter/postgres_exporter.go

+		}
+	}
+	if cfg.StatStatementFlags != nil && cfg.StatStatementFlags.Limit != 0 {
+		limitFlag := kingpin.CommandLine.GetFlag("collector.stat_statements.limit")


I hadn't seen this used before, does this approach work with multiple instances of the postgres exporter?

You're right, this can't work correctly for multiple instances. I'll have a look.

@dehaansa thanks for pointing this out, I realised I hadn't tested Alloy with multiple instances.

I've added a new patch in our fork, building on top of the existing one: grafana/postgres_exporter#29

That patch should allow passing collector parameters without using kingpin flag.

Once reviewed, I'll merge that PR in the branch exporter-toolkit-v0.19.0 and update our deps here.

Have merged the PR in our fork and did a squash/rebase here. @dehaansa @blewis12 could you please have a second pass?

dehaansa · 2026-02-09T15:01:39Z

internal/static/integrations/postgres_exporter/postgres_exporter.go

+		cfg.ExcludeDatabases,
+		dsns[0],
+		cfg.EnabledCollectors,
+		collector.WithCollectionTimeout("10s"),


Definitely agree with keeping it hidden if it's not clear that the upstream implementation will be stable.

docs/sources/reference/components/prometheus/prometheus.exporter.postgres.md

kgeckhart · 2026-02-11T20:31:06Z

FYI a recent issue was opened regarding a panic that was fixed in v0.19.0. I imagine this PR will resolve #5502

cristiangreco · 2026-02-12T07:54:12Z

FYI a recent issue was opened regarding a panic that was fixed in v0.19.0. I imagine this PR will resolve #5502

Yes, should be fixed by prometheus-community/postgres_exporter#1252, which is included in v0.19.0

…expose new collectors settings Update the postgres_exporter to version v0.19.0 (but continue to use our grafana fork). The update adds support for configuring the stat_statements collector flags, including limit, exclude_databases, and exclude_users.

ptodev · 2026-02-13T11:40:22Z

Thanks @cristiangreco, I edited the PR description to state that it will close #5502.

docs/sources/reference/components/prometheus/prometheus.exporter.postgres.md

clayton-cornell

Docs are OK - one small non-blocking suggestion

…er.postgres.md Co-authored-by: Clayton Cornell <131809008+clayton-cornell@users.noreply.github.com>

github-actions · 2026-02-13T15:48:03Z

💻 Deploy preview deleted (feat(prometheus.exporter.postgres): Update to version 0.19.0 and expose new collectors settings ).

…pose new collectors settings (#4640) #### PR Description Update the `postgres_exporter` to version [v0.19.0](https://github.com/prometheus-community/postgres_exporter/releases/tag/v0.19.0) (but continue to use our [fork](https://github.com/grafana/postgres_exporter/tree/exporter-package-v0.19.0)). The update adds support for configuring the `stat_statements` collector flags, including `limit`, `exclude_databases`, and `exclude_users`. #### Which issue(s) this PR fixes Fixes #5502 #### Notes to the Reviewer #### PR Checklist  - [ ] CHANGELOG.md updated - [x] Documentation added - [ ] Tests updated - [ ] Config converters updated --------- Co-authored-by: Clayton Cornell <131809008+clayton-cornell@users.noreply.github.com>

…pose new collectors settings (grafana#4640) #### PR Description Update the `postgres_exporter` to version [v0.19.0](https://github.com/prometheus-community/postgres_exporter/releases/tag/v0.19.0) (but continue to use our [fork](https://github.com/grafana/postgres_exporter/tree/exporter-package-v0.19.0)). The update adds support for configuring the `stat_statements` collector flags, including `limit`, `exclude_databases`, and `exclude_users`. #### Which issue(s) this PR fixes Fixes grafana#5502 #### Notes to the Reviewer #### PR Checklist  - [ ] CHANGELOG.md updated - [x] Documentation added - [ ] Tests updated - [ ] Config converters updated --------- Co-authored-by: Clayton Cornell <131809008+clayton-cornell@users.noreply.github.com>

This comment was marked as outdated.

Sign in to view

github-actions bot added the needs-attention label Jan 20, 2026

cristiangreco force-pushed the cristian/dbo11y-pg-stat-statements-limit branch from cbe7c33 to 5c01c78 Compare January 22, 2026 16:33

github-actions bot removed the needs-attention label Jan 23, 2026

cristiangreco force-pushed the cristian/dbo11y-pg-stat-statements-limit branch from 5c01c78 to 0d46e2c Compare January 23, 2026 09:27

cristiangreco force-pushed the cristian/dbo11y-pg-stat-statements-limit branch from 0d46e2c to 93c0776 Compare January 23, 2026 09:58

cristiangreco changed the title ~~postgres: add support for stat_statements limit flag~~ feat: Postgres_exporter: update version and add stat_statements flags Jan 23, 2026

cristiangreco force-pushed the cristian/dbo11y-pg-stat-statements-limit branch from 93c0776 to 6ae8ccf Compare January 27, 2026 10:40

cristiangreco changed the title ~~feat: Postgres_exporter: update version and add stat_statements flags~~ feat(postgres_exporter): Update version and add stat_statements flags Feb 4, 2026

cristiangreco changed the title ~~feat(postgres_exporter): Update version and add stat_statements flags~~ feat(prometheus.exporter.postgres): Update to version 0.19.0 and add expose new collectors settings Feb 4, 2026

cristiangreco force-pushed the cristian/dbo11y-pg-stat-statements-limit branch from 6ae8ccf to ab0a3f1 Compare February 4, 2026 18:41

cristiangreco force-pushed the cristian/dbo11y-pg-stat-statements-limit branch 5 times, most recently from 88e6ad0 to 3a926f5 Compare February 5, 2026 10:36