docs(observability): 구조화 로그 칸 사전을 한국어로 옮긴다
문제: `docs/observability/log-fields.md`가 영어였고, `startup.phase` 예시에 없는 값 `adapter-check`가 있었다. 고친 것: 번역했다. `startup.phase` 값을 `StartupPhase`의 넷(`env-validation`, `migration`, `profile-check`, `adapter-enablement`)으로 맞췄다. 칸 이름은 코드에서 찾아 그대로다. 예외 목록에서 이 파일의 language 줄을 지웠다. 검증: 최종 트리 기준(첫 커밋 본문 참고).
This commit is contained in:
@@ -1,67 +1,63 @@
|
||||
# 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.
|
||||
이 파일은 application·bootstrap 런타임 코드가 내는 구조화 칸 이름의 정본이다. 새 칸은 새 검색·필터 기준이 되기 전에 여기에
|
||||
먼저 더한다.
|
||||
|
||||
The message text is for humans. These fields are the stable machine-query surface.
|
||||
메시지 문장은 사람을 위한 것이다. 이 칸들이 기계가 조회하는 안정된 표면이다.
|
||||
|
||||
## Startup and error classification
|
||||
## 기동과 오류 분류
|
||||
|
||||
| Field | Meaning | Cardinality expectation |
|
||||
| 칸 | 뜻 | 기대하는 cardinality |
|
||||
|---|---|---|
|
||||
| `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.phase` | 기동 단계. `env-validation`, `migration`, `profile-check`, `adapter-enablement` | 상한 있음 |
|
||||
| `error.code` | 안정된 오류 코드 registry 값 | 상한 있음 |
|
||||
| `error.category` | 안정된 오류 분류 | 상한 있음 |
|
||||
| `error.root_cause.class` | 기동 실패 진단용 근본 예외 클래스 | 코드베이스·의존성이 상한 |
|
||||
| `error.root_cause.message` | 근본 예외 메시지 | 상한 없음. 진단에만 쓰고 메트릭·태그 재료가 아니다 |
|
||||
|
||||
Startup failures go through `StartupFailures`; callers do not construct their own startup error
|
||||
classification.
|
||||
기동 실패는 `StartupFailures`를 거친다. 호출자는 기동 오류 분류를 스스로 만들지 않는다.
|
||||
|
||||
## Runtime warning and retry classification
|
||||
## 런타임 경고와 재시도 분류
|
||||
|
||||
| Field | Meaning | Cardinality expectation |
|
||||
| 칸 | 뜻 | 기대하는 cardinality |
|
||||
|---|---|---|
|
||||
| `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 |
|
||||
| `warning.kind` | 안정된 경고 모양. 예: `meter-unavailable`, `setting-fallback`, `scheduled-task-failed`, `lease-expired-before-close` | 상한 있음 |
|
||||
| `capability` | 런타임 이벤트를 낸 capability. 예: `fileserver`, `outbox`, `distributed-lock` | 상한 있음 |
|
||||
| `operation` | `cleanup`이나 `relay` 같은 상한 있는 operation 이름 | 상한 있음 |
|
||||
| `retry.disposition` | 이벤트 뒤 런타임이 할 일. 예: `next-run`, `next-tick` | 상한 있음 |
|
||||
| `meter` | 갱신하지 못한 meter 이름이나 상한 있는 meter 연산 | 메트릭 registry가 상한 |
|
||||
| `env.key` | fallback에 관련된 설정 키 | env registry가 상한 |
|
||||
| `setting.rejected` | 진단용으로 찍은, 거부된 설정 값 | 상한이 없을 수 있다. 메트릭·태그 재료가 절대 아니다 |
|
||||
| `setting.applied` | 실제로 적용한 fallback 값 | 될 수 있으면 상한 있음 |
|
||||
|
||||
A retry disposition does not imply an `error.code`. Add an error code only when the failure is
|
||||
actually classified by the error registry.
|
||||
재시도 처리 방식이 `error.code`를 뜻하지는 않는다. 오류 코드는 그 실패를 오류 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 |
|
||||
| `cleanup.deleted` | 상한 있는 정리 실행 한 번에 지운 객체 |
|
||||
| `cleanup.skipped_active_lease` | 살아 있는 upload lease가 아직 가져서 건너뛴 항목 |
|
||||
| `cleanup.skipped_state_changed` | 대기열에 넣은 뒤 상태가 바뀌어 건너뛴 항목 |
|
||||
| `cleanup.failed` | 그 묶음에서 실패한 정리 항목 |
|
||||
| `cleanup.reclaimed_bytes` | 그 묶음에서 되찾은 바이트 |
|
||||
|
||||
These are numeric event fields. They are not identity fields.
|
||||
이것들은 숫자 이벤트 칸이다. 신원 칸이 아니다.
|
||||
|
||||
## Background executor rejection
|
||||
## background executor 거부
|
||||
|
||||
| Field | Meaning |
|
||||
| 칸 | 뜻 |
|
||||
|---|---|
|
||||
| `executor_name` | Bounded executor identifier |
|
||||
| `policy` | Rejection policy, currently `AbortPolicy` |
|
||||
| `queue_size` | Queue size observed at rejection |
|
||||
| `executor_name` | 상한 있는 executor 식별자 |
|
||||
| `policy` | 거부 정책. 지금은 `AbortPolicy` |
|
||||
| `queue_size` | 거부할 때 본 큐 크기 |
|
||||
|
||||
Executor rejection also carries `error.code=JOB_EXECUTOR_REJECTED` and its `error.category`.
|
||||
executor 거부는 `error.code=JOB_EXECUTOR_REJECTED`와 그 `error.category`도 싣는다.
|
||||
|
||||
## Cardinality and sensitive identifiers
|
||||
## cardinality와 민감한 식별자
|
||||
|
||||
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.
|
||||
한 장애에서 쓸모 있었다는 이유만으로 아무 식별자나 구조화 칸으로 올리지 않는다. 분산 락 키, 객체 키, 원본 사용자 식별자,
|
||||
요청 payload, secret 값이 그 예다.
|
||||
|
||||
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.
|
||||
분산 락 lease 만료 경고는 락 키를 사람이 읽는 메시지 문장에만 두고 `lock.key`를 내지 않는다. 일부러다. 앞으로 운영 요구가
|
||||
검색할 수 있는 락 신원을 필요로 하면, 원본 키를 더하지 말고 먼저 상한 있거나 가명화한 계약을 정한다.
|
||||
|
||||
@@ -72,7 +72,6 @@ language docs/notification/adr/NOTIF-ADR-001-durable-acceptance.md
|
||||
language docs/notification/adr/NOTIF-ADR-002-event-ledger-projection.md
|
||||
language docs/notification/adr/NOTIF-ADR-003-ambiguous-submission.md
|
||||
language docs/notification/adr/NOTIF-ADR-004-fcm-fid-primary.md
|
||||
language docs/observability/log-fields.md
|
||||
language docs/redis/command-policy.md
|
||||
language docs/redis/operations.md
|
||||
language docs/redis/support-matrix.md
|
||||
|
||||
Reference in New Issue
Block a user