standard_health 0.3.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4bc8cdc021df7485cb1443cf6902b6fee31627ad6135d9eef6f284cd5eed47e0
-  data.tar.gz: bfd4e8a50e602685430481b85a0ebf604d1e930db71ce47492036d772f4aa13c
+  metadata.gz: 68d0908117b9ae70545445465e84f94b4c6ccc5ebecb2aa6ab05b3aafa5ba9f7
+  data.tar.gz: 52c3ffe85837e265283011db180de726957df2eecd09b971efc369e879ae4ec3
 SHA512:
-  metadata.gz: 32ec724c45eb9899e4d241d5681d296e1ac5745c3ff1852b5a187dea1fcc2a6b7ff7a922c08f925f0b59189ca8523d11fd034a5743f394186d91c4c1f2d8596d
-  data.tar.gz: 4711ceae81d4b9d0c19b440cc62fe8b2677ce569661adf741775ecc7933ee93c68402c8141ca830e76a6a75aa023c3f7759ef4d68a175d38280a2d971e83b964
+  metadata.gz: 379b80dbdf211c4c1a3e7639ec6cc926219949f9c352fbadddfada54bdea53f20df6ab52d5672baa0974bb6b2952b5f5e67b9069191d980baff1de0d3c77f972
+  data.tar.gz: feaba7a044e8e63e4dc60ad4d010edfbe197691596ea2520632c4d590f6e52907d9275a5825dea8deff42c716517cb569b54f2824460820327f5003e9e5b5157

data/CHANGELOG.md

