63. pepsi-status

Summarise the health of the mail pipeline.

63.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 section of its own (the only other option it reads is [pepsi] MAILBOX_QUOTA, the site default an account with no row of its own inherits), 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).

63.2. Features

• Queue — the pepsi.workqueue 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 every reason recorded for them: the structured next-hop failure from state.bounce (remote MTA, SMTP code, enhanced status, reply text), the stage’s own state.last_error, and the dispatcher’s state.dispatch_error (a crashed or hung worker, an unconfigured stage); 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 — tls_session outcomes of the last seven UTC report-days (today’s included) grouped by policy domain and result type (non-successful results marked), plus MX addresses the resolver cache has flagged as failing to connect.

• Mailbox quotas — every account with quota accounting, oldest measurement first (the order pepsi-quota’s reconcile sweep works in), with its effective limit, the measured usage, the un-measured delivery estimate on top of it and the age of the measurement. An account appears here once something has been delivered to it, quota or no quota.

--json emits the whole report as one JSON object for monitoring systems, and --limit caps both the stuck-message list and the mailbox-quota list.

63.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.

63.4. See also

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