Health and operational snapshots

ManagedConsumer::snapshot() is an immutable, serializable operational view of one Consumer runtime. It does not require tracing to be enabled. HTTP /health or /ready endpoints are not added automatically; the application uses the snapshot in its own health or orchestration adapter.

Decide from the same snapshot#

use lilyrs::consumer::ManagedConsumer;

fn health(consumer: &ManagedConsumer) -> (bool, bool) {
    let snapshot = consumer.snapshot();
    println!("lifecycle={:?}, ready_queues={}, handlers={}",
        snapshot.lifecycle, snapshot.ready_queues, snapshot.registered_handlers);
    (snapshot.live, snapshot.ready)
}

This helper obtains liveness and readiness from the same sample. live is the lifecycle’s process-liveness opinion; broker recovery alone does not make the process dead. ready requires the necessary queues, admission, shutdown state and any enabled transactional outbox relay to be ready.

Interpret states correctly#

Other queues may continue receiving deliveries while one queue recovers; admission can be PartiallyOpen while aggregate ready is false. last_failure_code is retained even after successful recovery. Its presence does not mean the Consumer is currently unhealthy; ready is authoritative for current admission.

Separate counters from audit records#

deliveries contains bounded aggregate counters for handler success/failure/panic, confirmed retry/dead letter, original ACK, NACK/requeue, unresolved and in-flight work. They are independent of tracing sampling. Handler success and ACK success remain separate counters; do not substitute one for the other.

The snapshot contains no body, event ID, routing key, broker endpoint or credential. Lock-free counters are sampled on a best-effort point-in-time basis; this is not a transactionally consistent accounting barrier or a complete exactly-once audit ledger. Do not expect every counter to reconcile atomically in a single sample.

Transaction and shutdown fields#

transactional_inbox and transactional_outbox exist only when the corresponding transactional backend features are compiled. They carry bounded aggregate evidence rather than payload, event, handler or database-cell identities. Relay readiness participates in aggregate ready.

shutdown.requested records a request, while shutdown.completed records the actual runtime join. To assess success, inspect completion, dependencies and drain/close evidence in the optional report. The shutdown guide explains Failed, Incomplete and is_success(); a missing report is not successful cleanup.

When event-level diagnostics are needed#

The separate QueueService::delivery_terminal_observations() API can retain at most 4096 bounded settlement observations. Bodies are absent but event IDs may be present; the aggregate snapshot’s event-ID-free contract does not extend to this API. Store or lock contention losses appear in the dropped counter.

Consider this surface for access-controlled diagnostics rather than automatically adding it to public health responses. Its best-effort history is neither a durable audit nor an unlimited replay record. When needed, resolve QueueService through your shared DI owner instead of assuming the handle exposes a public API to retrieve Consumer’s container.