Files
clean-architecture-backend-…/docs/design/2026-11-06-error-code-log-level-design.md
T
DongHyeonka 74108497d4 docs(records): 기록과 ADR 맨 위에 한국어 머리 블록을 단다
문제: 설계서·계획서·납품 패키지·증거·학습 문서와 ADR이 기록이라는 표시
없이 지금 문서처럼 읽힌다. 상태 칸이 설계서 72개 중 40개, 계획서는
거의 없고, 있어도 Approved·확정·Accepted.처럼 값이 제각각이며 영어다.

고른 방법: docs/design, docs/history, docs/adr, docs/notification/adr의
.md 246개 맨 위에 같은 모양의 머리 블록을 단다. 칸은 상태·작성일·
요약(한국어 한 문장)·현재 정본, 대체됐으면 대체됨이다. 블록은 표시 줄
두 개로 감싸서 빼면 원문 바이트가 그대로 돌아온다(246개 모두 대조함).
- 종류는 폴더가 정하고 둘째 줄에 적는다(plans/evidence는 증거).
- 상태는 원래 상태 줄을 고정 어휘로 바꾼 값이다. 상태 줄이 없는
  설계서와 체크 상자가 다 표시되지 않은 계획서는 「확인 안 함」.
  capability-status.md 제거 표로 지운 것이 확인된 설계서 다섯은 「폐기」,
  2026-07-20 하네스 설계·계획과 production capability platform 설계는
  「대체됨」이다.
- 현재 정본은 구조 정리로 옮겨질 수 있는 src/messaging·src/grpc 대신
  docs/ 쪽 문서나 옮기지 않는 leaf README를 가리킨다.
docs/README.md에 「문서 수명과 언어」「기록 문서의 머리 블록」「문서와
코드를 같은 변경에서 고친다」를 더하고, 파생 서비스 안내에 머리 블록
충돌 가능성을 적었다.

버린 대안: H1 제목 아래에 블록을 두는 안은 보기에는 낫지만 빼는 규칙이
파일마다 달라져 원문 복원이 기계적이지 않다. 「종류」 칸을 따로 두는
안은 폴더와 같은 정보를 두 번 쓰게 한다.

위험·한계: 「확인 안 함」 설계서 38개, 계획서 51개는 지금 유효한지
아무도 판정하지 않았다. 요약은 제목·목표 줄을 보고 쓴 것이라 본문을
끝까지 읽지 않았다. 납품 패키지 셋의 MANIFEST.sha256는 이제 맞지 않는다
(납품 당시 바이트의 해시이고, 블록을 빼면 다시 맞는다). 리뷰 폴더에는
아직 머리 블록을 달지 않았다.

검증: 머리 블록을 뺀 내용과 HEAD 원본 246개 일치, check-work-docs.py
rc=0, --links docs·README.md·CLAUDE.md·AGENTS.md 깨진 링크 0.
2026-11-07 12:23:32 +09:00

255 lines
23 KiB
Markdown

