Stats and Monitoring¶
MessageBus tracks per-channel counters automatically via a shared Stats instance.
Available Counters¶
For each channel named :orders, the following counters are tracked:
| Counter | Description |
|---|---|
:orders_published |
Messages MessageBus#publish accepted (a publish to an already-closed channel or with the wrong type raises and is not counted) |
:orders_delivered |
All subscribers ACKed (message fully delivered) |
:orders_nacked |
Nacks of any cause: nack!, a raising handler, close, or a publish with no subscribers (timeouts are counted separately) |
:orders_timed_out |
Delivery timeouts (auto-nack) |
:orders_dead_lettered |
Entries added to the DLQ |
:orders_throttled |
Publishes that were rate-limited |
published and delivered count once per message. nacked, timed_out and
dead_lettered count once per subscriber delivery, so one publish to a channel
with three subscribers can add up to 3 to each of them.
Reading Stats¶
bus.stats[:orders_published] # => 42
bus.stats[:orders_delivered] # => 40
bus.stats[:orders_dead_lettered] # => 2
Snapshot¶
Get all counters as a Hash:
Reset¶
Zero all counters:
Or reset everything (channels + stats):
Using Stats Directly¶
When using Channel without a MessageBus, pass a Stats instance:
stats = TypedBus::Stats.new
channel = TypedBus::Channel.new(:work, stats: stats, timeout: 5)
# ... publish and subscribe ...
stats[:work_delivered] # => N
A bare Channel records delivered, nacked, timed_out, dead_lettered
and throttled. It does not record published: that counter is incremented
by MessageBus#publish, so stats[:work_published] stays 0 here.
Monitoring Pattern¶
Combine stats with DLQ callbacks for real-time alerting. Because
dead_lettered counts per subscriber delivery and published counts per
message, their ratio is dead letters per publish, which can exceed 1 when a
channel has several subscribers: