Files
clean-architecture-backend-…/docs/observability/log-fields.md
T
DongHyeonka e243eb582b docs(observability): 구조화 로그 칸 사전을 한국어로 옮긴다
문제: `docs/observability/log-fields.md`가 영어였고, `startup.phase` 예시에 없는 값
`adapter-check`가 있었다.

고친 것: 번역했다. `startup.phase` 값을 `StartupPhase`의 넷(`env-validation`, `migration`,
`profile-check`, `adapter-enablement`)으로 맞췄다. 칸 이름은 코드에서 찾아 그대로다.
예외 목록에서 이 파일의 language 줄을 지웠다.

검증: 최종 트리 기준(첫 커밋 본문 참고).
2026-11-07 17:56:34 +09:00

64 lines
3.5 KiB
Markdown

# 구조화 로그 칸 사전
이 파일은 application·bootstrap 런타임 코드가 내는 구조화 칸 이름의 정본이다. 새 칸은 새 검색·필터 기준이 되기 전에 여기에
먼저 더한다.
메시지 문장은 사람을 위한 것이다. 이 칸들이 기계가 조회하는 안정된 표면이다.
## 기동과 오류 분류
| 칸 | 뜻 | 기대하는 cardinality |
|---|---|---|
| `startup.phase` | 기동 단계. `env-validation`, `migration`, `profile-check`, `adapter-enablement` | 상한 있음 |
| `error.code` | 안정된 오류 코드 registry 값 | 상한 있음 |
| `error.category` | 안정된 오류 분류 | 상한 있음 |
| `error.root_cause.class` | 기동 실패 진단용 근본 예외 클래스 | 코드베이스·의존성이 상한 |
| `error.root_cause.message` | 근본 예외 메시지 | 상한 없음. 진단에만 쓰고 메트릭·태그 재료가 아니다 |
기동 실패는 `StartupFailures`를 거친다. 호출자는 기동 오류 분류를 스스로 만들지 않는다.
## 런타임 경고와 재시도 분류
| 칸 | 뜻 | 기대하는 cardinality |
|---|---|---|
| `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 값 | 될 수 있으면 상한 있음 |
재시도 처리 방식이 `error.code`를 뜻하지는 않는다. 오류 코드는 그 실패를 오류 registry가 실제로 분류할 때만 더한다.
## 파일 서버 정리
| 칸 | 뜻 |
|---|---|
| `cleanup.deleted` | 상한 있는 정리 실행 한 번에 지운 객체 |
| `cleanup.skipped_active_lease` | 살아 있는 upload lease가 아직 가져서 건너뛴 항목 |
| `cleanup.skipped_state_changed` | 대기열에 넣은 뒤 상태가 바뀌어 건너뛴 항목 |
| `cleanup.failed` | 그 묶음에서 실패한 정리 항목 |
| `cleanup.reclaimed_bytes` | 그 묶음에서 되찾은 바이트 |
이것들은 숫자 이벤트 칸이다. 신원 칸이 아니다.
## background executor 거부
| 칸 | 뜻 |
|---|---|
| `executor_name` | 상한 있는 executor 식별자 |
| `policy` | 거부 정책. 지금은 `AbortPolicy` |
| `queue_size` | 거부할 때 본 큐 크기 |
executor 거부는 `error.code=JOB_EXECUTOR_REJECTED`와 그 `error.category`도 싣는다.
## cardinality와 민감한 식별자
한 장애에서 쓸모 있었다는 이유만으로 아무 식별자나 구조화 칸으로 올리지 않는다. 분산 락 키, 객체 키, 원본 사용자 식별자,
요청 payload, secret 값이 그 예다.
분산 락 lease 만료 경고는 락 키를 사람이 읽는 메시지 문장에만 두고 `lock.key`를 내지 않는다. 일부러다. 앞으로 운영 요구가
검색할 수 있는 락 신원을 필요로 하면, 원본 키를 더하지 말고 먼저 상한 있거나 가명화한 계약을 정한다.