55. pepsi-status

Summarise the health of the mail pipeline.

55.1. Role

pepsi-status is the operator’s read-only health overview of the pipeline. It connects through the shared [pepsi-postgres] section, has no configuration of its own, and never modifies a row or issues a notification, so it is safe to run over SSH against a live deployment. Started as root it continues as the pepsi service account before connecting, so no sudo -u pepsi is needed. Reference: pepsi-status(1).

55.2. Features

• Queue — the pepsi.ingress backlog broken down by stage and status, with the age of the oldest message in each bucket.

• Stuck messages — the individual failed/timeout messages, oldest first, with the structured next-hop failure reason from state.bounce (remote MTA, SMTP code, enhanced status, reply text); capped by --limit.

• Delivery & failures — cumulative dispatch_stats/stage_stats counters: total messages processed, per-stage message counts, average processing time, worker timeouts and crashes.

• Outbound TLS — recent tls_session outcomes grouped by policy domain and result type (non-successful results marked), plus MX addresses the resolver cache has flagged as failing to connect.

--json emits the whole report as one JSON object for monitoring systems.

55.3. A note on “recent successes”

A successfully delivered message is deleted from the queue, so there is no per-message delivery log. The delivery figures are therefore the cumulative counters accumulated since the schema was created — lifetime totals, not a rolling time window. Only the queue snapshot and the TLS section (which is keyed by report-day) reflect genuinely recent activity.

55.4. See also

pepsi-queue, pepsi-tlsrpt, pepsi-dispatch, Architecture, pepsi-status(1), pepsi.conf(5).