@@ -7,6 +7,124 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.1] - 2026-07-29
+
+Observability release. Until now the gem emitted **nothing** — no events, no
+logs, no metrics. It computed `latency_ms` for every check and discarded it
+into the response body. A failing check was invisible unless somebody happened
+to call `/ready` at the right moment, so there was no history, no alerting
+hook, and no way to chart check latency.
+
+Everything here is **additive**: no status code, roll-up rule, or response
+field changes meaning, so this is a pure `bundle update` for consumers on
+`~> 0.4`.
+
+### Added
+
+- **Instrumentation.** Three events over whichever bus is live (`Rails.event`
+  on Rails 8.1+, `ActiveSupport::Notifications` otherwise), matching
+  `standard_circuit`'s `EventEmitter` idiom:
+  - `standard_health.check.completed` — `name`, `critical`, `status`,
+    `latency_ms`, `error_class`, `error_message`
+  - `standard_health.check.timed_out` — `name`, `critical`, `timeout_s`
+  - `standard_health.ready.evaluated` — `status`, `duration_ms`, `failed[]`
+- **Three built-in subscribers**, registered by a new engine initializer
+  (`after: :load_config_initializers`, so host config is final):
+  - `Notifiers::Logger` — **silent while healthy.** `warn` on degraded,
+    `error` on unavailable. Health events are polls (~6/min/instance), not
+    transitions; a line per evaluation is ~8,640/day/instance of "everything
+    is fine".
+  - `Notifiers::Sentry` — **transition-only**, with a 60s repeat floor and
+    one `info` on recovery. Capturing every non-ok poll would turn a
+    five-minute outage into ~30 duplicate issues. Mutex-guarded (Puma is
+    threaded). Sentry stays a soft dependency.
+  - `Notifiers::Metrics` — per-poll counters and latency distributions. This
+    fires on every evaluation on purpose: it is what makes `latency_ms`
+    chartable.
+- `config.add_notifier` for host-supplied `call(event_name, payload)`
+  subscribers, validated at add time.
+- Config: `instrumentation_enabled`, `logger`, `sentry_enabled`,
+  `metric_prefix`.
+- **Per-check timeout machinery** — `default_check_timeout`,
+  `total_check_budget`, and a `timeout:` option on `register_check`. Uses a
+  dedicated `StandardHealth::CheckTimeout` rather than bare `Timeout::Error`,
+  so a timeout the host raised for its own reasons is never mislabelled as
+  ours. **All default to `nil` (OFF)** — see below.
+- `status` on `/diagnostics/env`: `:ok` or `:incomplete` (a `required` var is
+  missing). **Additive — the endpoint still returns 200 either way.**
+
+### Fixed
+
+- `Check#with_timing` now records `error_class` alongside the message. All
+  three built-in checks route through it, so without this every real driver
+  failure reached the aggregator with no class and the redacted body fell back
+  to a generic `StandardError` — exactly the useless label redaction exists to
+  replace.
+- Failure detail (`error_class` + `error_message`) now rides on
+  `ready.evaluated`, not only on `check.completed`. Both built-in subscribers
+  are driven by `ready.evaluated` (deliberately — it is the transition-gated
+  event), so the message would otherwise have been deleted from the response
+  without ever reaching logs or Sentry.
+
+### Security
+
+- **`/ready` no longer returns raw exception messages.** The endpoint is
+  unauthenticated by design, and a driver error will happily tell an anonymous
+  caller the database host, port and username — during exactly the incident
+  you least want to be leaking. Failing rows now carry `error_class` and a
+  stable `error_code` instead. The full message is not lost: it goes to logs
+  and Sentry via the instrumentation above, which is why redaction ships in
+  the same release rather than separately.
+  - `config.expose_check_errors = true` restores the previous bodies.
+  - `config.detail_token` + an `X-Health-Token` header is a break-glass path
+    for on-call, compared in constant time.
+  - `status`, `name`, `critical`, `latency_ms` and `generated_at` are
+    unchanged, so dashboards and existing specs keep working.
+
+### Notes on what is deliberately NOT on
+
+Timeouts and the total budget default to **off**, giving byte-identical
+behaviour to 0.4.0. Turning them on is a semantic change: a check that has
+always been slow-but-fine starts reporting `:fail`, and for a critical check
+that pulls the instance out of rotation. Shipping that in a patch, to five
+apps, on a `bundle update`, is how you cause the outage you were preventing.
+
+The machinery ships now so apps can opt in per check, and so the events above
+can reveal the real p99 latencies. Defaults get chosen from that data in
+0.5.0, which requires an explicit Gemfile edit.
+
+One semantic guard is already in place for when they are enabled: a check
+skipped because the budget ran out reports `:skipped` and floors the roll-up
+at `:degraded` — **never `:unavailable`**, even when the skipped check is
+critical. Otherwise a slow *non-critical* check could exhaust the budget,
+leave the database check unrun, and pull a healthy instance out of rotation.
+
+`total_check_budget` bounds **how many checks run**, not how long the probe
+takes — it is evaluated before each check starts, not during one. Clamping
+each check to the remaining budget would close that gap but would apply
+`Timeout.timeout` to checks whose author never asked for one, so setting a
+budget deliberately does not opt you into that. Asserted by spec, not just
+documented.
+
+A second reason to leave them off: `Timeout.timeout` raises into the running
+thread at an arbitrary point, so firing one mid-connection-checkout can return
+a broken connection to the pool. The dedicated `CheckTimeout` fixes
+mislabelling, not this. The README now carries the full caveat — the right
+answer for datastore checks is usually a driver-level timeout
+(`connect_timeout` / `statement_timeout`), not this setting.
+
+## [0.4.0] - 2026-05-05
+
+### Added
+
+- Consumer-presence detection for `consumed_by:` paths. `audit()` accepts an optional `root:` keyword (host-app root). When given, each entry whose `consumed_by:` is set is checked against the host app's tree, producing a new `consumer:` field on the audit row: `:present` (file exists and references the var via `ENV[...]` or `ENV.fetch(...)`), `:file_missing` (path missing on disk), or `:not_referenced` (file exists but no `ENV` reference). Catches renamed/deleted consumer files, `consumed_by:` typos, and vars declared in env-spec but never actually `ENV.fetch`'d.
+- `DiagnosticsController#env` now passes `Rails.root` automatically, so host apps get the new `consumer:` field with no host-side change.
+- Deprecation metadata on `required` / `recommended`: `deprecated: true`, `sunset_on:` (target removal date), `replacement:` (what to use instead). Surfaced verbatim in audit rows. Lets vars be staged for removal with audit trail.
+
+### Changed
+
+- `Entry` struct extended with `deprecated`, `sunset_on`, `replacement`. Backward-compatible — every 0.3.0 spec produces identical audit output when the new opts aren't used and `root:` isn't passed.
+
 ## [0.3.0] - 2026-04-29
 
 ### Added

data/{MIT-LICENSE → LICENSE}

