Create user facing documentation by sysadmind · Pull Request #1361 · prometheus-community/postgres_exporter

sysadmind · 2026-08-08T19:26:11Z

Create a docs/ directory with user facing documentation. This covers getting started, running with docker, specifying secrets, configuration, and database permissions. This is all focused on the perspective of a user or someone deploying the exporter.

nicolastakashi · 2026-08-10T18:37:42Z

Is part of #1363

ArthurSens

I haven't read the written documentation just yet, I'm just thinking about how this would be integrated in the website.

Since you're writing separate documents per topic, are you imagining that each document also becomes a separate page in the website? With README kinda working as some kind of index.html for postgres exporter?

ArthurSens · 2026-08-12T18:01:37Z

+- `latest` — the most recent release.
+- `vX.Y.Z` — a specific release, e.g. `v0.18.1`. Pin to a specific tag for production deployments so upgrades are intentional.
+- `master` — the latest build from the `master` branch, which may be unstable. Use this only for testing or development.


We don't need to explain semver here 🤔

My intent here was to list the tags that a normal user might care about. Discoverability of tags for docker images isn't always straightforward - you often have to go dig through a git repo or just read through Dockerhub tags to find what you're looking for.

Also, while our releases are formatted like semver (x.y.z), we don't really treat it as semver. We will make breaking changes on a Y update. And if you think of it like a library (which you will going forward) the PR you just had to make it embeddable is probably a breaking change even though it was not user visible.

ArthurSens · 2026-08-12T18:03:35Z

@@ -0,0 +1,59 @@
+# Docker Images


I wouldn't create a document called Docker, especially when Docker is already mentioned in the Getting Started.

Maybe in Getting Started, we could have different sections? Getting Started with Docker/Kubernetes/Binary/Ansible/whatever is available.

I'm imagining a component like this (change Java/Go with what is relevant to us)

Where the reader can click and choose the preferred way of getting started

I think that there's value here. The docker file talks about a lot more than you need just to get started. The image details are something that a user would have to go digging through code to understand if it's not called out.

ArthurSens · 2026-08-12T18:06:36Z

+| Collector | Default | Notes |
+|---|---|---|
+| `database` | enabled | |
+| `database_wraparound` | disabled | transaction ID wraparound risk |
+| `locks` | enabled | |
+| `long_running_transactions` | disabled | |
+| `postmaster` | disabled | |
+| `process_idle` | disabled | |
+| `replication` | enabled | |
+| `replication_slots` | enabled | |
+| `roles` | enabled | |
+| `settings` | enabled | values from `pg_settings` |
+| `stat_activity` | enabled | |
+| `stat_activity_autovacuum` | disabled | |
+| `stat_archiver` | enabled | |
+| `stat_bgwriter` | enabled | |
+| `stat_checkpointer` | disabled | PostgreSQL 17+ only |
+| `stat_database` | enabled | |
+| `stat_progress_vacuum` | enabled | |
+| `stat_replication` | enabled | |
+| `stat_statements` | disabled | requires the `pg_stat_statements` extension |
+| `stat_user_tables` | enabled | |
+| `stat_wal_receiver` | disabled | |
+| `statio_user_indexes` | disabled | |
+| `statio_user_tables` | enabled | |
+| `wal` | enabled | |
+| `xlog_location` | disabled | |
+| `buffercache_summary` | disabled | requires the `pg_buffercache` extension |


I'd love it if this table could be automated with mdox. We should have a hidden CLI flag that builds this table to make sure it is always up to date.

I also believe that we should have some meaninfull description for each option

could we have that abstraction in exporter-toolkit @nicolastakashi? :)

Not sure how yet, but I'm thking something about exporter toolkit managing collector enable/disable states, we could use that to have exporter toolkit automatically generate tables like this for documentation and us using the same state to enable/disable collectors.

Either way, this is work for the future :p

ArthurSens · 2026-08-12T18:07:56Z

+```yaml
+auth_modules:
+  foo: # referenced as ?auth_module=foo on /probe requests
+    type: userpass
+    userpass:
+      username: monitoring_user
+      password: monitoring_password
+    options:
+      # merged into the DSN as key=value query parameters
+      sslmode: require
+```


This one also, it would be awesome if we used mdox-exec=cat example.yaml and we actually use this file as part of our tests in CI to make sure it's always valid.

ArthurSens · 2026-08-12T18:08:25Z

@@ -0,0 +1,60 @@
+# Connecting to PostgreSQL


Isn't database permissions related to this topic? should we merge them?

nicolastakashi · 2026-08-13T19:37:51Z

+
+## Point Prometheus at it
+
+Add a scrape job to your Prometheus configuration:


Maybe worth a cross reference here pointing to the scrape config docs for more details, mentioning this is a simple example, wdyt?

nicolastakashi · 2026-08-13T19:39:35Z

+| Collector | Default | Notes |
+|---|---|---|
+| `database` | enabled | |
+| `database_wraparound` | disabled | transaction ID wraparound risk |
+| `locks` | enabled | |
+| `long_running_transactions` | disabled | |
+| `postmaster` | disabled | |
+| `process_idle` | disabled | |
+| `replication` | enabled | |
+| `replication_slots` | enabled | |
+| `roles` | enabled | |
+| `settings` | enabled | values from `pg_settings` |
+| `stat_activity` | enabled | |
+| `stat_activity_autovacuum` | disabled | |
+| `stat_archiver` | enabled | |
+| `stat_bgwriter` | enabled | |
+| `stat_checkpointer` | disabled | PostgreSQL 17+ only |
+| `stat_database` | enabled | |
+| `stat_progress_vacuum` | enabled | |
+| `stat_replication` | enabled | |
+| `stat_statements` | disabled | requires the `pg_stat_statements` extension |
+| `stat_user_tables` | enabled | |
+| `stat_wal_receiver` | disabled | |
+| `statio_user_indexes` | disabled | |
+| `statio_user_tables` | enabled | |
+| `wal` | enabled | |
+| `xlog_location` | disabled | |
+| `buffercache_summary` | disabled | requires the `pg_buffercache` extension |


