From e243eb582bc7b67f3048718488d57d81a365c8c1 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sat, 7 Nov 2026 17:56:34 +0900 Subject: [PATCH] =?UTF-8?q?docs(observability):=20=EA=B5=AC=EC=A1=B0?= =?UTF-8?q?=ED=99=94=20=EB=A1=9C=EA=B7=B8=20=EC=B9=B8=20=EC=82=AC=EC=A0=84?= =?UTF-8?q?=EC=9D=84=20=ED=95=9C=EA=B5=AD=EC=96=B4=EB=A1=9C=20=EC=98=AE?= =?UTF-8?q?=EA=B8=B4=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: `docs/observability/log-fields.md`가 영어였고, `startup.phase` 예시에 없는 값 `adapter-check`가 있었다. 고친 것: 번역했다. `startup.phase` 값을 `StartupPhase`의 넷(`env-validation`, `migration`, `profile-check`, `adapter-enablement`)으로 맞췄다. 칸 이름은 코드에서 찾아 그대로다. 예외 목록에서 이 파일의 language 줄을 지웠다. 검증: 최종 트리 기준(첫 커밋 본문 참고). --- docs/observability/log-fields.md | 88 +++++++++++++++---------------- scripts/check-docs-exceptions.txt | 1 - 2 files changed, 42 insertions(+), 47 deletions(-) diff --git a/docs/observability/log-fields.md b/docs/observability/log-fields.md index e7177ec6..c9294a45 100644 --- a/docs/observability/log-fields.md +++ b/docs/observability/log-fields.md @@ -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`를 내지 않는다. 일부러다. 앞으로 운영 요구가 +검색할 수 있는 락 신원을 필요로 하면, 원본 키를 더하지 말고 먼저 상한 있거나 가명화한 계약을 정한다. diff --git a/scripts/check-docs-exceptions.txt b/scripts/check-docs-exceptions.txt index 802ea42b..52bc3ede 100644 --- a/scripts/check-docs-exceptions.txt +++ b/scripts/check-docs-exceptions.txt @@ -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