Files
clean-architecture-backend-…/docs/observability/log-fields.md
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

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를 내지 않는다. 일부러다. 앞으로 운영 요구가 검색할 수 있는 락 신원을 필요로 하면, 원본 키를 더하지 말고 먼저 상한 있거나 가명화한 계약을 정한다.