observability-logging
Observability Logging
Use the least production telemetry that answers a defined operational question. If existing signals answer it, add nothing. Use motel-debug for temporary diagnostic probes rather than retaining them as production instrumentation.
Signal And Scope
| Operational need | Signal |
|---|---|
| Duration and causal operation boundary | Span |
| Meaningful occurrence or state transition | Named event or structured log |
| Aggregate rate, count, or distribution | Metric |
A context-rich completion event can answer several known queries; it does not replace useful spans or point-in-time events by default.
Use static names such as checkout.completed or HTTP route templates. Put dynamic values in attributes, with bounded metric dimensions. Resource attributes describe the service and deployment, not individual requests. Use SDK trace/span correlation; an application request ID complements it.
Inbound middleware owns request lifecycle fields; application modules own business outcomes; outbound adapters classify dependency failures. Configure resources, exporters, sampling, and structured logging at the composition root. For Effect programs, use the installed version's span and scoped logging APIs rather than ad hoc global loggers.