Prometheus metrics at /metrics, off unless an operator turns them on #50

New issue

Closed

opened 2026-09-06 15:46:47 +00:00 by tiagoagueda · 0 comments

tiagoagueda commented

2026-09-06 15:46:47 +00:00

Owner

Observation

enable "cleen" prometheus metrics collection at /metrics endpoint
enebled by env or option on server settings (default:false)

Shape

Off by default, and that is most of the design: POSTULO_METRICS_ENABLED (default
false) and a switch under Server settings → Monitoring. Off, the address is a plain 404 —
not a 403, which would confirm that something is there.

Clean means the numbers an operator needs to run the instance, and nothing about the
people on it:

postulo_info{version, python, django} — one gauge carrying the build, the conventional
way to expose it.
HTTP: request count and a duration histogram by method, view name and status. The
view's name and never the path, so no company, application id or search text can become
a label.
The scheduler: when it last ran, reminders announced, document copies sent and failed,
syncs run and failed.
Work waiting: pending document copies, sync connections due, suggestions unreviewed.
Health: database reachable, migrations applied.
Size, as counts only: people, applications, documents, plugins installed.

What is deliberately absent: anything per person, per company or per application. A
metric with somebody's identifier in a label is a record of what they are doing, exported
somewhere else, and calling it monitoring does not change that.

Who may read it: a bearer token (POSTULO_METRICS_TOKEN) or an allow-list of
addresses, at the operator's choice. With neither set the endpoint is readable by anybody
who can reach the instance, and the page says exactly that rather than implying it is
protected.

Classification

Enhancement. Not breaking: nothing exists until an operator asks for it.

Depends on

Nothing. It shares the "off unless asked, environment variable or setting" pattern with
#51, and the two switches should live in one Monitoring section.

Open questions

prometheus_client, or write the exposition format by hand? It is a handful of lines
for the text format. Proposal: decide on the answer to the next question first.
Per worker or aggregated? With three gunicorn workers a counter is per process unless a
shared directory is configured. Whichever way it goes must be documented, because a
graph quietly showing a third of the traffic is worse than no graph at all.

## Observation > enable "cleen" prometheus metrics collection at /metrics endpoint > enebled by env or option on server settings (default:false) ## Shape **Off by default**, and that is most of the design: `POSTULO_METRICS_ENABLED` (default false) and a switch under *Server settings → Monitoring*. Off, the address is a plain 404 — not a 403, which would confirm that something is there. **Clean** means the numbers an operator needs to run the instance, and nothing about the people on it: - `postulo_info{version, python, django}` — one gauge carrying the build, the conventional way to expose it. - HTTP: request count and a duration histogram by method, **view name** and status. The view's name and never the path, so no company, application id or search text can become a label. - The scheduler: when it last ran, reminders announced, document copies sent and failed, syncs run and failed. - Work waiting: pending document copies, sync connections due, suggestions unreviewed. - Health: database reachable, migrations applied. - Size, as counts only: people, applications, documents, plugins installed. **What is deliberately absent**: anything per person, per company or per application. A metric with somebody's identifier in a label is a record of what they are doing, exported somewhere else, and calling it monitoring does not change that. **Who may read it**: a bearer token (`POSTULO_METRICS_TOKEN`) or an allow-list of addresses, at the operator's choice. With neither set the endpoint is readable by anybody who can reach the instance, and the page says exactly that rather than implying it is protected. ## Classification Enhancement. Not breaking: nothing exists until an operator asks for it. ## Depends on Nothing. It shares the "off unless asked, environment variable or setting" pattern with #51, and the two switches should live in one *Monitoring* section. ## Open questions 1. `prometheus_client`, or write the exposition format by hand? It is a handful of lines for the text format. Proposal: decide on the answer to the next question first. 2. Per worker or aggregated? With three gunicorn workers a counter is per process unless a shared directory is configured. Whichever way it goes must be documented, because a graph quietly showing a third of the traffic is worse than no graph at all.

tiagoagueda added this to the 0.2.0 milestone

2026-09-06 15:46:47 +00:00

tiagoagueda added the

enhancement

observability

tier/4

labels

2026-09-06 15:46:47 +00:00

tiagoagueda referenced this issue

2026-09-06 15:46:48 +00:00

Serve the log at /logs for a collector, off unless an operator turns it on #51

tiagoagueda referenced this issue from a commit