@@ -1,4 +1,6 @@
-Copyright (c) 2026 Jaryl Sim
+The MIT License (MIT)
+
+Copyright (c) 2026 Rarebit One
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the
@@ -13,8 +15,8 @@ included in all copies or substantial portions of the Software.
 
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
-CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
-TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
-SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -184,6 +184,23 @@ Audit rows for entries declared inside a `group` block carry a `group` key:
 
 Entries declared outside any `group` block omit the `group` key entirely.
 
+### Top-level status
+
+Since 0.4.1 the response carries a `status` alongside the audit, so a caller
+can gate on one field instead of re-implementing the roll-up:
+
+```json
+{ "mode": "production", "status": "incomplete", "audit": [ ... ] }
+```
+
+`incomplete` means at least one `required` var is missing; `recommended` is
+advisory and never affects it.
+
+**The endpoint still returns 200 either way in 0.4.1.** That is deliberate: it
+gives monitors a release to migrate onto the field before 0.5.0 makes
+`incomplete` a 503. Flipping the status code without that window would
+silently redden every existing caller.
+
 ### Backward compatibility
 
 All v0.2.0 specs continue to produce identical audit output in v0.3.0. The new fields (`description`, `consumed_by`, `group`, `reason`) appear only when the corresponding feature is used; the new `:not_applicable` status only appears when a predicate suppresses an entry.
@@ -283,6 +300,130 @@ When `diagnostics_parent_controller` is unset, `DiagnosticsController` falls bac
 
 The orchestrator should pull the instance out of rotation only on 503; degraded means "still serving, page someone."
 
+`skipped` also exists, for a check the total budget never reached (see
+Timeouts). A skip floors the roll-up at `degraded` and **never** produces
+`unavailable`, even for a critical check.
+
+## Failure detail is redacted
+
+Since 0.4.1, a failing check reports the exception **class** rather than its
+message:
+
+```json
+{ "name": "database", "critical": true, "status": "fail",
+  "error_class": "PG::ConnectionBad", "error_code": "pg_connection_bad" }
+```
+
+`/ready` is unauthenticated by design — probes carry no credentials — and a
+raw driver message will happily tell an anonymous caller the database host,
+port and username. The full message still reaches your logs and Sentry through
+the instrumentation below; it just isn't in the public body.
+
+```ruby
+c.expose_check_errors = true       # restore pre-0.4.1 verbose bodies
+c.detail_token = ENV["HEALTH_DETAIL_TOKEN"]   # X-Health-Token unlocks detail
+```
+
+`status`, `name`, `critical`, `latency_ms` and `generated_at` are unchanged.
+
+## Instrumentation
+
+The gem emits events on whichever bus is live — `Rails.event` on Rails 8.1+,
+`ActiveSupport::Notifications` otherwise:
+
+| Event | Payload |
+|---|---|
+| `standard_health.check.completed` | `name`, `critical`, `status`, `latency_ms`, `error_class`, `error_message` |
+| `standard_health.check.timed_out` | `name`, `critical`, `timeout_s` |
+| `standard_health.ready.evaluated` | `status`, `duration_ms`, `failed[]` |
+
+Three subscribers are registered automatically. Their noise profiles differ on
+purpose, because health events are **polls**, not state transitions — a 10s
+probe period means ~6 evaluations/minute/instance:
+
+- **Logger** — silent while healthy. `warn` on degraded, `error` on
+  unavailable. A line per evaluation would be ~8,640/day/instance of
+  "everything is fine".
+- **Sentry** — only on status **change**, plus a 60s repeat floor for a
+  sustained bad state, plus one `info` on recovery. Capturing every non-ok
+  poll would turn a five-minute outage into ~30 duplicate issues. Sentry is a
+  soft dependency; no gemspec entry.
+- **Metrics** — every poll, deliberately. Counters plus latency
+  distributions are what make `latency_ms` chartable.
+
+```ruby
+StandardHealth.configure do |c|
+  c.instrumentation_enabled = true    # default
+  c.logger        = Rails.logger      # default: Rails.logger
+  c.sentry_enabled = true             # default
+  c.metric_prefix  = "health"         # default
+
+  c.add_notifier(MyNotifier.new)      # must respond to call(event_name, payload)
+end
+```
+
+## Timeouts
+
+**Off by default.** Both settings are `nil`, which is byte-identical to 0.4.0.
+
+```ruby
+c.default_check_timeout = 2.0        # seconds, per check
+c.total_check_budget    = 5.0        # checked BEFORE each check starts
+c.register_check :db, MyCheck, critical: true, timeout: 1.0   # per-check override
+```
+
+**`total_check_budget` bounds how many checks RUN, not how long the probe
+takes.** It is evaluated before each check starts, not during one. With a 1s
+budget and a first check that blocks for 30s, `/ready` still takes 30s — only
+the checks *after* it are skipped.
+
+Clamping each check to the remaining budget would close that gap, and is
+deliberately not done: it would apply `Timeout.timeout` to checks whose author
+never asked for one, and that mechanism raises into the thread at an arbitrary
+point (see below). Setting a budget must not silently opt you into that. To
+bound wall-clock, put a `timeout:` on the checks that can safely take one.
+
+Enabling them is a semantic change — a check that has always been
+slow-but-fine starts reporting `:fail`, and for a critical check that pulls
+the instance out of rotation. Pick values from observed `latency_ms` rather
+than intuition; that is what the `check.completed` events are for.
+
+Checks the total budget never reaches report `:skipped`, never silently `:ok`.
+A skip alone floors the roll-up at `degraded` — otherwise a slow *non-critical*
+check could exhaust the budget, leave the database check unrun, and pull a
+healthy instance out of rotation.
+
+Checks run **sequentially**. They are not parallelised on purpose: running
+them in threads would mean connection checkouts from the health path, and a
+health endpoint that can exhaust the connection pool is a worse problem than
+the one it was added to solve.
+
+### ⚠ Know what `Timeout.timeout` actually does before enabling this
+
+Ruby's `Timeout.timeout` interrupts by raising **into the running thread at an
+arbitrary point**. It cannot wait for a safe boundary. If a timeout fires
+while a check is mid-way through a non-atomic operation — say a connection
+checkout in the `ActiveRecord` check — the connection can be returned to the
+pool in a broken state. You would have traded a slow check for a corrupted
+pool, on the health path, during an incident.
+
+The dedicated `CheckTimeout` class solves the *mislabelling* problem (a host's
+own `Timeout::Error` is never mistaken for ours). **It does not solve this
+one.** Nothing can, at this layer.
+
+So, before turning timeouts on:
+
+- Prefer a driver-level timeout where one exists — `connect_timeout` /
+  `statement_timeout` on the database, a client timeout on an HTTP dependency.
+  Those abort at a safe point because the driver owns the operation.
+- Reserve `timeout:` here for checks whose `run` is genuinely interruptible —
+  typically your own custom checks — rather than the built-in datastore ones.
+- Set the value comfortably above observed p99 (see the `latency_ms` in
+  `check.completed`), so it fires on a hang rather than on a slow day.
+
+This is why the defaults ship as `nil` and why choosing them is deferred: the
+right answer is usually a driver timeout, not this.
+
 ## License
 
 MIT.

