Logging Wide Events

Build operational logs around one wide event per unit of work: an authoritative structured record, enriched during execution and emitted when that unit completes. Add other events only when they represent independently meaningful occurrences. Logs complement traces and metrics; ordinary operational logs are not a durable audit system.

Vocabulary

Unit of work: one operation whose outcome matters: an HTTP request, queue message, scheduled job, CLI invocation, batch operation, workflow step, or streaming session.

Wide event: the unit's canonical completion record. It carries enough safe, bounded context to query the unit by outcome, timing, deployment, correlation identifiers, and relevant domain dimensions.

Owner: the boundary responsible for the unit's lifecycle. The owner initializes, enriches, and emits its wide event. Inner layers return or annotate errors instead of logging the same failure again.

Independent event: a separately queryable occurrence with meaning beyond narrating the unit's implementation steps: a security decision, externally visible state transition, retry attempt operators act on, progress checkpoint, circuit-breaker transition, or process lifecycle event.

Process

1. Establish the local contract

Before changing logs, inspect the repository's: