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.