..
  This file is part of PEPSI.
  Copyright (C) 2026 Pepsi contributors

  PEPSI is free software; you can redistribute it and/or modify it under the
  terms of the GNU Affero General Public License as published by the Free
  Software Foundation; either version 3, or (at your option) any later version.

============
pepsi-status
============

*Summarise the health of the mail pipeline.*

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: :manpage:`pepsi-status(1)`.

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.

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.

See also
========

:doc:`pepsi-queue`, :doc:`pepsi-tlsrpt`, :doc:`pepsi-dispatch`,
:doc:`../architecture`, :manpage:`pepsi-status(1)`, :manpage:`pepsi.conf(5)`.