data/app/controllers/standard_health/diagnostics_controller.rb

@@ -19,14 +19,36 @@ module StandardHealth
     def env
       spec = StandardHealth.config.env_spec
       mode = ENV["APP_ENVIRONMENT"].to_s
+      root = defined?(Rails) ? Rails.root : nil
 
-      audit = spec ? spec.audit(ENV.to_h, mode: mode) : []
+      audit = spec ? spec.audit(ENV.to_h, mode: mode, root: root) : []
 
       render json: {
         mode: mode,
+        status: audit_status(audit),
         audit: audit,
         generated_at: Time.now.utc.iso8601
       }
     end
+
+    private
+
+    # Top-level verdict so a caller can gate on ONE field instead of
+    # re-implementing the roll-up over `audit`.
+    #
+    #   :ok         — nothing required is missing
+    #   :incomplete — at least one `required` var is missing
+    #
+    # ADDITIVE ONLY in 0.4.1: the endpoint still returns 200 either way, so
+    # nothing that asserts on the status code breaks. That is the point —
+    # it gives monitors a release in which to migrate onto this field before
+    # 0.5.0 makes `:incomplete` a 503. Without the migration window, turning
+    # the code non-200 would silently redden every existing caller.
+    def audit_status(audit)
+      incomplete = Array(audit).any? do |row|
+        row[:level].to_s == "required" && row[:status].to_s == "missing"
+      end
+      incomplete ? :incomplete : :ok
+    end
   end
 end

data/app/controllers/standard_health/health_controller.rb

