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행.
7.3 KiB
7.3 KiB
업그레이드 안내 — 2026-11 관측 registry·로그 내용·로컬 비밀 기본값
- 범위: 2026-11-12 전체 리뷰의 관측 registry 묶음, 로그 내용 묶음, 비밀·IP 문서 묶음을 고친 변경. 지표·MDC·헤더 registry를 코드에
맞췄고, 로그 줄이 원본 경로·SQL·요청 값을 덜 싣게 했고, 로컬 비밀 기본값을
__LOCAL_DEV_규칙에 맞췄다. - 근거: 2026-11-12 전체 리뷰(
docs/reviews/2026-11-12-round9-review/)의 RR9-02-05·07·08·09·10·12·13·15·21·22·26·27, RR9-03-05
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에 행을 더한 서비스 |
| 8 | 지표 이름 둘을 이름 규칙(dot.case, 밑줄 없음)에 맞췄다: http.client.rate_limit.rejected → http.client.ratelimit.rejected, fileserver.upload.offset_mismatch → fileserver.upload.offset.mismatch |
그 이름을 쓰는 대시보드·경보를 새 이름으로 바꾼다 | 그 패널이 비고 경보가 울리지 않는다 | httpclient·파일 서버를 켠 서비스 |
| 9 | docs/registries/metrics.yaml에서 아무 코드도 등록하지 않던 행 열하나를 지웠다(http.server.requests.latency, dependency.client.requests, db.query.duration, resilience4j.* 셋, cache.* 다섯). http.server.requests의 tag는 Spring Framework 기본 convention이 다는 값(method, uri, 숫자 status, outcome, exception, error)이다 |
그 이름·tag(uri_template, 2xx)로 만든 경보를 실제 이름으로 바꾼다. 지연 경보는 http.server.requests로 건다 |
경보가 없는 시계열을 본다 | registry를 보고 경보를 만든 서비스 |
| 10 | MetricsDistributionMeterFilter의 SLO 대상이 http.server.requests·jvm.gc.pause 둘이다. 아무도 등록하지 않던 http.server.requests.latency·dependency.client.requests·db.query.duration은 대상에서 빠졌다 |
그 셋 이름으로 timer를 직접 만들었으면 자기 MeterFilter로 SLO histogram을 켠다 |
그 timer의 _bucket 시계열(인스턴스 사이 p99)이 사라진다 |
그 셋 이름으로 timer를 직접 만든 서비스 |
| 11 | 단일 인스턴스(in-process) lock도 lock.acquisition을 센다 |
단일 인스턴스 배포의 lock 경보 기준선을 다시 잡는다 | 새로 생긴 값으로 경보가 울릴 수 있다 | persistence-jpa를 켠 서비스 |
| 12 | docs/registries/mdc-keys.yaml은 코드가 MDC에 넣는 다섯 key(request_id, trace_id, span_id, correlation_id, user_principal)만 적는다. headers.yaml에서 아무도 쓰지 않던 Deprecation·Sunset을 지우고 쓰는 헤더 행을 더했다(tracestate는 W3C 전파가 쓰므로 framework: 행으로 둔다). 지표·헤더 행마다 source가 있다 |
자기 MDC key·헤더·지표를 더한 서비스는 MdcKeys·행을 같이 더하고 source를 적는다 |
새 정합 시험이 실패한다 | registry에 행을 더한 서비스 |
| 13 | testFixtures CardinalityBounds: STATUS_CODE가 7에서 40(숫자 HTTP status)으로, RESILIENCE4J_OUTCOME(5)이 OUTCOME(6)으로 바뀌었고 uri key가 더해졌다. MetricNaming.ALLOWED_UNITS는 이름 접미사가 아니라 unit 칸의 값이다 |
그 상수를 쓰던 시험을 새 이름·값으로 고친다 | 시험 컴파일이 실패한다 | 그 fixture를 쓰는 서비스 |
3. 바뀌지 않은 것
- 지표·MDC key·헤더 이름은 위 8번 둘 말고 그대로다. 응답 모양도 그대로다.