Files
clean-architecture-backend-…/docs/observability/log-fields.md
T

3.4 KiB

Structured log field dictionary

This file is the naming SSOT for structured fields emitted by application/bootstrap runtime code. A new field should be added here before it becomes a new search/filter dimension.

The message text is for humans. These fields are the stable machine-query surface.

Startup and error classification

Field Meaning Cardinality expectation
startup.phase Startup phase such as env-validation, migration or adapter-check bounded
error.code Stable error-code registry value bounded
error.category Stable error category bounded
error.root_cause.class Root exception class for startup failure diagnosis bounded by codebase/dependencies
error.root_cause.message Root exception message unbounded; diagnosis only, not metric/tag material

Startup failures go through StartupFailures; callers do not construct their own startup error classification.

Runtime warning and retry classification

Field Meaning Cardinality expectation
warning.kind Stable warning shape, for example meter-unavailable, setting-fallback, scheduled-task-failed, lease-expired-before-close bounded
capability Capability that emitted the runtime event, for example fileserver, outbox, distributed-lock bounded
operation Bounded operation name such as cleanup or relay bounded
retry.disposition What the runtime will do after the event, for example next-run or next-tick bounded
meter Meter name or bounded meter operation that could not be updated bounded by metrics registry
env.key Configuration key involved in a fallback bounded by env registry
setting.rejected Rejected setting value rendered for diagnosis potentially unbounded; never metric/tag material
setting.applied Fallback value actually applied bounded where possible

A retry disposition does not imply an error.code. Add an error code only when the failure is actually classified by the error registry.

Fileserver cleanup

Field Meaning
cleanup.deleted Objects deleted in one bounded cleanup run
cleanup.skipped_active_lease Items skipped because an active upload lease still owns them
cleanup.skipped_state_changed Items skipped because state changed after queueing
cleanup.failed Cleanup items that failed in the batch
cleanup.reclaimed_bytes Bytes reclaimed in the batch

These are numeric event fields. They are not identity fields.

Background executor rejection

Field Meaning
executor_name Bounded executor identifier
policy Rejection policy, currently AbortPolicy
queue_size Queue size observed at rejection

Executor rejection also carries error.code=JOB_EXECUTOR_REJECTED and its error.category.

Cardinality and sensitive identifiers

Do not promote arbitrary identifiers to structured fields merely because they are useful in one incident. Examples include distributed-lock keys, object keys, raw user identifiers, request payloads and secret values.

The distributed-lock lease-expiry warning intentionally keeps the lock key only in human-readable message text and does not emit lock.key. If a future operational requirement needs a searchable lock identity, define a bounded/pseudonymized contract first instead of adding the raw key.