@@ -12,10 +12,38 @@ module StandardHealth
     # Readiness probe. Runs every registered check and returns:
     #   200 if the rolled-up status is :ok or :degraded
     #   503 if any critical check failed (:unavailable)
+    #
+    # Failure detail is REDACTED by default — see StandardHealth::Redactor.
+    # This endpoint is unauthenticated so probes need no credentials, and a
+    # raw driver error will happily tell an anonymous caller the database
+    # host, port and username. The full message goes to logs and Sentry
+    # instead. Status codes and every other field are unchanged.
     def ready
       result = StandardHealth::Aggregator.call
       http_status = result[:status] == :unavailable ? :service_unavailable : :ok
-      render json: result, status: http_status
+      render json: StandardHealth::Redactor.call(result, expose: expose_errors?),
+             status: http_status
+    end
+
+    private
+
+    # Detail is exposed when the host opted in globally, or when the caller
+    # presents the break-glass token. Compared in constant time: the token is
+    # a secret, and a naive == leaks its length and prefix to a patient
+    # attacker on an endpoint that is public by design.
+    def expose_errors?
+      config = StandardHealth.config
+      return true if config.expose_check_errors
+
+      token = config.detail_token
+      return false if token.nil? || token.empty?
+
+      presented = request.headers["X-Health-Token"].to_s
+      return false if presented.empty?
+
+      ActiveSupport::SecurityUtils.secure_compare(presented, token)
+    rescue StandardError
+      false
     end
   end
 end

data/lib/standard_health/aggregator.rb

@@ -1,48 +1,187 @@
 # frozen_string_literal: true
 
+require "timeout"
+
 module StandardHealth
+  # Raised internally when a check exceeds its timeout.
+  #
+  # A DEDICATED subclass, never bare `Timeout::Error`: `Timeout.timeout` with
+  # the default class would also swallow a timeout the host app raised for its
+  # own reasons and mislabel it as ours. Passing our own class means we only
+  # ever catch the one we threw.
+  class CheckTimeout < ::Timeout::Error; end
+
   # Runs all registered checks and rolls them up into a single status.
   #
   # Status semantics:
   #   :ok           — every check returned :ok
-  #   :degraded     — at least one non-critical check failed
+  #   :degraded     — at least one non-critical check failed, OR a check was
+  #                   skipped because the total budget ran out
   #   :unavailable  — at least one critical check failed
   #
-  # The aggregator never raises. Each check is invoked through
-  # `safe_run` which catches `StandardError` so a buggy custom check
-  # cannot take down /ready.
+  # The aggregator never raises. Each check is invoked through `safe_run`
+  # which catches `StandardError` so a buggy custom check cannot take down
+  # /ready. Instrumentation is held to the same bar — every emit is wrapped
+  # so a broken subscriber cannot become a new way for /ready to 500.
   class Aggregator
     def self.call(checks: StandardHealth.config.checks, now: Time.now.utc)
-      check_rows = checks.map { |reg| safe_run(reg) }
+      started = monotonic
+      budget = StandardHealth.config.total_check_budget
+
+      check_rows = checks.map do |reg|
+        if budget_exhausted?(budget, started)
+          row = skipped_row(reg, budget)
+          # Skips emit too. Without this a skip is invisible to the Metrics
+          # notifier — the only trace would be a name inside ready.evaluated's
+          # `failed[]`, with no per-check counter — so once a budget is
+          # enabled you could not answer "how often is check X getting
+          # skipped", which is exactly the question a budget creates.
+          emit_check(row)
+          row
+        else
+          safe_run(reg)
+        end
+      end
+
+      duration_ms = ((monotonic - started) * 1000).round
+      status = overall_status(check_rows)
+
+      failing = check_rows.reject { |r| r[:status] == :ok }
+
+      emit(
+        "standard_health.ready.evaluated",
+        status: status,
+        duration_ms: duration_ms,
+        failed: failing.map { |r| r[:name] },
+        # The full failure detail rides on THIS event, not only on the
+        # per-check one. Redaction removes the message from the HTTP body on
+        # the promise that it still reaches logs and Sentry — but both of
+        # those subscribers are driven by ready.evaluated (deliberately: it
+        # is the transition-gated event, so they don't fire per poll). If the
+        # message only existed on check.completed, redaction would delete the
+        # last copy instead of relocating it.
+        failures: failing.map do |r|
+          {
+            name: r[:name],
+            critical: r[:critical],
+            status: r[:status],
+            error_class: r[:error_class],
+            error_message: r[:error]
+          }.compact
+        end
+      )
+
       {
-        status: overall_status(check_rows),
+        status: status,
         checks: check_rows,
         generated_at: now.iso8601
       }
     end
 
     def self.safe_run(reg)
