Health and observability
Platform · Health and observability
Platform concern — Give operators enough signal to distinguish a healthy process from a useful service.Liveness, readiness, structured logs, metrics, traces, and alertable dependency state.
Key concepts
Liveness
Process state
Readiness
Dependency state
Saturation
Capacity state
Operating model
Decisions to make before production
Boundary and failure behavior
Without health semantics, an overloaded or disconnected service can look alive while causing user-visible failure.Questions for review
Implementation notes
Decision lens
Built-in contracts
createMetricsRegistry provides a small provider-neutral counter and histogram surface for tests and local operation. TraceAdapter and withSpan provide a safe integration boundary for OpenTelemetry or another tracing provider without bundling a vendor SDK into the framework.
Use withRetry only for operations that are safe to retry, and combine it with createCircuitBreaker for dependencies that remain unavailable. Configure explicit upstream timeouts with fetchWithPolicy; do not allow user-controlled upstream URLs without assertSafeUrl and an allowlist.
Related topics
- server-stack · Build runbooks — Read the focused guide for this boundary.
- gauge-high · Measure saturation — Read the focused guide for this boundary.
- stream · Observe streams — Read the focused guide for this boundary.