Files
clean-architecture-backend-…/docs/upgrade/2026-11-round9-observability.md
T
DongHyeonka a7f44d8a8d fix(secrets)!: 로컬 비밀 기본값을 __LOCAL_DEV_ 규칙에 맞추고 가림 약속을 구현과 맞춘다
로컬 비밀 기본값(compose·lane·application-local의 DB 비밀번호, MinIO
root, Keycloak admin)이 __LOCAL_DEV_ 접두어 규칙을 따르지 않아 prod
sentinel 검사가 그 값을 알아보지 못한다. secrets-classification.yaml은
구현 없는 masking_rule full_except_last_4를 약속하고, full로 적은 키 일부
(salt·PEM·HMAC/signing key, URI 사용자 정보)를 LogMaskingPatterns가 가리지
않는다. required_test는 없는 시험 이름이다. IP 신뢰 설정을 두 문서가
다르게 적는다(application-local은 framework, rate-limiting은 native).

- 기본값을 __LOCAL_DEV_db_password__·__LOCAL_DEV_minio_root__·
  __LOCAL_DEV_keycloak_admin__로 바꾼다.
- masking_rule을 full|userinfo|none 셋으로 줄이고, LogMaskingPatterns의
  키 목록을 넓히고 URI userinfo와 여러 줄 PEM 블록 가림을 더한다. 시험이 masking_rule 어휘,
  required_test 클래스 존재, full·userinfo 행이 실제로 가려지는지 본다.
  버린 안: full_except_last_4 구현(끝 네 자리를 남길 값이 없다).
- IP 신뢰는 native + 내부 proxy 목록 하나로 적는다.

위험: 로컬 compose 볼륨이 옛 비밀번호로 만들어졌으면 DB 접속이 실패한다
(docs/upgrade/2026-11-round9-observability.md 6행). 운영 값은 바뀌지
않는다.

검증: 위와 같은 desktop 실행(묶음 셋을 합친 트리) rc=0.

Refs: RR9-02-10, RR9-02-12, RR9-02-13
BREAKING CHANGE: 로컬 compose·lane의 비밀 기본값이 바뀐다. 옛 볼륨은
  지우거나 env로 옛 값을 준다(docs/upgrade/2026-11-round9-observability.md 6~7행).
2026-11-13 13:12:09 +09:00

4.5 KiB

업그레이드 안내 — 2026-11 관측 registry·로그 내용·로컬 비밀 기본값

  • 범위: 2026-11-12 전체 리뷰의 로그 내용 묶음과 비밀·IP 문서 묶음을 고친 변경. 로그 줄이 원본 경로·SQL·요청 값을 덜 싣게 했고, 로컬 비밀 기본값을 __LOCAL_DEV_ 규칙에 맞췄다.
  • 근거: 2026-11-12 전체 리뷰(docs/reviews/2026-11-12-round9-review/)의 RR9-02-09·10·12·13·15·21·22·26

1. 누가 읽나

이 템플릿을 upstream remote로 두고 merge해 받는 파생 서비스가 읽는다. 특히 지표·로그로 대시보드와 경보를 만든 서비스, 로컬 compose로 개발하는 사람이다.

2. 할 일

# 바뀐 것 할 일 안 하면 해당 서비스
1 로그의 경로: 401·403 보안 줄의 path=, handler를 못 찾은 요청 로그 줄의 uri_template=, 처리하지 못한 예외 줄은 원본 URI 대신 가린 경로(식별자가 들 수 있는 마디는 {})를 쓴다(LoggedPath). 정적 자원 handler가 받은 없는 경로는 전처럼 /**다 원본 경로로 검색하던 로그 질의를 바꾼다 질의가 맞는 줄을 못 찾는다 로그 질의를 만든 서비스
2 감사·보안 logger(이름의 마지막 마디가 audit·security, 또는 AUDIT marker를 단 줄)의 INFO 줄은 APP_LOG_SAMPLING_RATE와 상관없이 버리지 않는다 다른 이름의 감사 logger가 있으면 AUDIT marker를 단다 그 logger의 감사 줄이 표본 비율만큼 버려진다 자기 감사 logger를 둔 서비스
3 outbox relay·파일 서버 정리 작업의 실패 줄은 분류된 실패를 ServerFailureLog 모양으로 남긴다(persistence 실패는 원인 사슬 없이, 그 밖의 carrier는 client 쪽 코드여도 stack과 함께). composition:outbox-relay가 shared-contract에 기댄다(registry edge 추가) gradle/modules.json을 자기 쪽에서 고친 서비스는 그 edge를 받는다 의존 검사가 실패한다 registry를 바꾼 서비스
4 JSON 로그의 profile 칸은 줄을 쓸 때의 해석된 profile이다(ResolvedProfileJsonProvider). customFields에는 app만 남았다 logback-spring.xml을 복사해 고친 서비스는 같은 provider 줄을 넣는다 profile이 환경 변수 값에 머문다 logback 설정을 바꾼 서비스
5 web HeaderSanitizer(로그용 헤더 가림 공개 유틸리티)와 그 시험을 지웠다. 운영 코드가 부르지 않았고, 요청 로그는 헤더를 싣지 않는다 그 클래스를 부르던 서비스는 자기 코드로 옮긴다(마지막으로 있던 커밋은 docs/capability-status.md 제거 표) 컴파일이 실패한다 HeaderSanitizer를 부르던 서비스
6 로컬 비밀 기본값이 __LOCAL_DEV_ 접두어다: DB 비밀번호 __LOCAL_DEV_db_password__(compose·lane·application-local.yml), MinIO root __LOCAL_DEV_minio_root__, Keycloak admin __LOCAL_DEV_keycloak_admin__. prod에서 이 값이면 기동이 실패한다 옛 기본값으로 만든 로컬 volume(Postgres caskeleton-db-data, MinIO caskeleton-minio-data)이 있으면 저장소 루트 .env(compose 보간과 bootRun이 읽는 파일)에 옛 값을 APP_DATASOURCE_PASSWORD·MINIO_ROOT_PASSWORD로 두거나 volume을 지우고 다시 만든다(docker compose down -v). Keycloak은 volume이 없어 컨테이너를 다시 만들면 새 비밀번호로 들어간다 로컬 앱이 DB 인증에 실패하고 minio-init이 bucket을 만들지 못한다 로컬 compose를 쓰는 사람
7 docs/registries/secrets-classification.yaml의 masking_rule은 full·userinfo·none뿐이다(full_except_last_4는 구현이 없었다). Layer 1 가림이 salt·PEM·HMAC/signing/encryption/credential/private key 이름, 여러 줄 PEM 블록 전체, URI 사용자 정보 비밀번호(scheme://user:****@host)도 가린다. required_test는 app-bootstrap 시험 폴더에 있는 시험 클래스 이름이어야 한다(옛 secrets-contract:* 표지는 안 된다). 쓰지 않는 행 넷(APP_PROFILE, SERVER_PORT, APP_NOTIFICATION_SLACK_WEBHOOK_URL, APP_SECURITY_GOOGLE_OAUTH_CLIENT_ID)을 지웠다 자기 행에 full_except_last_4를 쓴 서비스는 full이나 userinfo로, secrets-contract:*는 시험 클래스 이름으로 바꾼다 SecretsClassificationRegistryTest가 실패한다 registry에 행을 더한 서비스

3. 바뀌지 않은 것

  • 지표·MDC key·헤더 이름과 응답 모양은 그대로다.