Expose statistics reset timestamps as gauges by je4yfc · Pull Request #1416 · prometheus-community/postgres_exporter

je4yfc · 2026-10-11T23:02:51Z

This is my attempt to fix: #1415

Add pg_stat_bgwriter_stats_reset_timestamp_seconds, pg_stat_checkpointer_stats_reset_timestamp_seconds, and pg_stat_database_stats_reset_timestamp_seconds as Unix-second gauges. At master@c5662d1, the background-writer (also before PostgreSQL 17), checkpointer, and database SQL conversion and emission paths turn SQL stats_reset timestamps into Unix seconds but publish counters. Preserve the legacy names, counter types, values and label sets as deprecated aliases, scheduled for removal two releases after deprecation. The new timestamp gauges omit samples when PostgreSQL returns NULL; the legacy counters retain their existing NULL-as-zero behavior. The checkpointer guard stays PostgreSQL 17+, and database labels stay datid,datname. No SQL, flag or legacy-exporter change.

Reproduce the original failure with the focused collector/HTTP exposition test:

git clone https://github.com/prometheus-community/postgres_exporter.git
cd postgres_exporter
git switch --detach c5662d1e61af7fed870049d342215c01263496ba
curl -fsSL https://raw.githubusercontent.com/je4yfc/postgres_exporter/2c68f9c44d1d594b083ea20626d7c29476139fbd/collector/stats_reset_timestamp_test.go -o collector/stats_reset_timestamp_test.go
go test ./collector -run TestStatsResetTimestampExposition -count=1

The original run fails because the gauge families are absent. Regression coverage now lives in the existing collector test files. On this PR branch, go test ./collector -run 'TestPGStat(BGWriter|Checkpointer|Database)Collector' -count=1 passes. Updated HTTP exposition excerpt:

ORIGINAL (c5662d1):
# TYPE pg_stat_bgwriter_stats_reset_total counter
pg_stat_bgwriter_stats_reset_total 1.685059842e+09
# TYPE pg_stat_checkpointer_stats_reset_total counter
pg_stat_checkpointer_stats_reset_total 1.685059842e+09
# TYPE pg_stat_database_stats_reset counter
pg_stat_database_stats_reset{datid="1",datname="first"} 1.685059842e+09
pg_stat_database_stats_reset{datid="2",datname="second"} 0

PATCHED:
# TYPE pg_stat_bgwriter_stats_reset_total counter
pg_stat_bgwriter_stats_reset_total 1.685059842e+09
# TYPE pg_stat_bgwriter_stats_reset_timestamp_seconds gauge
pg_stat_bgwriter_stats_reset_timestamp_seconds 1.685059842e+09
# TYPE pg_stat_checkpointer_stats_reset_total counter
pg_stat_checkpointer_stats_reset_total 1.685059842e+09
# TYPE pg_stat_checkpointer_stats_reset_timestamp_seconds gauge
pg_stat_checkpointer_stats_reset_timestamp_seconds 1.685059842e+09
# TYPE pg_stat_database_stats_reset counter
pg_stat_database_stats_reset{datid="1",datname="first"} 1.685059842e+09
pg_stat_database_stats_reset{datid="2",datname="second"} 0
# TYPE pg_stat_database_stats_reset_timestamp_seconds gauge
pg_stat_database_stats_reset_timestamp_seconds{datid="1",datname="first"} 1.685059842e+09
PASS

Validation: go test ./..., go vet ./..., and git diff --check passed. Tests cover both background-writer version paths, checkpointer's version guard, NULL omission, valid zero timestamps, and metric names, types and labels.

LLM Disclosure: This bug was found and classified by an LLM that I was ~~abusing~~ giving the task of looking through every metric I ingest to see what could be used in a dashboard. After I verified the issue, I had that same LLM help me understand enough of your codebase to make a PR.

ArthurSens · 2026-10-26T17:03:56Z