-      result = reg.klass.new(name: reg.name, critical: reg.critical).run
-      result.merge(name: reg.name, critical: reg.critical)
+      timeout = reg.timeout || StandardHealth.config.default_check_timeout
+      instance = reg.klass.new(name: reg.name, critical: reg.critical)
+
+      result =
+        if timeout
+          Timeout.timeout(timeout, CheckTimeout) { instance.run }
+        else
+          instance.run
+        end
+
+      row = result.merge(name: reg.name, critical: reg.critical)
+      emit_check(row)
+      row
+    rescue CheckTimeout
+      emit("standard_health.check.timed_out",
+           name: reg.name, critical: reg.critical, timeout_s: timeout)
+      row = {
+        name: reg.name,
+        critical: reg.critical,
+        status: :fail,
+        error: "timed out after #{timeout}s",
+        error_class: "StandardHealth::CheckTimeout"
+      }
+      emit_check(row)
+      row
     rescue StandardError => e
-      {
+      row = {
         name: reg.name,
         critical: reg.critical,
         status: :fail,
-        error: e.message
+        error: e.message,
+        error_class: e.class.name
       }
+      emit_check(row)
+      row
     end
     private_class_method :safe_run
 
+    def self.budget_exhausted?(budget, started)
+      return false unless budget
+
+      (monotonic - started) >= budget
+    end
+    private_class_method :budget_exhausted?
+
+    # A check the total budget never reached. `:skipped`, never silently
+    # `:ok` — an unperformed check is not a healthy one.
+    def self.skipped_row(reg, budget)
+      {
+        name: reg.name,
+        critical: reg.critical,
+        status: :skipped,
+        error: "skipped — total check budget of #{budget}s exhausted"
+      }
+    end
+    private_class_method :skipped_row
+
     def self.overall_status(rows)
       return :ok if rows.empty?
 
       failures = rows.reject { |r| r[:status] == :ok }
       return :ok if failures.empty?
-      return :unavailable if failures.any? { |r| r[:critical] }
+
+      # A SKIP MUST NEVER PRODUCE :unavailable, even for a critical check.
+      # Otherwise a slow *non-critical* check could exhaust the budget, leave
+      # the database check unrun, and pull a perfectly healthy instance out of
+      # rotation — a self-inflicted outage caused by the safety mechanism.
+      # Skips floor the result at :degraded; only a real critical FAILURE
+      # reaches :unavailable.
+      return :unavailable if failures.any? { |r| r[:critical] && r[:status] != :skipped }
 
       :degraded
     end
     private_class_method :overall_status
+
+    def self.emit_check(row)
+      emit(
+        "standard_health.check.completed",
+        name: row[:name],
+        critical: row[:critical],
+        status: row[:status],
+        latency_ms: row[:latency_ms],
+        error_class: row[:error_class],
+        error_message: row[:error]
+      )
+    end
+    private_class_method :emit_check
+
+    # Belt and braces on top of EventEmitter's own rescue. The never-raise
+    # rule names this file, and instrumentation is the newest way to violate
+    # it — so the call site guards too.
+    def self.emit(event_name, **payload)
+      return unless StandardHealth.config.instrumentation_enabled
+
+      EventEmitter.emit(event_name, payload)
+    rescue StandardError
+      nil
+    end
+    private_class_method :emit
+
+    def self.monotonic
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+    private_class_method :monotonic
   end
 end

data/lib/standard_health/check.rb

@@ -43,7 +43,12 @@ module StandardHealth
       latency_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000).round
       { status: :ok, latency_ms: latency_ms }
     rescue StandardError => e
-      { status: :fail, error: e.message }
+      # `error_class` matters as much as the message. All three built-in
+      # checks route through here, so without it every real driver failure
+      # reaches the aggregator with no class — and the redacted response then
+      # falls back to a generic "StandardError", which is precisely the
+      # useless label redaction exists to replace with something groupable.
+      { status: :fail, error: e.message, error_class: e.class.name }
     end
   end
 end