This commit is contained in:
@@ -0,0 +1,33 @@
|
||||
# 업그레이드 안내 — 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번 둘 말고 그대로다. 응답 모양도 그대로다.
|
||||
Reference in New Issue
Block a user