I also believe that we should have some meaninfull description for each option

nicolastakashi · 2026-08-13T19:42:51Z

+
+Run `postgres_exporter --help` for the exact, current list of flags — new collectors are added over time and this table can drift.
+
+## Common flags


Are all those common flags comming from exporter toolkit? should we reference it here?

Many are or from prometheus/common. Updated this section.

nicolastakashi · 2026-08-13T19:43:10Z

+| `xlog_location` | disabled | |
+| `buffercache_summary` | disabled | requires the `pg_buffercache` extension |
+
+`pg_stat_statements` has its own sub-flags: `--collector.stat_statements.include_query` (off by default — includes raw query text), `--collector.stat_statements.query_length` (default 120), `--collector.stat_statements.limit` (default 100), and `--collector.stat_statements.exclude_databases` / `--collector.stat_statements.exclude_users` (comma-separated).


Should we have a dedicated section to what's pg_stat_statements?

nicolastakashi · 2026-08-13T19:43:39Z

+
+## Deprecated options
+
+These remain for backward compatibility but shouldn't be used in new deployments:


Aren't those removed on newer versions?

nicolastakashi · 2026-08-13T19:44:51Z

+Prometheus is typically configured to do this via relabeling so the target list can come from service discovery:
+
+```yaml
+scrape_configs:


same: https://github.com/prometheus-community/postgres_exporter/pull/1361/changes#r3778534453

Create a docs/ directory with user facing documentation. This covers getting started, running with docker, specifying secrets, configuration, and database permissions. This is all focused on the perspective of a user or someone deploying the exporter. Signed-off-by: Joe Adams <github@joeadams.io>

Clean up duplication on docker commands. Make the docs README more useful as a standalone page. Signed-off-by: Joe Adams <github@joeadams.io>

sysadmind · 2026-08-19T03:21:10Z

@ArthurSens yes I'm imagining each file becomes a navigation item in the site. One thing I also want to consider with this - people will also come directly to this repo to view docs, so I want to enable viewing them in Github and avoid anything too custom that reduces the value of them as standalone files in this repo.

Add more details on each flag and collector to help the user understand the purpose. Signed-off-by: Joe Adams <github@joeadams.io>

ArthurSens · 2026-08-19T13:53:40Z

I spent some time looking at how to pull exporter docs into prometheus.io. The docs site can support this with a latest-release-tag source for exporters, but each Markdown file needs the same frontmatter contract that the site uses for title/nav ordering.

Could you add this frontmatter while keeping the existing # heading in each file? Keeping the H1 means the files still read well on GitHub; the website will use the frontmatter for metadata and navigation.

docs/README.md:

---
title: postgres_exporter Documentation
nav_title: Overview
sort_rank: 1
---

docs/getting-started.md:

---
title: Getting Started
sort_rank: 2
---

docs/connecting.md:

---
title: Connecting to PostgreSQL
sort_rank: 3
---

docs/database-permissions.md:

---
title: Database Permissions
sort_rank: 4
---

docs/configuration.md:

---
title: Configuring the Exporter
nav_title: Configuration
sort_rank: 5
---

docs/secrets.md:

---
title: Secrets
sort_rank: 6
---

docs/docker.md:

---
title: Docker Images
nav_title: Docker
sort_rank: 7
---

docs/aws-rds.md:

---
title: Running Against AWS RDS
nav_title: AWS RDS
sort_rank: 8
---

One important detail: prometheus.io will pull exporter docs from the latest stable release tag, not directly from master. So after this merges, the docs will appear on the website once postgres_exporter cuts a release containing the docs/ directory.

ArthurSens reviewed Aug 12, 2026

View reviewed changes

nicolastakashi reviewed Aug 13, 2026

View reviewed changes

This was referenced Aug 15, 2026

collector: shared registry for collector enable/disable state (PoC) prometheus/exporter-toolkit#429

Draft

collector: use the shared exporter-toolkit collector registry (PoC) #1366

Draft

sysadmind added 2 commits August 18, 2026 22:35

Update getting started to show multiple options

e2b0127

Clean up duplication on docker commands. Make the docs README more useful as a standalone page. Signed-off-by: Joe Adams <github@joeadams.io>

sysadmind force-pushed the user-docs branch from 2e2d3cc to e2b0127 Compare August 19, 2026 03:14

Update configuration docs

3d2ee4a

Add more details on each flag and collector to help the user understand the purpose. Signed-off-by: Joe Adams <github@joeadams.io>

ArthurSens mentioned this pull request Aug 19, 2026

Add postgres exporter docs to website prometheus/docs#3076

Draft


		## Point Prometheus at it

		Add a scrape job to your Prometheus configuration:


		Run `postgres_exporter --help` for the exact, current list of flags — new collectors are added over time and this table can drift.

		## Common flags


		## Deprecated options

		These remain for backward compatibility but shouldn't be used in new deployments:

Uh oh!

Conversation

sysadmind commented Aug 8, 2026

Uh oh!

nicolastakashi commented Aug 10, 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!

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!

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!

sysadmind commented Aug 19, 2026

Uh oh!

ArthurSens commented Aug 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants