standard_health 0.5.1 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c16f507443b9c907f813a35fb05f7b5cb1517a84cf73b64198b69ee70a41325c
-  data.tar.gz: 4ecfb084c5ca25b231785f8cd1c9069f4f8c5b7554ded6aa600d7723724d83a9
+  metadata.gz: 2c32e1366e2b116f86a8be7780d4717a35b07952402f14e213a2533530c30fe8
+  data.tar.gz: 7c0fe9a0993be6e1ef46adcd95f3ba6c05dc029e7f621557ea314eb0a7062f0e
 SHA512:
-  metadata.gz: 004eb3f2f99b3472340be3f4662e9b0e1ed7b1688db29345f244374384438d07bfa6c914aa219b9f33e4ac891b643a86791ced646c0464911f37eafd807bd152
-  data.tar.gz: 93e407d5e93d2c0c095244290a7aa2c67a7c2c8c67710c931507d18f1a5ca95e211ec9e039b1a66b8615e05473254360dfe64f7154111ab275bc7131ceee5446
+  metadata.gz: ad3e4a667c77a923dfa0ab49aa1de21f86923e7a1e30e7f7204c9ebb4c471f284f61c4f1d0a768155345da3fd46f10b7b77216d6feeeb0c9b799bc7f29bc02f7
+  data.tar.gz: '00853d5d4423f12269bf47f67692bcea3c43bc7da5ac9b64ff39fb9f080364131bea90156cc3fd41387d37421cef886695965c66d28fa024c9e3de418b07458b'

data/CHANGELOG.md

