문제: `docs/observability/log-fields.md`가 영어였고, `startup.phase` 예시에 없는 값 `adapter-check`가 있었다. 고친 것: 번역했다. `startup.phase` 값을 `StartupPhase`의 넷(`env-validation`, `migration`, `profile-check`, `adapter-enablement`)으로 맞췄다. 칸 이름은 코드에서 찾아 그대로다. 예외 목록에서 이 파일의 language 줄을 지웠다. 검증: 최종 트리 기준(첫 커밋 본문 참고).
3.5 KiB
3.5 KiB
구조화 로그 칸 사전
이 파일은 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를 내지 않는다. 일부러다. 앞으로 운영 요구가
검색할 수 있는 락 신원을 필요로 하면, 원본 키를 더하지 말고 먼저 상한 있거나 가명화한 계약을 정한다.