+	)
+	statBGWriterStatsResetTimestampDesc = prometheus.NewDesc(
+		prometheus.BuildFQName(namespace, bgWriterSubsystem, "stats_reset_timestamp_seconds"),
+		"Unix timestamp in seconds at which these statistics were last reset; 0 means PostgreSQL returned NULL",


I think it's better not to expose the metric at all if, while scanning the row, we get a NULL value from Postgres. It would definitely be less confusing than seeing a 0 in the dashboard and thinking that the last reset happened in 1970

NULL now omits the timestamp gauge in both version paths

https://github.com/je4yfc/postgres_exporter/blob/6e73ed0/collector/pg_stat_bgwriter.go#L164-L274

ArthurSens · 2026-10-26T17:04:55Z

@@ -95,7 +95,13 @@ var (
 	)
 	statBGWriterStatsResetDesc = prometheus.NewDesc(


Could we add a comment stating that this metric will be removed in the next two releases? Mostly for us to remind ourselves to actually remove it 😬

Added a comment marking the counter for removal after two releases

https://github.com/je4yfc/postgres_exporter/blob/6e73ed0/collector/pg_stat_bgwriter.go#L96

ArthurSens · 2026-10-26T17:05:22Z

@@ -87,7 +87,13 @@ var (
 	)
 	statCheckpointerStatsResetDesc = prometheus.NewDesc(


same as above, could we add a comment stating that this metric can be removed in the future?

Added the same two-release removal reminder here

https://github.com/je4yfc/postgres_exporter/blob/6e73ed0/collector/pg_stat_checkpointer.go#L88

ArthurSens · 2026-10-26T17:05:35Z

+	)
+	statCheckpointerStatsResetTimestampDesc = prometheus.NewDesc(
+		prometheus.BuildFQName(namespace, statCheckpointerSubsystem, "stats_reset_timestamp_seconds"),
+		"Unix timestamp in seconds at which these statistics were last reset; 0 means PostgreSQL returned NULL",


same as above, let's not use 0 for NULL returns

the timestamp gauge is only emitted for non-NULL values

https://github.com/je4yfc/postgres_exporter/blob/6e73ed0/collector/pg_stat_checkpointer.go#L216-L222

ArthurSens · 2026-10-26T17:06:18Z

@@ -0,0 +1,206 @@
+// Copyright 2026 The Prometheus Authors


why create a new file just for this test? couldn't we reuse the existing ones?

Because I was lazy and dumb - I fixed it. I moved the coverage into the existing bgwriter, checkpointer and database test files and removed the standalone file.

https://github.com/je4yfc/postgres_exporter/blob/6e73ed0/collector/pg_stat_bgwriter_test.go#L207
https://github.com/je4yfc/postgres_exporter/blob/6e73ed0/collector/pg_stat_checkpointer_test.go#L149
https://github.com/je4yfc/postgres_exporter/blob/6e73ed0/collector/pg_stat_database_test.go#L529

No need to be harsh on yourself either, things happen 😅

ArthurSens · 2026-10-26T17:08:12Z


 All metrics are prefixed with `pg_`. The exporter's own health is exposed via `pg_up` and `pg_exporter_*` metrics alongside the standard Go runtime metrics.

+The last statistics-reset time is exposed as a Unix-seconds gauge in `pg_stat_bgwriter_stats_reset_timestamp_seconds`, `pg_stat_checkpointer_stats_reset_timestamp_seconds` (PostgreSQL 17+), and `pg_stat_database_stats_reset_timestamp_seconds` (with `datid` and `datname` labels). A value of `0` means PostgreSQL returned a NULL reset time, so filter for values greater than zero before calculating an age with `time() - metric`. The older `pg_stat_bgwriter_stats_reset_total`, `pg_stat_checkpointer_stats_reset_total`, and `pg_stat_database_stats_reset` families remain as deprecated counters with their existing values for compatibility; they represent timestamps, not reset counts, and should not be used with `rate()`, `increase()`, or `resets()`.


We don't document all our metrics in our README, it would be weird to document this one 😬

I removed this - sorry haha.

ArthurSens · 2026-10-26T17:09:00Z

 * [FEATURE] Export `pg_settings.pending_restart` as `pg_settings_pending_restart{name}` from the `settings` collector by @MarcWort in https://github.com/prometheus-community/postgres_exporter/pull/1396
 * [FEATURE] Add `aurora_replica_status` collector for Amazon Aurora PostgreSQL by @megative in https://github.com/prometheus-community/postgres_exporter/pull/1311

+* [ENHANCEMENT] Expose `pg_stat_bgwriter`, `pg_stat_checkpointer`, and `pg_stat_database` statistics reset times as `_timestamp_seconds` gauges; retain the former counter families as deprecated aliases.


This changelog entry doesn't follow the format we've been using above. Could you follow it?

Also, since we're deprecating a metric, it would be nice to have a deprecation notice in the changelog as well

I adeded tis:

https://github.com/je4yfc/postgres_exporter/blob/6e73ed0/CHANGELOG.md#L18

explicit notice naming all three deprecated counters, their replacements, and the two-release removal timeline:

https://github.com/je4yfc/postgres_exporter/blob/6e73ed0/CHANGELOG.md#L19

Signed-off-by: Joseph Erdosy <168128519+je4yfc@users.noreply.github.com>

Signed-off-by: Joseph <168128519+je4yfc@users.noreply.github.com>

je4yfc · 2026-10-29T16:47:28Z

I think I fixed it all, I'll leave resolution to you. If you need additional fixed, let me know 🫡

ArthurSens

just some nits

ArthurSens · 2026-11-03T21:34:00Z

 * [FEATURE] Export `pg_settings.pending_restart` as `pg_settings_pending_restart{name}` from the `settings` collector by @MarcWort in https://github.com/prometheus-community/postgres_exporter/pull/1396
 * [FEATURE] Add `aurora_replica_status` collector for Amazon Aurora PostgreSQL by @megative in https://github.com/prometheus-community/postgres_exporter/pull/1311
+* [BUGFIX] Expose `pg_stat_bgwriter`, `pg_stat_checkpointer`, and `pg_stat_database` statistics reset times as `_timestamp_seconds` gauges, omitting samples when PostgreSQL returns NULL, by @je4yfc in https://github.com/prometheus-community/postgres_exporter/pull/1416
+* [CHANGE] Deprecate `pg_stat_bgwriter_stats_reset_total`, `pg_stat_checkpointer_stats_reset_total`, and `pg_stat_database_stats_reset` in favor of their `_stats_reset_timestamp_seconds` gauges; the counters will be removed two releases after this deprecation, by @je4yfc in https://github.com/prometheus-community/postgres_exporter/pull/1416


It's better to be explicit on what "two releases from now" means. Which is after v0.22.0

ArthurSens · 2026-11-03T21:34:35Z

 		[]string{"datid", "datname"},
 		prometheus.Labels{},
 	)
+	// Deprecated: remove this counter two releases after introducing the timestamp gauge.


let's be explicit about which version we're removing the metric

ArthurSens · 2026-11-03T21:34:49Z

 		[]string{},
 		prometheus.Labels{},
 	)
+	// Deprecated: remove this counter two releases after introducing the timestamp gauge.


je4yfc · 2026-11-11T02:22:45Z

Fixed. I set them to 0.22.0.

je4yfc force-pushed the fix/stats-reset-timestamps branch from 2c68f9c to 7286f89 Compare October 11, 2026 23:05

ArthurSens reviewed Oct 26, 2026

View reviewed changes

je4yfc added 2 commits October 29, 2026 13:26

Expose statistics reset timestamps as gauges

c779b8f

Signed-off-by: Joseph Erdosy <168128519+je4yfc@users.noreply.github.com>

fix: omit NULL stats reset gauges and clarify metric deprecations

08f755e

Signed-off-by: Joseph Erdosy <168128519+je4yfc@users.noreply.github.com>

je4yfc force-pushed the fix/stats-reset-timestamps branch from 6e73ed0 to 08f755e Compare October 29, 2026 16:26

Merge branch 'master' into fix/stats-reset-timestamps

86a4aa3

Signed-off-by: Joseph <168128519+je4yfc@users.noreply.github.com>

ArthurSens reviewed Nov 3, 2026

View reviewed changes

Clarify deprecated stats reset counters are removed after v0.22.0

f49ff55

		@@ -95,7 +95,13 @@ var (
		)
		statBGWriterStatsResetDesc = prometheus.NewDesc(

		@@ -87,7 +87,13 @@ var (
		)
		statCheckpointerStatsResetDesc = prometheus.NewDesc(


		All metrics are prefixed with `pg_`. The exporter's own health is exposed via `pg_up` and `pg_exporter_*` metrics alongside the standard Go runtime metrics.

		The last statistics-reset time is exposed as a Unix-seconds gauge in `pg_stat_bgwriter_stats_reset_timestamp_seconds`, `pg_stat_checkpointer_stats_reset_timestamp_seconds` (PostgreSQL 17+), and `pg_stat_database_stats_reset_timestamp_seconds` (with `datid` and `datname` labels). A value of `0` means PostgreSQL returned a NULL reset time, so filter for values greater than zero before calculating an age with `time() - metric`. The older `pg_stat_bgwriter_stats_reset_total`, `pg_stat_checkpointer_stats_reset_total`, and `pg_stat_database_stats_reset` families remain as deprecated counters with their existing values for compatibility; they represent timestamps, not reset counts, and should not be used with `rate()`, `increase()`, or `resets()`.

Conversation

je4yfc commented Oct 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ArthurSens Nov 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

je4yfc Oct 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

je4yfc commented Oct 29, 2026

Uh oh!

ArthurSens left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

je4yfc commented Nov 11, 2026

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

je4yfc commented Oct 11, 2026 •

edited

Loading

ArthurSens Nov 3, 2026 •

edited

Loading

je4yfc Oct 29, 2026 •

edited

Loading