<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택
- 작성일: 2026-11-06
- 요약: 오류 코드 레지스트리에 log_level 칸을 두지 않고 실패 종류·경로가 레벨을 정하게 한 설계 메모다.
- 현재 정본: `docs/registries/error-codes.yaml`
<!-- 머리 블록 끝 -->
# `error-codes.yaml`의 `log_level` 칸 — 설계 메모
- 상태: **확정** (2026-11-06, 소유자 답 "권하는 안대로"). 결정은 10절이다. 아래 1~9절은 결정 전에 쓴 그대로 둔다.
- 기준 커밋: `06f520e6` (`refactor/maturity-review-2026-11`)
- 크기: 중간(brief). 이 메모가 고르는 안을 실제로 적용하는 일은 **큼**이다. 오류 코드 레지스트리는 공개 계약이라
파일 하나여도 큼이다(`docs/work/README.md` 2절). 그래서 이 메모는 대안 비교까지 하고 멈춘다. 코드와 yaml은
바꾸지 않았다.
- 요청(총괄 brief 원문): "`docs/registries/error-codes.yaml`의 `log_level` 칸은 읽는 코드가 없고, 값이 코드와 다른
곳이 있다(`IDEMPOTENCY_UNAVAILABLE`: 문서 WARN, 코드 ERROR). 이 칸을 어떻게 할지 설계 메모를 쓰고 소유자 결정을
묻는다."
- 처음 나온 곳: 재리뷰 round6이 "규범인지 판단하지 않았다"로 남긴 항목
(`docs/reviews/2026-11-03-rereview/round6/02-idempotency-outbound.md:217`).
## 1. 결론
권하는 안은 **A — 칸을 지운다**이다. 로그 레벨은 오류 코드 하나가 아니라 실패의 종류와 경로가 정하고, 그 규칙은
이미 코드 한 곳(`ServerFailureLog`)에 있다. 레지스트리 머리말은 그 규칙을 가리키기만 한다. 칸 값을 증상으로 적은
런북 2곳은 실제 로그 줄로 고친다.
칸과 별개로 동작 질문이 둘 남는다. 보안 필터가 5xx 두 코드를 WARN으로 남기는 것(결정 2), 문서가 ERROR로 의도한 401
세 코드(결정 3)다.
## 2. 지금 어떻게 되어 있나
### 2.1 칸을 읽는 곳
- 스키마: `docs/registries/error-codes.yaml:18` `log_level: ERROR | WARN | INFO`. 60행 모두 값이 있다(ERROR 25,
WARN 26, INFO 9).
- 코드와 테스트: 읽는 곳이 없다. `src`·`scripts`의 java·py·gradle·sh에서 `log_level`·`logLevel` 검색 결과 0건이다.
- 테스트가 읽는 칸: `category`·`http_status`·`retryable`·`client_safe_message`·`runbook_link`·`owner_branch`·
`compatibility_impact`·`required_test`다(테스트 코드의 `get("<칸>")` 집계). `log_level`과 `owner_layer`만
아무도 읽지 않는다.
- 스키마 검사(`ContractRegistrySchemaGovernanceTest`, `RegistryGovernanceCatalog.java:217, 247-253`)는 필수 칸만 본다.
모르는 칸을 막지 않는다.
- 값의 이력: `git log -S log_level`의 네 커밋(`821fe00c`, `9da00eb7`, `c4a066df`, `bbe944bd`)은 행을 넣거나 뺐다.
있던 행의 레벨 값이 바뀐 적은 없다(커밋 사이 코드별 값 비교 결과 차이 0).
- 런북: 두 곳이 칸 값을 증상으로 적는다.
- `docs/runbooks/auth-token-invalid-signature.md:16`: "`log_level=ERROR` — may indicate forged tokens"
- `docs/runbooks/authz-tenant-mismatch.md:16`: "`log_level=ERROR`"
- 경보: `docs/registries/metrics.yaml`의 경보 기준은 모두 지표다(error_rate, p99 등). 로그 레벨을 세는 경보는 없다
(`logback_events`·`level=error` 검색 0건).
- 파생 서비스 `tech-log-backend`(`a000f87`): 자기 `error-codes.yaml` 96행에 `log_level`을 채운다. 설계서가 새 행마다
이 칸을 채우라고 적는다(`docs/superpowers/specs/2026-08-18-techlog-studio-backend-design.md:382`). 그쪽에도 이
칸을 읽는 코드는 없다(`git grep log_level`, java·gradle·yaml·sh 0건).
### 2.2 코드가 로그 레벨을 정하는 방식
레벨은 오류 코드가 아니라 **실패의 종류와 경로**가 정한다.
```text
요청 실패 ─┬─ 보안 필터(401·403·JWKS·인증 설정) ─ AuthErrorResponseWriter ─────────── 늘 WARN
├─ IllegalArgumentException ─────────── ServerFailureLog.refusedArgument ─── WARN
├─ ApiErrorCarrier ─ ServerFailureLog.of ─┬─ PersistenceFailureException ── ERROR (상태 무관)
│ ├─ DependencyFailureException ── ERROR (상태 무관)
│ ├─ 그 밖의 5xx ───────────────── ERROR
│ └─ 4xx ───────────────────────── 남기지 않음
├─ Spring MVC 예외 ─ handleExceptionInternal ── 5xx면 ERROR, 4xx면 남기지 않음
└─ 그 밖의 예외 ─ handleUnknown ── INTERNAL_ERROR로 답하고 ERROR
배경 작업 ─ outbox 실패 보고, executor 거절 ── ERROR
```
출처:
- 규칙: `src/shared-contract/src/main/java/dev/caskeleton/shared/error/ServerFailureLog.java:54-79`.
4xx를 남기지 않는 이유는 같은 파일 25행 "A client-side carrier is not logged: it is an answer, not an incident"다.
IAE WARN은 91-96행이다.
- 네 전송이 같은 줄을 쓴다.
- carrier ERROR: web `GlobalExceptionHandler.java:173-176`, gRPC `GrpcExceptionHandlingInterceptor.java:135-136`,
GraphQL `GraphQlWireErrorMapper.java:134-135`, STOMP `StompHandlerFailureLog.java:35-36`
- IAE WARN: web `GlobalExceptionHandler.java:96-97`, gRPC `:139-140`, GraphQL `:137-138`, STOMP `:40-41`
- 보안 필터: `src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/auth/AuthErrorResponseWriter.java:32`
`log.warn("security failure: code={} …")`. 인증 진입점과 접근 거부 처리기가 둘 다 이 writer를 쓴다.
- Spring MVC: `GlobalExceptionHandler.java:397-401`. 그 밖의 예외: 같은 파일 195-203행.
- 배경 작업: `Slf4jOutboxRelayFailureReportAdapter.java`의 `atError()`, `LoggingAbortPolicy.java:35`.
- 이 규칙은 리뷰를 거쳐 정한 설계다. 네 전송이 한 정책을 쓰게 했고(`ServerFailureLog` Javadoc 첫 문단), IAE를 네
전송에서 같은 WARN 한 줄로 남기게 했다(RR6-01-06, `docs/reviews/2026-11-03-rereview/README.md` 17절 r10-01).
그래서 레벨은 오류 코드 하나에 값 하나로 떨어지지 않는다.
- 같은 `BAD_PARAMETER`라도 IAE에서 오면 WARN이다. 타입 변환 실패에서 오면 남기지 않는다
(`GlobalExceptionHandler.java:108-116`).
- 같은 409라도 영속성 실패면 ERROR다. 멱등 in-flight면 남기지 않는다.
### 2.3 60행 대조
방법: 행마다 main 코드에서 그 코드를 내는 곳을 찾았다(`grep -rlw <CODE> src --include='*.java'` 중 `/main/`). 그 경로에
2.2의 규칙을 대어 레벨을 정했다. 코드를 읽은 결과이고, 실행 탐침은 돌리지 않았다(이유는 6절 가정 4).
| 결과 | 행 | 코드 |
| --- | --- | --- |
| 같다 | 14 | WARN: `AUTH_TOKEN_MISSING`, `AUTH_TOKEN_MALFORMED`, `AUTH_TOKEN_EXPIRED`, `AUTH_KID_UNKNOWN`. ERROR: `DB_UNAVAILABLE`, `DB_IDLE_IN_TX_TIMEOUT`, `DB_COMPLETION_UNKNOWN`, `IDEMPOTENCY_COMPLETION_UNKNOWN`, `IDEMPOTENCY_RECOVERY_REQUIRED`, `ADAPTER_DISABLED`, `INTERNAL_ERROR`, `OUTBOX_PUBLISH_FAILED`, `OUTBOX_DEAD_LETTER`, `JOB_EXECUTOR_REJECTED` |
| 문서 ERROR, 코드 WARN | 5 | `AUTH_TOKEN_INVALID_SIGNATURE`, `AUTH_ISSUER_MISMATCH`, `AUTH_AUDIENCE_MISMATCH`(401), `AUTH_JWKS_UNAVAILABLE`(503), `INTERNAL_AUTH_MISCONFIGURATION`(500). 보안 필터가 모두 WARN으로 남긴다 |
| 문서 WARN, 코드 ERROR | 10 | `IDEMPOTENCY_UNAVAILABLE`(503 carrier). 영속성 실패 9개: `DB_SERIALIZATION_FAILURE`, `DB_DEADLOCK`, `DB_NULL_VIOLATION`, `DB_FK_VIOLATION`, `DB_UNIQUE_VIOLATION`, `DB_CHECK_VIOLATION`, `DB_OPTIMISTIC_CONFLICT`, `DB_LOCK_TIMEOUT`(409), `DB_QUERY_CANCELED`(503). JPA 예외는 모두 `PersistenceFailureException`의 하위 타입이다(`JpaPersistenceException.java:22`) |
| 문서는 레벨, 코드는 남기지 않음 | 15 | `IDEMPOTENT_IN_FLIGHT`, `IDEMPOTENT_REQUEST_MISMATCH`, `MAPPING_FAILED`, `VALIDATION_FAILED`, `PRECONDITION_FAILED`, `METHOD_NOT_ALLOWED`, `NOT_ACCEPTABLE`, `PAYLOAD_TOO_LARGE`, `URI_TOO_LONG`, `UNSUPPORTED_MEDIA_TYPE`, `ROUTE_NOT_FOUND`, `RATE_LIMIT_EXCEEDED`, `INVALID_TOKEN`, `FORBIDDEN`, `BATCH_PARTIAL_FAILURE` |
| 경로마다 다름 | 3 | `BAD_PARAMETER`(문서 INFO; IAE면 WARN, 타입 변환이면 없음). `AUTHZ_INSUFFICIENT_PERMISSION`(문서 WARN; 필터면 WARN, controller method security면 `handleForbidden`이라 없음). `UNAUTHENTICATED`(문서 WARN; web은 없음, gRPC는 인증 정책이 예외를 던질 때만 WARN — `GrpcAuthenticationInterceptor.java:55`) |
| 템플릿 main에 내는 곳 없음 | 13 | `AUTH_CLAIM_MAPPING_FAILED`, `AUTHZ_TENANT_MISMATCH`, `JVM_OOM`, `DEPENDENCY_TIMEOUT`, `DEPENDENCY_CONNECT_FAILED`, `DEPENDENCY_DNS_FAILED`, `DEPENDENCY_4XX_CLIENT`, `DEPENDENCY_5XX_SERVER`, `DEPENDENCY_CIRCUIT_OPEN`, `JOB_TIMEOUT`, `JOB_DEAD_LETTER`, `ACTUATOR_FORBIDDEN`, `LOCK_ACQUISITION_TIMEOUT` |
- 내는 곳이 있는 47행 중 33행이 문서와 다르다. brief가 든 `IDEMPOTENCY_UNAVAILABLE`은 그중 하나다.
- `DEPENDENCY_*`: 파생 서비스의 어댑터가 `DependencyFailureException`으로 던지면 ERROR가 된다. 그때는 문서가 WARN인
`DEPENDENCY_CIRCUIT_OPEN`도 어긋난다.
- `LOCK_ACQUISITION_TIMEOUT`은 레벨과 별개의 문제가 있다(9절).
### 2.4 어긋남이 실제로 해를 끼치는 곳
- **런북 증상이 틀렸다.** `auth-token-invalid-signature.md`는 `log_level=ERROR`를 증상으로 적는다. 실제 줄은
WARN `security failure: code=AUTH_TOKEN_INVALID_SIGNATURE …`다. ERROR로 거르는 운영자는 이 사건을 못 본다.
- **칸을 채우는 일이 헛수고다.** 새 코드를 만드는 사람이 칸을 채워도 동작이 바뀌지 않는다. 파생 서비스는 96행에
값을 골라 적었다.
- 경보는 로그 레벨을 쓰지 않는다. 그래서 이 어긋남으로 경보가 빠지지는 않는다.
## 3. 선행 사례
| 출처 | 1차/2차 | 그들이 한 것 | 한계 | 가져올 것 |
| --- | --- | --- | --- | --- |
| 이 repo `client_safe_message` 칸 (`c4a066df`, 소유자 결정 11) | 1차 | 행마다 다르던 문구를 Category별 문구 표 하나(`ClientErrorMessages`)로 코드에 두었다. 칸은 그 값과 같아야 한다고 테스트로 고정했다(`OperationalErrorRegistryContractTest.everyRegistryClientMessageIsTheSharedCategoryMessage`) | 문구가 category만으로 정해져서 고정이 쉬웠다 | 코드가 원본이고 칸은 테스트가 고정한다. 레벨은 코드 하나로 정해지지 않는다는 점이 다르다(2.2) |
| 이 repo `category`·`http_status`·`retryable` | 1차 | enum이 원본이다. yaml을 enum과 테스트로 대조한다(`theEnumAndTheRegistryAgree`) | — | 레지스트리 칸은 코드가 읽거나 테스트가 고정한다는 이 repo의 관행 |
| 이 repo `env-keys.yaml`의 `required_when` (`0a6dd0e4`) | 1차 | 런타임이 강제한 적 없는 요구("app.redis.mode=sentinel")를 지우고 실제 동작에 맞췄다(`docs/registries/env-keys.yaml:2269-2273`) | — | 강제하지 않는 레지스트리 문장을 규범처럼 두지 않는다. 실제 동작으로 고친다 |
| JBoss Logging Tools (Hibernate·WildFly가 씀) | 1차, <https://jboss-logging.github.io/jboss-logging-tools/> | 메시지 id와 레벨을 코드의 annotation 한 곳에 둔다(`@Message(id = …)`, `@LogMessage(level = ERROR)`). 보고서(id, 해결 문서 링크, 메시지, 레벨)는 annotation에서 만든다(AsciiDoc·XML) | 메시지마다 레벨이 하나인 모델이다. 경로마다 레벨이 다른 우리 설계에는 그대로 맞지 않는다 | 레벨을 문서로 보이고 싶으면 손으로 쓴 칸이 아니라 코드에서 뽑는다 |
| Spring Framework `AbstractHandlerExceptionResolver` | 1차, `spring-webmvc/src/main/java/org/springframework/web/servlet/handler/AbstractHandlerExceptionResolver.java`(main) | 예외 처리 로그는 처리기 코드가 정한다. 기본은 남기지 않고, `setWarnLogCategory`로 켜면 WARN 한 레벨로 남긴다 | 오류 코드별 레벨 표는 없다 | 처리된 클라이언트 오류는 기본으로 남기지 않는다. `ServerFailureLog`의 "4xx는 답이지 사건이 아니다"와 같은 판단이다 |
## 4. 대안
### A. 칸을 지운다
- 머리말 스키마에서 `log_level` 줄을 뺀다. 대신 "로그 레벨은 오류 코드가 아니라 실패 종류와 경로가 정한다. 규칙은
`ServerFailureLog` Javadoc과 `AuthErrorResponseWriter`"라고 적는다.
- 60행에서 `log_level:` 줄을 지운다.
- 런북 2곳의 증상 줄을 실제 로그 줄로 고친다.
- `docs/upgrade/`에 파생 서비스 안내를 한 줄 더한다.
- 선택(결정 1-b): 칸이 다시 생기지 않게 "행에 `log_level`이 없다"는 단언을 레지스트리 테스트에 둔다. 두면 파생
서비스도 자기 행에서 칸을 지워야 merge 뒤 테스트가 통과한다.
### B. 칸을 남기고 코드에 맞춘 뒤 테스트로 고정한다
- 값 집합에 `NONE`(남기지 않음)과 `BY_PATH`(경로마다 다름)를 더한다. 60행을 2.3 표대로 고친다.
- 테스트는 `ServerFailureLog` 규칙을 다시 구현한 표(코드 → 기대 레벨)와 yaml을 대조한다.
- 문제: 레벨이 코드만으로 정해지지 않아서, 표가 규칙의 손 사본이 된다. 예외 종류(영속성·의존성 carrier)는 행에
없으므로, 테스트가 "`DB_*`면 ERROR"를 이름 접두어로 짐작해야 한다. 템플릿 main에 내는 곳이 없는 13행은 기대값을
정할 근거가 없다.
### C. 칸을 규범으로 만들고 코드가 읽는다
- `ApiErrorCode`에 `logLevel()`을 더한다. `OperationalError`는 값을 갖고, 파생 enum은 default 메서드로 지금 규칙을 쓴다.
- 네 전송, 보안 필터, 배경 작업이 그 값으로 남긴다. yaml은 enum과 테스트로 대조한다.
- 동작이 바뀐다. 2.3의 33행이 지금과 다른 레벨이 된다.
- 문서가 INFO·WARN인 4xx 15행이 새로 로그를 남긴다. 404·400·429마다 한 줄씩이라, 스캐너·공격 트래픽이 로그
양을 정한다.
- 409 영속성 실패는 ERROR에서 WARN으로 내려간다.
- `ServerFailureLog`의 "4xx는 남기지 않는다"와 RR6-01-06 결정을 뒤집는다. 다시 열 조건(`docs/work/reference/decisions.md`
1절)에 맞는 새 근거가 없다.
- `ApiErrorCode`는 shared-contract의 공개 인터페이스다. 파생 서비스의 enum이 영향을 받는다.
### 버린 기준선: 주석만 달기
칸에 "참고용"이라 적고 `IDEMPOTENCY_UNAVAILABLE` 한 행만 고치는 안이다. 틀린 33행 중 1행만 고쳐지고 런북은 여전히
틀린 증상을 적는다. 버린다.
### 비교
| 대안 | 효과 | 비용 | 되돌리기 | 파생 서비스 영향 | 기존 결정과 충돌 |
| --- | --- | --- | --- | --- | --- |
| A 지움 | 틀린 값 33행과 틀린 런북 증상 2곳이 사라진다. 레벨의 원본이 코드 하나로 준다 | yaml 머리말·60줄, 런북 2곳, upgrade 1줄. 코드 변경 0 (1-b면 테스트 단언 1개) | 쉽다(revert) | 1-b 없으면 할 일 없음. 1-b면 자기 96행에서 칸을 지운다 | 없다. `client_safe_message`·`env-keys` 선례와 같은 방향 |
| B 맞추고 고정 | 칸이 맞는 값이 된다 | yaml 33행, 스키마, 새 테스트(규칙의 손 사본). 규칙을 바꿀 때마다 두 곳을 고친다 | 쉽다 | 같은 테스트가 파생 행도 읽으면 자기 행도 맞춰야 한다 | 없다. 다만 규칙 사본을 하나 더 만든다 |
| C 규범화 | 소유자가 코드마다 레벨을 고를 수 있다 | shared-contract 인터페이스, 전송 넷, 보안 필터, 배경 작업, 테스트. 로그 양이 는다 | 어렵다(공개 인터페이스, 운영 로그 모양) | `ApiErrorCode` 구현 enum, 로그 수집 규칙 | `ServerFailureLog` 설계, RR6-01-06 |
## 5. 권하는 안: A
- 이 칸이 담으려던 정보("이 코드가 얼마나 시끄러운가")는 코드가 이미 실패 종류로 정한다. 그 규칙은 리뷰를 거쳐 네
전송에 하나로 모였다. 코드별 칸은 그 규칙을 담을 모양이 아니다(2.2).
- B는 그 규칙의 손 사본을 테스트에 하나 더 만든다. 사본은 고칠 곳만 늘린다. 내는 곳이 없는 13행에는 고정할 값도
없다.
- C는 코드가 맞고 문서가 틀린 상황에서 코드를 문서에 맞춘다. 문서 값은 행을 처음 넣을 때 적은 뒤 한 번도 고친 적이
없다(2.1). 레벨을 따져 본 리뷰를 거친 쪽은 코드다.
- 이 repo의 관행은 "칸은 코드가 읽거나 테스트가 고정한다"이다. 이 관행에 맞는 길은 A와 B인데, B는 고정할 값이
없다. 그래서 A다.
## 6. 반증할 수 있는 가정, 반론과 답
### 가정
1. **템플릿과 파생 서비스 밖에서 이 칸을 읽는 도구가 없다.** 틀렸다면: 로그 파이프라인이나 대시보드가 이 yaml을
읽고 있다면 칸 삭제가 그것을 깨뜨린다. 확인한 범위는 두 repo의 추적 파일이다. repo 밖 운영 도구는 모른다(결정 4).
2. **레벨은 오류 코드 하나로 정해지지 않는다.** 틀렸다면 B의 비용이 크게 준다. 확인:
`GlobalExceptionHandler.java:96-97`(IAE, WARN)과 `:108-116`(타입 변환, 로그 없음)가 같은 `BAD_PARAMETER`를 낸다.
3. **4xx를 남기지 않는 것은 의도다.** 틀렸다면, 즉 소유자가 4xx를 줄 단위로 추적하길 원하면 C가 맞다. 근거:
`ServerFailureLog.java:25`의 문장. 4xx 양은 `http.server.requests`의 `status=4xx` 지표로 이미 보인다
(`metrics.yaml:18-40`).
4. **2.3 표는 코드 읽기로 충분하다.** 틀렸다면: 다른 경로가 같은 코드를 다른 레벨로 남기면 표 칸이 바뀐다. 결론
("대부분 다르다")은 33행 중 몇 행이 바뀌어도 유지된다. 탐침을 돌리지 않은 이유는 둘이다.
- 각 경로는 레벨을 바꾸는 분기가 없는 `log.error`/`log.warn` 한 줄이다.
- 기존 테스트가 같은 레벨을 고정한다: `GrpcExceptionHandlingInterceptorTest`·`StompHandlerFailureLogTest`·
`GraphQlWireErrorMapperTest`의 `Level.ERROR`/`Level.WARN` 단언,
`GlobalExceptionHandlerTest.anIllegalArgumentIsLoggedAtWarnByItsTypeWithoutItsMessage`.
### 반론과 답
- **"레벨을 문서에서 한눈에 보는 가치가 있다."** 그 가치는 값이 맞을 때만 있다. 지금은 47행 중 33행이 틀렸다.
꼭 보이고 싶다면 JBoss Logging처럼 코드에서 뽑아야 한다. 그것은 레벨이 코드별 값이 된 뒤(C)에나 가능하다.
- **"보안 쪽 ERROR(위조 토큰 의심)는 의도였다."** 의도는 런북 문장에 남아 있지만 구현된 적이 없다. 401 서명 실패를
ERROR로 남기면 공격자가 ERROR 양을 정하게 된다. 감지가 필요하면 결정 3에서 따로 고른다.
- **"칸을 지우면 파생 서비스가 upstream merge 때 할 일이 생긴다."** 1-b를 두지 않으면 할 일이 없다. 1-b를 두면
지울 일이 생기지만, 같은 거짓 칸이 파생 서비스 96행에 남지 않는다.
## 7. 소유자가 정할 것
| # | 항목 | 선택지 | 권하는 안과 이유 | 정할 사람 |
| --- | --- | --- | --- | --- |
| 1 | `log_level` 칸 | A 지움 / B 코드 규칙에 맞추고 테스트로 고정 / C 규범화(코드가 읽음) | **A**. 5절 | 소유자 |
| 1-b | A일 때 칸이 다시 생기는 것을 막는 단언 | 둔다(파생 서비스도 자기 행에서 지운다) / 두지 않는다 | **둔다**. 칸이 거짓인 것은 파생 서비스 행도 같다. upgrade 안내 "반드시 할 일"에 한 줄 | 소유자 |
| 2 | 보안 필터가 5xx 두 코드(`AUTH_JWKS_UNAVAILABLE` 503, `INTERNAL_AUTH_MISCONFIGURATION` 500)를 WARN으로 남기는 것 | ERROR로 올림 / WARN 유지 | **ERROR로 올림**. 다른 모든 경로가 5xx를 ERROR로 남긴다. 둘 다 서버 쪽 고장(키 서버 장애, 설정 오류)이다. 1번과 관계없이 동작 변경이라 별도 개선 작업으로 한다 | 소유자 |
| 3 | 401 서명·issuer·audience 불일치(문서가 ERROR로 의도) | WARN 유지, 런북은 WARN 줄의 code로 찾게 고침 / ERROR로 올림 / WARN 유지 + 코드별 인증 실패 지표를 새로 둠 | **WARN 유지**. 클라이언트가 만드는 실패라 ERROR로 올리면 공격 트래픽이 ERROR 양을 정한다. 경보가 필요하면 세 번째 안이다. 지금은 코드별 인증 실패 지표가 없다(`metrics.yaml`) | 소유자 |
| 4 | repo 밖에서 이 칸을 읽는 도구 | 있음 / 없음 | **모름**. 두 repo의 추적 파일에는 없다. 있으면 A를 다시 본다 | 소유자 |
## 8. 결정 뒤 할 일 (이 메모에서는 하지 않았다)
- A를 고르면: `docs/registries/error-codes.yaml` 머리말과 60행, 런북 2곳, `docs/upgrade/` 안내 한 줄, (1-b면)
레지스트리 테스트 단언. 공개 계약 변경이라 크기는 큼이고 `docs/work/improve.md`로 한다. 결정은
`docs/work/reference/decisions.md`에 기록한다.
- 결정 2를 고르면: `AuthErrorResponseWriter`의 레벨 분기와 테스트(RED → GREEN).
- B나 C를 고르면 이 메모의 4절을 계획서로 옮겨 다시 크기를 잡는다.
## 9. 이 조사 중 본 별개 문제 (범위 밖, 고치지 않았다)
- `LockAcquisitionTimeoutException`은 `ApiErrorCarrier`를 구현하지 않는다
(`src/application-core/src/main/java/dev/caskeleton/application/lock/LockAcquisitionTimeoutException.java:13`).
inbound 어디에도 이 예외의 처리기가 없다(`grep -rln LockAcquisitionTimeoutException src`: persistence-jpa와 테스트뿐).
- Javadoc은 "The web adapter maps it to 409"라고 적는다. 하지만 web은 `handleUnknown`을 거쳐 `INTERNAL_ERROR` 500으로
답할 것으로 읽힌다(`GlobalExceptionHandler.java:195-203`).
- `LockAcquisitionTimeoutClassificationContractTest`가 막으려는 "500 INTERNAL로 뭉개기"(D7)와 같은 모양이다. 그
테스트는 enum과 레지스트리만 보고 전송 경로는 보지 않는다.
- 코드 읽기 결과이고 탐침은 돌리지 않았다. 결함 후보로 `docs/work/improve.md` 절차에 넘긴다.
## 10. 결정 (2026-11-06)
소유자 답은 "권하는 안대로"다(총괄 세션 전달, 2026-11-06). 7절 각 항목은 이렇게 정해졌다.
| # | 결정 | 적용한 곳 |
| --- | --- | --- |
| 1 | A. `log_level` 칸을 지운다. 레지스트리 머리말이 레벨을 정하는 코드(`ServerFailureLog`, `AuthErrorResponseWriter`)를 가리킨다 | `docs/registries/error-codes.yaml` 머리말과 60행 |
| 1-b | 칸이 다시 생기지 않게 단언을 둔다. 파생 서비스는 자기 행에서도 지운다 | `OperationalErrorRegistryContractTest.noRegistryRowCarriesALogLevel`(태그 `document-contract`), `docs/upgrade/2026-11-maturity-review.md` 「반드시 할 일」 17·B-44 |
| 2 | 보안 필터는 5xx(`AUTH_JWKS_UNAVAILABLE` 503, `INTERNAL_AUTH_MISCONFIGURATION` 500)를 ERROR로 남긴다 | `AuthErrorResponseWriter`(5xx ERROR, 4xx WARN), `EnvelopeAuthenticationEntryPointTest`, web README, 런북 2곳, upgrade 5절 |
| 3 | 401 서명·issuer·audience 불일치는 WARN으로 둔다. 런북은 WARN 줄의 `code=`로 찾게 고친다 | `docs/runbooks/auth-token-invalid-signature.md`, 서명 실패 WARN을 고정한 테스트 |
| 4 | repo 밖에서 이 칸을 읽는 도구는 없는 것으로 본다 | — |
결정 색인: `docs/work/reference/decisions.md` 2.3절 「오류 코드 로그 레벨」.