Criticality Tiered Reporting
A reporter that emits at one volume is wrong at every volume. Page on
everything and the operator mutes you; report nothing and a real failure passes
unnoticed. The fix is to tier the signal by how much the consumer needs to act
on it, then route each tier to a channel matched to that urgency.
The tiers
Classify every reportable event into one of three tiers and route accordingly:
- Down or blocking — the work has stopped, is stuck, or needs a human
decision to proceed. This is the only tier that may interrupt a person:
page, alert, or message a channel someone watches. It must be actionable —
what broke, what is blocked, and the first step to unblock.
- Routine progress — the work is proceeding normally: started, milestone
reached, finished. Summarize, do not interrupt. A periodic digest, a
status surface someone can pull, or a single completion message — not a ping
per step.
- Noise — heartbeats, retried-and-recovered transients, per-iteration
detail. Stay silent on the active channels; write it to logs or metrics
for later inspection, not to anyone's attention.
Route to the consumer's need, not your chattiness
The tier is defined by what the consumer must do, not by how much is
happening internally. A thousand successful iterations are still tier "routine"
(one summary). One stuck queue is tier "blocking" (one page). Map each tier to a
channel whose interruption level matches: interrupting channel for blocking,
pull/digest surface for progress, log/metric sink for noise.
Design rules
- Escalate, don't duplicate: a blocking event pages once; it does not also
spray progress updates. Lower tiers never borrow the higher tier's channel.
- Actionable at the top: every interrupting message names the problem and a
next step. "Something went wrong" is not a tier-one message.
- Recovered transients are noise: a retry that succeeded is not a page;
count it as a metric. Only a transient that exhausts retries escalates.
- Make routine pullable: progress should be queryable on demand so the
consumer checks when they want, instead of being pushed each step.
- Silence is a valid output: when nothing crosses a tier threshold, emit
nothing to attention channels. No-news is good news, by design.
Anti-patterns
- alerting on every event so real failures drown in green noise (alert fatigue)
- emitting a notification per step of a long routine job
- a "failure" page that contains no cause and no next action
- paging on a transient that already recovered on retry
- silence by omission: a worker that simply never reports, so a real stall is
invisible until someone notices the absence of output
Done means
Events are classified into down/blocking, routine progress, and noise; each tier
routes to a channel matched to its urgency; interrupting messages are actionable;
routine is summarized or made pullable; and noise stays out of attention
channels while remaining inspectable in logs or metrics.
1---2name: criticality-tiered-reporting3description: Use when deciding what a service or worker should report and how loudly — alerts, progress updates, logs, notifications. Tier output by criticality so the important signal is not buried in routine chatter.4---56# Criticality Tiered Reporting78A reporter that emits at one volume is wrong at every volume. Page on9everything and the operator mutes you; report nothing and a real failure passes10unnoticed. The fix is to **tier the signal by how much the consumer needs to act11on it**, then route each tier to a channel matched to that urgency.1213## The tiers1415Classify every reportable event into one of three tiers and route accordingly:1617- **Down or blocking** — the work has stopped, is stuck, or needs a human18 decision to proceed. This is the only tier that may **interrupt** a person:19 page, alert, or message a channel someone watches. It must be actionable —20 what broke, what is blocked, and the first step to unblock.21- **Routine progress** — the work is proceeding normally: started, milestone22 reached, finished. **Summarize**, do not interrupt. A periodic digest, a23 status surface someone can pull, or a single completion message — not a ping24 per step.25- **Noise** — heartbeats, retried-and-recovered transients, per-iteration26 detail. **Stay silent** on the active channels; write it to logs or metrics27 for later inspection, not to anyone's attention.2829## Route to the consumer's need, not your chattiness3031The tier is defined by **what the consumer must do**, not by how much is32happening internally. A thousand successful iterations are still tier "routine"33(one summary). One stuck queue is tier "blocking" (one page). Map each tier to a34channel whose interruption level matches: interrupting channel for blocking,35pull/digest surface for progress, log/metric sink for noise.3637## Design rules3839- **Escalate, don't duplicate**: a blocking event pages once; it does not also40 spray progress updates. Lower tiers never borrow the higher tier's channel.41- **Actionable at the top**: every interrupting message names the problem and a42 next step. "Something went wrong" is not a tier-one message.43- **Recovered transients are noise**: a retry that succeeded is not a page;44 count it as a metric. Only a transient that exhausts retries escalates.45- **Make routine pullable**: progress should be queryable on demand so the46 consumer checks when they want, instead of being pushed each step.47- **Silence is a valid output**: when nothing crosses a tier threshold, emit48 nothing to attention channels. No-news is good news, by design.4950## Anti-patterns5152- alerting on every event so real failures drown in green noise (alert fatigue)53- emitting a notification per step of a long routine job54- a "failure" page that contains no cause and no next action55- paging on a transient that already recovered on retry56- silence by omission: a worker that simply never reports, so a real stall is57 invisible until someone notices the absence of output5859## Done means6061Events are classified into down/blocking, routine progress, and noise; each tier62routes to a channel matched to its urgency; interrupting messages are actionable;63routine is summarized or made pullable; and noise stays out of attention64channels while remaining inspectable in logs or metrics.
selamy-labs