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

68 lines
3.4 KiB
Markdown

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