@@ -7,6 +7,71 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.1] - 2026-09-24
+
+### Fixed
+
+- **A check that raises on the aggregate tier is reported to `Rails.error` again.** Before 0.6.0 every host's aggregate controller rescued a raising check and called `Rails.error.report(e, handled: true, ...)`. When the engine took over the tier, the exception was only logged by the Logger notifier, so a buggy aggregate check stopped reaching Sentry (noted in the jumpdrive-web and sidekick-web adoptions). The Aggregator now reports it as handled with context `{ health_check: <name>, tier: "aggregate" }`. Severity follows the readiness Sentry notifier: `:error` for a critical check, `:warning` otherwise. The readiness tier is unchanged. Its failures still reach Sentry through the transition-gated `ready.evaluated` notifier, which keeps a ~6/min probe from flooding the tracker. Checks that return a `:fail` row (every built-in check) are not reported. The report is rescued, so a broken error subscriber cannot 500 the tier.
+
+### Documentation
+
+- The aggregate tier re-runs the `register_check` readiness checks by default (`aggregate_readiness_checks = true`), so a failing critical check (database, Solid Queue) makes `/health` answer **503 `unavailable`**, not only `/ready`.
+- The aggregate body reports `"unavailable"`, never StandardCircuit's `"critical"`. Monitors matching on `"critical"` need updating (as noted in 0.6.0's migration notes).
+- `StandardHealth::DiagnosticsAuthentication` is the request-time gate behind `diagnostics_basic_auth`. The README now notes that a host can include it into its own diagnostics controller, as sidekick-web does. It is not yet a documented, semver-stable extension point.
+
+## [0.6.0] - 2026-09-24
+
+DX release: absorbs the code every consumer app copy-pasted around the engine.
+Everything is **additive and opt-in** — no default changes, no existing route
+returns anything different, and readiness event payloads are byte-identical —
+so this is a pure `bundle update` for consumers on `~> 0.5`. Each feature's
+README section has a "replace your host code with" snippet.
+
+### Added
+
+- `config.diagnostics_basic_auth` — built-in HTTP Basic gate for
+  `/diagnostics/env`. `true` uses `ADMIN_BASIC_AUTH_USERNAME` /
+  `ADMIN_BASIC_AUTH_PASSWORD`; a Hash takes `username:` / `password:`
+  (String or callable, resolved per request), `realm:` (default
+  "Health Diagnostics") and `allow_unconfigured:` (default false). **Fails
+  closed** with a 403 when credentials are blank or their lookup raises;
+  secure_compare over digests on both halves. Replaces each app's
+  `StandardHealthHostController` + `diagnostics_parent_controller` wiring.
+- `Configuration#register_default_checks` — registers `:database`
+  (ActiveRecord, critical), `:solid_queue` (critical), `:solid_cache` and
+  `:audit_retention` (non-critical), skipping any whose backing library isn't
+  loaded or whose name is already registered. Per-check `false` or override
+  Hash (`name:`, `critical:`, `timeout:`, constructor options).
+- `StandardHealth::PROBE_PATHS`, `StandardHealth.probe_path?(path, mount:,
+  up:, aggregate:, extra:)` and `probe_path_pattern` — the orchestrator probe
+  regex (`/up`, `/health`, `/health/alive`, `/health/ready`), built from
+  `StandardHealth::PROBE_ACTIONS`, which the engine's routes are now drawn
+  from. Excludes the doctor tier.
+- `config.metrics_enabled` (drop only the Metrics notifier) and
+  `config.metric_events` (allow-list of event names, validated at boot);
+  `Notifiers::Metrics::EVENTS` / `PER_POLL_EVENTS`. Replaces sidekick-web's
+  `StandardHealthPollMetricSuppression` prepend.
+- `register_check` forwards extra keywords to the check constructor (e.g.
+  `EnvSpecAudit`'s `fail_on:`), validated against its signature at
+  registration. `klass` may also be a String, resolved when the check runs.
+- Opt-in aggregate tier: `config.aggregate_endpoint = true` serves
+  `{ status, checks, circuits, generated_at }` at the engine root (`GET
+  /health`), folding in `StandardCircuit.health_report` when loaded
+  (`aggregate_circuits`), the readiness checks (`aggregate_readiness_checks`)
+  and aggregate-only checks (`register_aggregate_check`). 503 only on
+  `unavailable` (a critical check failure or a `:critical` circuit red);
+  redacted like `/ready`. The route is constrained per request, so with the
+  flag off a bare `/health` still cascades to the host. Emits
+  `standard_health.aggregate.evaluated` (logged; ignored by Sentry and
+  Metrics) and tags aggregate-run check events with `tier: :aggregate`.
+- Specs for `Checks::SolidQueue`, `Checks::SolidCache`, `Notifiers::Metrics`,
+  `Subscribers` and `EventEmitter`.
+
+### Changed
+
+- `Checks::EnvSpecAudit` docs: narrow with `fail_on:` at registration instead
+  of subclassing (subclassing still works).
+
 ## [0.5.1] - 2026-09-24
 
 CI and tooling only — no runtime code changes, so this is a pure

data/README.md

@@ -7,6 +7,7 @@ Mount it once and you get:
 - `GET /health/alive` — liveness probe (always 200 if Rails is up)
 - `GET /health/ready` — readiness probe; runs every registered check and rolls them up into an overall status
 - `GET /health/diagnostics/env` — audits the host app's `ENV` against a declarative spec
+- `GET /health` — *opt-in* aggregate tier: checks plus StandardCircuit state (see [below](#let-the-engine-serve-the-aggregate-tier-060))
 
 Built-in checks cover ActiveRecord, SolidQueue, and SolidCache. Host apps can register additional checks via the configuration block.
 
@@ -45,9 +46,9 @@ This wires up:
 
 ### The aggregate `GET /health` is yours to draw — before the mount
 
-**The engine draws sub-paths only.** There is no `GET /health` in
-`config/routes.rb` here; the aggregate tier is the host's responsibility, and
-the ordering is not optional:
+**Unless you opt into [`aggregate_endpoint`](#let-the-engine-serve-the-aggregate-tier-060)
+(0.6.0), the engine serves no bare `GET /health`.** The aggregate tier is then
+the host's responsibility, and the ordering is not optional:
 
 ```ruby
 get "/health", to: "health_aggregate#show"          # aggregate — FIRST
@@ -79,6 +80,90 @@ Readiness gates **only** on hard infra the app owns. A soft upstream that
 degrades must not pull an instance out of rotation — put those on the aggregate
 tier instead.
 
+### Let the engine serve the aggregate tier (0.6.0)
+
+Instead of drawing the aggregate route yourself, opt in and the engine serves
+it at its root:
+
+```ruby
+StandardHealth.configure do |c|
+  c.aggregate_endpoint = true
+  # c.aggregate_readiness_checks = true    # default: re-run the register_check registry
+  # c.aggregate_circuits = true            # default: fold StandardCircuit.health_report in, when loaded
+  c.register_aggregate_check :solid_cable, StandardHealth::Checks::SolidCable  # aggregate-ONLY
+end
+```
+
+```json
+{ "status": "degraded",
+  "checks":   [{ "name": "database", "critical": true, "status": "ok", "latency_ms": 2 },
+               { "name": "solid_cable", "critical": false, "status": "fail",
+                 "error_class": "PG::ConnectionBad", "error_code": "pg_connection_bad" }],
+  "circuits": [{ "name": "google_oauth", "color": "green", "locked": false, "criticality": "critical" }],
+  "generated_at": "2026-09-24T00:00:00Z" }
+```
+
+| Status | HTTP | When |
+|---|---|---|
+| `unavailable` | 503 | a critical check failed, or a `:critical` circuit is red |
+| `degraded` | 200 | a non-critical check failed or was skipped, or the circuit roll-up is `:degraded` |
+| `ok` | 200 | otherwise |
+
+**The aggregate tier re-runs your readiness checks by default.** With
+`aggregate_readiness_checks` on (the default), every `register_check`
+registration runs here as well as on `/ready`. A failing critical check, such
+as `:database` or `:solid_queue` from `register_default_checks`, therefore turns
+`/health` into a **503 `unavailable`**, not just `/ready`. Point an uptime
+monitor at `/health` and a database outage pages as a 503. If your aggregate
+tier should only report soft signals (sidekick), set
+`aggregate_readiness_checks = false`.
+
+StandardCircuit's own word `critical` is translated to `unavailable`, so both
+tiers speak one vocabulary. The aggregate body never says `"critical"`. `circuits` is omitted when StandardCircuit isn't
+loaded (or `aggregate_circuits = false`); if `health_report` raises (circuit
+store down) the tier degrades and reports `circuits_error: { error_class,
+error_code }` instead of 500ing. Check rows are redacted exactly like `/ready`,
+with the same `detail_token` break-glass. `register_aggregate_check` checks
+run **only** here — never on `/ready` — and default to `critical: false`.
+
+A check that **raises** on this tier, rather than returning a `:fail` row, is
+also reported to `Rails.error` as handled (since 0.6.1), with context
+`{ health_check:, tier: "aggregate" }` and severity `:error` for a critical
+check or `:warning` otherwise. That matches what the pre-0.6 host controllers
+did. `/ready` does not do this: its failures reach Sentry through the
+transition-gated `ready.evaluated` notifier.
+
+With `aggregate_endpoint` off (the default) the engine's root route carries a
+per-request constraint that never matches, so a bare `/health` cascades to your
+own route exactly as before. Once on, the engine answers `/health` regardless
+of where your own route is drawn relative to the mount.
+
+**Migration** — replace your host code with the flag:
+
+- **fundbright / nutripod / jumpdrive** (`get "/health", to: "standard_circuit/health#show"`):
+  set `c.aggregate_endpoint = true`, delete that route (and the
+  `require "standard_circuit/health_controller"` if nothing else uses it —
+  fundbright's `/circuits` alias still does). The body gains `checks[]`, and
+  a red critical circuit reports `"unavailable"` rather than `"critical"`
+  (still 503). Update any dashboard or monitor matching on `"critical"`.
+- **luminality** (`HealthAggregateController` merging `Aggregator` + circuits):
+  set the flag, delete the route and the controller. Same envelope and status
+  words — it is this controller.
+- **sidekick** (`HealthAggregateController` with soft checks only):
+
+  ```ruby
+  c.aggregate_endpoint = true
+  c.aggregate_readiness_checks = false   # sidekick's aggregate never re-ran readiness
+  c.register_aggregate_check :solid_cable, StandardHealth::Checks::SolidCable
+  c.register_aggregate_check :attestation_roots, "AttestationRootsCheck"  # String: resolved per request
+  ```
+
+  then delete the route and the controller. Status words move from
+  `critical` to `unavailable`, as above.
+
+Aggregate evaluations emit `standard_health.aggregate.evaluated`, **not**
+`ready.evaluated` — see [Instrumentation](#instrumentation).
+
 ## Configuration
 
 Create `config/initializers/standard_health.rb` (or let the generator write it):
@@ -105,6 +190,40 @@ StandardHealth.configure do |c|
 end
 ```
 
+### `register_default_checks` (0.6.0)
+
+Every consumer registers the same set by hand. One call does it:
+
+```ruby
+# replaces:
+#   c.register_check :database,        StandardHealth::Checks::ActiveRecord, critical: true
+#   c.register_check :solid_queue,     StandardHealth::Checks::SolidQueue,   critical: true
+#   c.register_check :solid_cache,     StandardHealth::Checks::SolidCache,   critical: false
+#   c.register_check :audit_retention, StandardAudit::Checks::Retention,     critical: false
+c.register_default_checks
+```
+
+| Key | Registered as | Class | `critical` | Skipped unless |
+|---|---|---|---|---|
+| `database` | `:database` | `Checks::ActiveRecord` | `true` | `ActiveRecord::Base` is loaded |
+| `solid_queue` | `:solid_queue` | `Checks::SolidQueue` | `true` | `SolidQueue` is loaded |
+| `solid_cache` | `:solid_cache` | `Checks::SolidCache` | `false` | `SolidCache` is loaded |
+| `audit_retention` | `:audit_retention` | `StandardAudit::Checks::Retention` | `false` | `standard_audit` is loaded |
+
+A check whose backing library isn't loaded is skipped rather than registered
+to fail forever. A name that's already registered is skipped too, so it's safe
+to mix with hand-registered checks (in either order) and to call twice. Each
+key takes `true` (defaults), `false` (skip), or a Hash of overrides —
+`name:`, `critical:`, `timeout:`, plus any [constructor options](#custom-checks):
+
+```ruby
+c.register_default_checks solid_cache: false,                 # jumpdrive: has SolidCache, doesn't check it
+                          solid_queue: { timeout: 2 }
+```
+
+Returns the names it registered. Check order in the response follows
+registration order.
+
 ## EnvSpec
 
 The DSL has three declarations:
@@ -350,6 +469,32 @@ end
 
 `with_timing` captures `latency_ms` on success and converts any `StandardError` into `{ status: :fail, error: <message> }`.
 
+**Per-registration options (0.6.0).** Keywords other than `critical:` and
+`timeout:` are forwarded to the check's constructor, and validated against its
+signature at registration — a typo fails at boot, not on every probe:
+
+```ruby
+class QueueDepthCheck < StandardHealth::Check
+  def initialize(name:, critical: false, max_depth: 1_000)
+    super(name: name, critical: critical)
+    @max_depth = max_depth
+  end
+  # ...
+end
+
+c.register_check :queue_depth, QueueDepthCheck, max_depth: 5_000
+```
+
+**String class names.** `klass` may be a String, resolved each time the check
+runs. That lets an initializer register an autoloaded app constant (which isn't
+resolvable yet at initializer time) without a `to_prepare` block, and picks up
+class reloads in development. An unresolvable name reports a failing row
+(`error_class: "NameError"`) rather than raising.
+
+```ruby
+c.register_check :runner, "RunnerHealthCheck"
+```
+
 **A check must never raise.** `Aggregator` rescues `StandardError` per check, so a buggy check degrades to `:fail` rather than 500ing the endpoint — but don't rely on that as the only line of defence. Route fallible work through `with_timing`.
 
 ## Opt-in checks
@@ -407,15 +552,12 @@ still serving traffic correctly, and de-rotating it converts a warning into an
 outage. Registering it `critical: true` asserts "this app must not serve at all
 with a bad env" — a real but rare posture. Know which you want.
 
-The aggregator instantiates checks with `name:`/`critical:` only, so to narrow
-what counts as a failure, subclass:
+To narrow what counts as a failure, pass `fail_on:` at registration (0.6.0+
+forwards it to the constructor — no subclass needed):
 
 ```ruby
-class ForbiddenTogglesOnly < StandardHealth::Checks::EnvSpecAudit
-  def initialize(name: :forbidden_toggles, critical: false)
-    super(name: name, critical: critical, fail_on: %i[forbidden])
-  end
-end
+c.register_check :forbidden_toggles, StandardHealth::Checks::EnvSpecAudit,
+                 fail_on: %i[forbidden]
 ```
 
 Note the failure message is subject to [redaction](#failure-detail-is-redacted)
@@ -427,9 +569,67 @@ Sentry. The row carries a stable `error_class` of
 
 ## Auth
 
-`/alive` and `/ready` are typically left open for orchestrator probes. `/diagnostics/env` enumerates which env vars are missing — that's potentially sensitive, so the host app is responsible for protecting it.
+`/alive` and `/ready` are typically left open for orchestrator probes. `/diagnostics/env` enumerates which env vars are missing — that's potentially sensitive, so it must be protected.
+
+### Built-in basic auth for diagnostics (0.6.0)
+
+The simplest option is to let the engine gate it:
 
-The recommended pattern is to point `parent_controller` at a host app controller that enforces auth:
+```ruby
+StandardHealth.configure do |c|
+  c.diagnostics_basic_auth = true   # ADMIN_BASIC_AUTH_USERNAME / ADMIN_BASIC_AUTH_PASSWORD
+end
+```
+
+or, with your own credential source (Strings or callables, resolved **per
+request**, so rotation needs no restart):
+
+```ruby
+c.diagnostics_basic_auth = {
+  username: -> { Current.config.admin_basic_auth_username },
+  password: -> { Current.config.admin_basic_auth_password },
+  realm: "Health Diagnostics",                                  # default
+  allow_unconfigured: -> { Rails.env.local? }                   # default: false
+}
+```
+
+- Only `/diagnostics/env` is gated; `/alive`, `/ready` and the aggregate tier stay anonymous.
+- **Fails closed.** If either credential resolves blank (or the lookup raises),
+  the endpoint answers **403** `{"error":"diagnostics refused", ...}` rather
+  than serving env state. 403, not 503: DigitalOcean App Platform's edge
+  replaces an app 5xx with its own error page, which reads as "app down". Not
+  401: there are no credentials that could succeed. `allow_unconfigured`
+  (boolean or callable) opts a credential-less environment — typically local
+  dev — into passing through.
+- Both halves are compared with `secure_compare` over SHA-256 digests, so a
+  wrong username still costs a password comparison and differing lengths leak
+  nothing.
+- Off by default; independent of `diagnostics_parent_controller` (if you set
+  both, the parent's callbacks run first).
+- The request-time gate is the `StandardHealth::DiagnosticsAuthentication`
+  concern, which the engine includes into its own `DiagnosticsController`.
+  sidekick-web also includes it into its own `HealthDiagnosticsController`
+  (an `ActionController::API` subclass) so that controller shares the same
+  gate. That works: the concern is a no-op until `diagnostics_basic_auth` is
+  set, and it adds one `before_action`. It is not yet a documented,
+  semver-stable extension point, so pin your minor version if you depend on it.
+
+**Replace your host code with it.** Delete
+`app/controllers/standard_health_host_controller.rb` and the
+`c.diagnostics_parent_controller = "StandardHealthHostController"` line, then:
+
+| App | Was | Set |
+|---|---|---|
+| jumpdrive | fail-closed 403 on unset `ADMIN_BASIC_AUTH_*` | `c.diagnostics_basic_auth = true` |
+| sidekick | 503 when unset in staging/preview/production, open locally | `c.diagnostics_basic_auth = { allow_unconfigured: -> { !%w[staging preview production].include?(ENV["APP_ENVIRONMENT"]) } }` |
+| fundbright, luminality | open when unset (boot-enforced in deployed envs) | `c.diagnostics_basic_auth = { allow_unconfigured: -> { Rails.env.local? } }` |
+| nutripod | `Current.config.admin_basic_auth_*` | `c.diagnostics_basic_auth = { username: -> { Current.config.admin_basic_auth_username }, password: -> { Current.config.admin_basic_auth_password }, allow_unconfigured: -> { Rails.env.local? } }` |
+
+(Sidekick moves from 503 to 403 on a missing gate — see above for why.)
+
+### Bring your own parent controller
+
+The pre-0.6.0 pattern is to point `parent_controller` at a host app controller that enforces auth:
 
 ```ruby
 # app/controllers/internal_health_controller.rb
@@ -490,6 +690,53 @@ Now `/health/alive` and `/health/ready` are unauthenticated (probe-friendly) whi
 
 When `diagnostics_parent_controller` is unset, `DiagnosticsController` falls back to `parent_controller`, matching v0.1.0 behavior exactly.
 
+## Probe paths (0.6.0)
+
+Hosts copy the probe regex into `production.rb` and their Sentry samplers. The
+gem now owns it, built from the same `PROBE_ACTIONS` list its routes are drawn
+from, so it cannot drift:
+
+```ruby
+StandardHealth::PROBE_PATHS
+# => matches /up, /health, /health/alive, /health/ready (optional trailing /)
+#    never /health/diagnostics/env, never /healthy-habits
+StandardHealth.probe_path?(path)                    # predicate, same default
+StandardHealth.probe_path?(path, mount: "/_status") # engine mounted elsewhere
+```
+
+Anchored at both ends. The doctor tier is deliberately excluded — it's authed,
+hit by on-call rather than on a timer, and belongs in logs and APM.
+
+**If you mount the engine anywhere but `/health`, `PROBE_PATHS` is wrong for
+you** — call `probe_path?(path, mount: "/your-prefix")` or build your own with
+`StandardHealth.probe_path_pattern(mount:, up: true, aggregate: true, extra: [])`.
+`aggregate: false` reproduces the old exact set without the bare `/health`;
+`extra:` adds exact paths such as fundbright's `/circuits` alias.
+
+Replace your host code with it:
+
+```ruby
+# config/environments/production.rb
+# was: %r{\A/(up|health/(alive|ready))\z}  (x3 in fundbright/luminality/nutripod)
+config.silence_healthcheck_path = StandardHealth::PROBE_PATHS
+config.x.silence_console_paths  = [StandardHealth::PROBE_PATHS]   # luminality/sidekick
+config.ssl_options = { redirect: { exclude: ->(r) { StandardHealth.probe_path?(r.path) } } }
+config.host_authorization = { exclude: ->(r) { StandardHealth.probe_path?(r.path) } }
+
+# config/initializers/sentry.rb traces_sampler
+# was: Sentry::ProbePaths.probe?(path) (lib/sentry/probe_paths.rb in
+#      fundbright/luminality/sidekick) or SentryTracesSampler#health_or_stream?
+#      in jumpdrive, or the inline start_with? in nutripod
+return 0.0 if StandardHealth.probe_path?(rack_env["PATH_INFO"])
+return 0.0 if StandardHealth.probe_path?(path, extra: ["/circuits"])   # fundbright
+```
+
+Note the difference from the samplers' segment-prefix match: this is an
+**exact** match on the probe routes the engine actually serves, so a future
+`/health/<something>` sub-route is covered by a gem release rather than by a
+prefix. Paths the gem doesn't serve (sidekick's `/api/v1/provisioning/health`)
+go in `extra:`.
+
 ## Status semantics
 
 `/ready` returns:
@@ -537,7 +784,14 @@ The gem emits events on whichever bus is live — `Rails.event` on Rails 8.1+,
 |---|---|
 | `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[]` |
+| `standard_health.ready.evaluated` | `status`, `duration_ms`, `failed[]`, `failures[]` |
+| `standard_health.aggregate.evaluated` | `status`, `duration_ms`, `failed[]`, `failures[]`, `circuits_status`, `red_circuits[]` (0.6.0, only with `aggregate_endpoint`) |
+
+Checks run by the aggregate tier also emit `check.completed` / `check.timed_out`,
+carrying `tier: :aggregate`; readiness payloads carry no `tier` key, exactly as
+before 0.6.0. The aggregate evaluation deliberately gets its **own** event:
+the Sentry notifier keeps per-process transition state on `ready.evaluated`,
+and an aggregate that includes soft checks would make it flap.
 
 Three subscribers are registered automatically. Their noise profiles differ on
 purpose, because health events are **polls**, not state transitions — a 10s
@@ -551,7 +805,38 @@ probe period means ~6 evaluations/minute/instance:
   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.
+  distributions are what make `latency_ms` chartable. Aggregate-tier check
+  counts carry a `tier` attribute.
+
+The Logger also reports `aggregate.evaluated` (silent on ok); Sentry and
+Metrics ignore it.
+
+### Narrowing metrics (0.6.0)
+
+The per-poll events are the metric volume (~2 evaluations × N checks per probe
+interval per instance). To keep the rare, actionable timeout metric and drop
+the per-poll firehose:
+
+```ruby
+c.metric_events = %w[standard_health.check.timed_out]
+# or equivalently:
+c.metric_events = StandardHealth::Notifiers::Metrics::EVENTS -
+                  StandardHealth::Notifiers::Metrics::PER_POLL_EVENTS
+```
+
+or drop the Metrics notifier entirely — unlike `instrumentation_enabled =
+false`, this keeps the Logger and Sentry notifiers:
+
+```ruby
+c.metrics_enabled = false
+```
+
+`metric_events` is an allow-list (nil, the default, records everything) and
+unknown names raise at boot. **Replace your host code with it:** sidekick's
+`config/initializers/standard_health_metrics.rb` (the
+`StandardHealthPollMetricSuppression` prepend) becomes the first snippet above;
+its spec's "is patched with the suppression module" example goes, the
+behavioural examples stay.
 
 ```ruby
 StandardHealth.configure do |c|
@@ -559,6 +844,8 @@ StandardHealth.configure do |c|
   c.logger        = Rails.logger      # default: Rails.logger
   c.sentry_enabled = true             # default
   c.metric_prefix  = "health"         # default
+  c.metrics_enabled = true            # default (0.6.0)
+  c.metric_events   = nil             # default: all (0.6.0)
 
   c.add_notifier(MyNotifier.new)      # must respond to call(event_name, payload)
 end

data/app/controllers/concerns/standard_health/diagnostics_authentication.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module StandardHealth
+  # Request-time half of `config.diagnostics_basic_auth`. Included into
+  # `DiagnosticsController` only — never `HealthController` — so /alive and
+  # /ready stay anonymous for orchestrator probes.
+  #
+  # A NO-OP when `diagnostics_basic_auth` is unset, so hosts that gate
+  # diagnostics through `diagnostics_parent_controller` see no change. Both
+  # can be used together; the parent's callbacks run first.
+  module DiagnosticsAuthentication
+    extend ActiveSupport::Concern
+
+    included do
+      # ActionController::API does not include this; ActionController::Base
+      # does, and including it twice is harmless.
+      include ActionController::HttpAuthentication::Basic::ControllerMethods
+
+      before_action :standard_health_diagnostics_basic_auth!
+    end
+
+    private
+
+    def standard_health_diagnostics_basic_auth!
+      settings = StandardHealth.config.diagnostics_basic_auth
+      return unless settings
+
+      user = settings.expected_username
+      pass = settings.expected_password
+
+      if user.empty? || pass.empty?
+        return if settings.allow_unconfigured?
+
+        return refuse_unconfigured_diagnostics!
+      end
+
+      authenticate_or_request_with_http_basic(settings.realm) do |given_user, given_pass|
+        settings.authenticate(given_user, given_pass)
+      end
+    rescue StandardError => e
+      # A credential lookup that raises (missing credentials key, Current not
+      # set, ...) must fail CLOSED — never fall through to the audit, and
+      # never 500 (see below). The class name is logged, not rendered.
+      Rails.logger&.warn("[StandardHealth] diagnostics auth lookup failed: #{e.class}")
+      refuse_unconfigured_diagnostics!
+    end
+
+    # 403, NOT 5xx — a platform constraint, not a preference. DigitalOcean
+    # App Platform's edge replaces an app 5xx with its own generic error page,
+    # so a 503 here is indistinguishable from the app being down and the
+    # explanation is thrown away. 403 passes through and is honest: access is
+    # refused. Not 401, because a challenge invites retrying with credentials
+    # that cannot work — none are configured to match.
+    def refuse_unconfigured_diagnostics!
+      render json: {
+        error: "diagnostics refused",
+        detail: "diagnostics basic-auth credentials are not configured, so this endpoint " \
+                "cannot be authenticated. Refusing rather than exposing env state."
+      }, status: :forbidden
+    end
+  end
+end

data/app/controllers/standard_health/diagnostics_controller.rb

@@ -11,7 +11,12 @@ module StandardHealth
   # `before_action :auth, only: :env` on a dedicated diagnostics parent —
   # without that callback leaking onto `HealthController` and tripping
   # Rails 7.1's `raise_on_missing_callback_actions`.
+  #
+  # Or, since 0.6.0, set `config.diagnostics_basic_auth` and let the engine
+  # gate it (fail-closed) — see `DiagnosticsAuthentication`.
   class DiagnosticsController < DiagnosticsApplicationController
+    include DiagnosticsAuthentication
+
     # Audits the configured EnvSpec against the current process ENV and
     # returns the result as JSON. When no EnvSpec is configured the
     # endpoint returns an empty audit rather than a 404 so callers don't

data/app/controllers/standard_health/health_controller.rb

@@ -25,6 +25,18 @@ module StandardHealth
              status: http_status
     end
 
+    # Aggregate tier (0.6.0, opt-in via `config.aggregate_endpoint`; the route
+    # does not match otherwise). Checks + StandardCircuit state in one body —
+    # see StandardHealth::AggregateReport. 503 only on :unavailable, i.e. a
+    # critical check failure or a :critical circuit RED. Redacted exactly like
+    # /ready, with the same break-glass.
+    def aggregate
+      report = StandardHealth::AggregateReport.call
+      http_status = report[:status] == :unavailable ? :service_unavailable : :ok
+      render json: StandardHealth::Redactor.call(report, expose: expose_errors?),
+             status: http_status
+    end
+
     private
 
     # Detail is exposed when the host opted in globally, or when the caller

data/config/routes.rb

@@ -1,8 +1,19 @@
 # frozen_string_literal: true
 
 StandardHealth::Engine.routes.draw do
-  get "/alive", to: "health#alive"
-  get "/ready", to: "health#ready"
+  # Probe routes are drawn from PROBE_ACTIONS (alive, ready) so
+  # StandardHealth::PROBE_PATHS / probe_path? cannot drift from what the
+  # engine serves.
+  StandardHealth::PROBE_ACTIONS.each do |action|
+    get "/#{action}", to: "health##{action}"
+  end
+
+  # Aggregate tier at the engine root (GET /health for the usual mount).
+  # OPT-IN: the constraint is evaluated per request, so with
+  # `aggregate_endpoint` off this route never matches and a bare /health
+  # cascades to the host's own route exactly as it did before 0.6.0.
+  get "/", to: "health#aggregate", as: :aggregate,
+           constraints: ->(_request) { StandardHealth.config.aggregate_endpoint }
 
   namespace :diagnostics do
     get :env

data/lib/generators/standard_health/install/templates/initializer.rb.erb

@@ -15,6 +15,10 @@
 # tier silently has no aggregate tier at all — no boot error, and no failing
 # route spec unless one exists. Add a route spec for `GET /health`.
 #
+# Alternatively (0.6.0+) let the engine serve the aggregate tier itself —
+# checks plus StandardCircuit state — and draw no route at all:
+#   config.aggregate_endpoint = true
+#
 # Tiers: /alive = liveness (process up) · /ready = readiness (rotation gate)
 # /health = aggregate (dashboards) · /diagnostics/env = authed doctor.
 # ────────────────────────────────────────────────────────────────────────────
@@ -28,6 +32,10 @@ StandardHealth.configure do |config|
   # it. Setting a diagnostics-only parent lets you put auth on the doctor tier
   # without the callback leaking onto /alive and /ready.
   # config.diagnostics_parent_controller = "DiagnosticsBaseController"
+  #
+  # Or let the engine gate it with HTTP Basic (fails CLOSED — 403 — when the
+  # credentials are unset). `true` reads ADMIN_BASIC_AUTH_USERNAME/_PASSWORD.
+  # config.diagnostics_basic_auth = true
 
   # ── Checks ───────────────────────────────────────────────────────────────
   #
@@ -35,6 +43,11 @@ StandardHealth.configure do |config|
   # pulls the instance out of rotation, so `critical: true` belongs on the
   # database and little else. Soft upstreams degrade; they never gate rotation.
   config.register_check :database, StandardHealth::Checks::ActiveRecord, critical: true
+  #
+  # Or register the common set in one call — :database and :solid_queue
+  # (critical), :solid_cache and :audit_retention (non-critical), each skipped
+  # when its library isn't loaded:
+  # config.register_default_checks
   # config.register_check :cache, StandardHealth::Checks::SolidCache
   # config.register_check :queue, StandardHealth::Checks::SolidQueue