# 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.