Logs become operational evidence when fields have stable semantics across success, rejection, timeout, and failure.
Structured Boundary Log
A boundary log is durable causal evidence, not a prose debugging message.
logger.info({
event: 'payment_authorized',
trace_id: traceId,
request_id: requestId,
tenant_id: tenantId,
payment_id: paymentId,
provider: 'stripe',
duration_ms: performance.now() - started,
outcome: 'success',
})Invariant: Every emitted boundary event has stable causal identity, outcome, and duration fields.
Use when: An operation crosses a service boundary and needs searchable causal evidence.
Why this boundary matters
Without stable identity and outcome fields, partial failures cannot be joined across services or distinguished from expected business rejection.
Failure policy
| Boundary | Action |
|---|---|
| Successful boundary | Record identity, outcome, and duration once |
| Expected business rejection | Use a distinct outcome, not an exception-shaped error |
| Unexpected failure | Include causal error data without secrets |
| Sensitive field | Redact before the logger receives it |
| High-cardinality identity | Keep it searchable in logs, not as an unbounded metric label |
Trade-offs
Structured logs improve correlation but increase storage cost and privacy exposure. Logging every layer duplicates evidence; logging arbitrary payloads destroys schema stability and can leak credentials or personal data.
Decision rule: Emit one stable event at an owned system boundary when it materially helps detection, diagnosis, or audit.
Further reference
Browse all engineering snippets · Read about observability contracts