68 lines
3.4 KiB
Markdown
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.
|