fix(observability)!: 관측 registry를 코드와 맞추고 로그 내용·로컬 비밀 기본값을 고친다 #32

Merged
donghyeon.kang merged 4 commits from claude/r9-a-obs-logs into main 2026-11-13 06:28:56 +00:00
4 Commits
Author SHA1 Message Date
donghyeon.kang 4f73e62e23 Merge branch 'main' into claude/r9-a-obs-logs
pr / done (pull_request) Successful in 13m43s
2026-11-13 04:44:09 +00:00
DongHyeonka 354b7fc959 fix(observability)!: 지표·MDC·헤더 registry를 코드가 실제로 내는 것과 맞춘다
pr / done (pull_request) Canceled after 0s
관측 registry가 코드와 양쪽으로 어긋난다. metrics.yaml에는 아무 코드도
등록하지 않는 행 열하나와 코드에 없는 tag 값이 있고, 코드가 등록하는
graphql·notification·http.client·fileserver·mongodb·jpa.query 지표 다수가
없다. mdc-keys.yaml은 18키 중 코드가 넣는 5키만 맞고 required_in이 틀렸다.
headers.yaml은 X-Request-Id·X-Correlation-Id를 ulid로 적고 아무도 쓰지
않는 Deprecation·Sunset·tracestate를 적는다. 전송마다 correlation 규칙이
다른데 registry는 하나로 적는다. 단일 인스턴스 in-process lock은
lock.acquisition을 세지 않아 그 지표가 0이다. 밑줄 든 meter 이름 둘이
이름 규칙을 어긴다.

- 행마다 등록하는 main 파일(source)·상수(constant)·등록 주체
  (registered_by)를 적고, MetricsRegistryCodeAlignmentTest가 행 → 코드(이름이
  상수면 그 상수를 쓰는 곳까지)와 코드(글자·상수 이름의 builder·registry·
  Metrics 호출) → 행 두 방향을 본다. 템플릿이 부르지 않는 공개 메서드로만
  생기는 job.* 행은 emitted_when을 적는다. 버린 안: 행만 지우기(새 지표가
  다시 빠진다).
- mdc-keys는 5키와 전송별 표, headers는 source가 든 33행(서비스 controller용
  상수는 service: 출처), StructuredLog·HeaderRegistry 시험이 코드 상수와
  집합을 대조한다. 두 registry 시험은 시험 도우미 MainSources를 같이 쓴다.
- slo_driven 행은 MetricsDistributionMeterFilter 대상과 같은 집합이다(두
  방향 시험). histogram을 켜지 않는 hikaricp timer 행은 평균으로 경보한다.
  graphql.datafetcher·dataloader 행에 Spring 기본 tag를 적는다.
- in-process lock을 MeteredDistributedLock으로 감싼다.
- http.client.ratelimit.rejected, fileserver.upload.offset.mismatch로
  이름을 바꾸고 http.client.circuit.state.rejected를 상수로 둔다.
- CardinalityBounds(status 40·outcome 6·uri), MetricNaming 단위 규칙,
  SLO filter 대상(http.server.requests·jvm.gc.pause)을 문서와 맞춘다.

위험: 지표 이름 둘이 바뀌고 단일 인스턴스 lock 지표가 생긴다. 그 이름으로
만든 대시보드·경보를 옮겨야 한다(docs/upgrade/2026-11-round9-observability.md
8~13행). ApachePoolMetricsBinder·MongoTransactionRetry 지연은 다른 묶음이
맡는다.

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

Refs: RR9-02-05, RR9-02-07, RR9-02-08, RR9-02-27, RR9-03-05
BREAKING CHANGE: http.client.rate_limit.rejected → http.client.ratelimit.rejected,
  fileserver.upload.offset_mismatch → fileserver.upload.offset.mismatch,
  CardinalityBounds 상수. docs/upgrade/2026-11-round9-observability.md 8~13행.
2026-11-13 13:12:27 +09:00
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
DongHyeonka 75df7615e5 fix(logging)!: 로그 줄이 원본 경로·SQL을 싣지 않고 감사 줄을 버리지 않게 한다
로그 줄이 남기지 말아야 할 값을 싣고, 남겨야 할 줄을 버린다. 401·403
보안 WARN, route를 못 찾은 요청 로그, 처리하지 못한 예외 ERROR가 원본
request URI(식별자·토큰이 든 경로)를 싣는다. outbox relay·파일 서버 정리
스케줄러는 실패를 통째로 남겨 SQL·제약 이름·값이 원인 사슬로 따라간다.
SamplingTurboFilter는 INFO 이하를 logger 구분 없이 표본으로 버려 감사
logger의 INFO 줄도 사라진다. JSON 로그 profile 칸은 Logback이 처음 읽은
환경 변수 값이라 Spring이 해석한 profile과 다를 수 있다. HeaderSanitizer는
운영 코드가 부르지 않는 공개 유틸리티로 남아 있다.

- LoggedPath: route template이 있으면 그것, 없으면 식별자가 들 수 있는
  마디를 {}로 가린 경로. 세 줄이 모두 쓴다. 버린 안: 원본 URI 그대로 두고
  문서로 경고(로그 수집기가 이미 받는다).
- 스케줄러 실패는 새 ServerFailureLog.forBackgroundTask로 남긴다: 분류된
  persistence 실패는 원인 사슬 없이, 그 밖의 carrier는 client 쪽 코드여도
  stack과 함께(요청이 없으니 결함이다). composition:outbox-relay에
  shared-contract edge를 더한다(gradle/modules.json).
- SamplingTurboFilter는 AUDIT marker와 이름 끝 마디가 audit·security인
  logger를 표본에서 뺀다(이름별 판정은 캐시).
- ResolvedProfileJsonProvider가 줄을 쓸 때의 해석된 profile을 쓴다.
- HeaderSanitizer와 시험을 지우고 capability-status 제거 표에 적는다.

위험: 경로를 보던 로그 검색이 가린 경로를 본다. 감사 줄이 표본에서 빠져
양이 늘 수 있다. docs/upgrade/2026-11-round9-observability.md 1~5행.

검증: desktop에서 바뀐 leaf check·:app-bootstrap:test·systemTest·
documentContractTest·repositoryContractTest, scripts/verify.sh pr rc=0
(묶음 셋을 합친 트리). 새 시험은 고치기 전 트리에서 실패했다(RED).

Refs: RR9-02-09, RR9-02-15, RR9-02-21, RR9-02-22, RR9-02-26
BREAKING CHANGE: 보안·요청·예외 로그 줄의 경로 값과 JSON profile 칸의 출처,
  HeaderSanitizer 삭제. docs/upgrade/2026-11-round9-observability.md 1~5행.
2026-11-13 13:12:09 +09:00