Merge branch 'main' into claude/r9-objstore-contract
pr / done (pull_request) Canceled after 4m7s

This commit is contained in:
2026-11-13 06:28:59 +00:00
67 changed files with 3122 additions and 907 deletions
+2 -1
View File
@@ -402,7 +402,8 @@ app:
**Sampling (`SamplingTurboFilter`)**
- **`APP_LOG_SAMPLING_RATE`** — `INFO` 이하 로그를 남길 확률. [0.0, 1.0] float. prod 는 `0.1`(10%
샘플링)이 권장, `WARN`/`ERROR` 는 항상 유지. `1.0` = 샘플링 없음(dev/local/staging 기본).
샘플링)이 권장, `WARN`/`ERROR` 는 항상 유지. 감사·보안 기록(logger 이름의 마지막 마디가 `audit`·`security`, 또는
`AUDIT` marker)도 레벨과 상관없이 유지한다. `1.0` = 샘플링 없음(dev/local/staging 기본).
### 분산 추적
+1
View File
@@ -529,3 +529,4 @@ web 경로의 `W/`는 `src/adapter/inbound/web/src/main/java/dev/caskeleton/adap
| 설정 키 `app.notification.platform.smtp.max-concurrency`(이름 변경 → `dispatch-concurrency`, env `APP_NOTIFICATION_PLATFORM_SMTP_DISPATCH_CONCURRENCY` 그대로) | `NotificationSmtpSettings.java`, `notification.yml` | `0ebb77b5` | P20-new-1 |
| Redis ACL `+@pubsub`·`&prod:*`(application 계정 2개) | `infra/redis-sdk/acl/*.acl` | `0ebb77b5` | P22-new-2 |
| 시험 `ComposeMergeCharacterizationTest` | `src/bootstrap/app/src/integrationTest/java/dev/caskeleton/bootstrap/compose/ComposeMergeCharacterizationTest.java` | `ca1fbfde`(지운 커밋 `23139722`의 부모) | 어느 lane도 고르지 않아 한 번도 돌지 않았다(`integrationTest` lane은 `requires`로 적은 클래스만 고른다). 보던 것(기본·dev 조합 렌더링, 계약 스크립트)은 PR 단계 `verifyComposeProfiles`가 모든 lane으로 본다(2026-11-12 리뷰) |
| `HeaderSanitizer`(로그용 헤더 가림)와 시험 `HeaderSanitizerTest` | `src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/observability/HeaderSanitizer.java`, `src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/observability/HeaderSanitizerTest.java` | `e6c3b159` | 운영 코드가 부르지 않았다. 요청 로그는 헤더를 싣지 않는다 |
+17 -10
View File
@@ -13,19 +13,26 @@
| `http.client.timeout` | 단계별 시간 초과 |
| `http.client.request.bytes` | 요청 wire 바이트 |
| `http.client.response.bytes` | 응답 바이트 |
| `http.client.active` | 진행 중인 시도 |
| `http.client.pool.connections` | 빌려 간 connection과 남은 connection |
| `http.client.pool.pending` | pool 대기자 |
| `http.client.pool.acquire.duration` | pool 대기 시간 |
| `http.client.dns.duration` | DNS 시간 |
| `http.client.connect.duration` | 연결 시간 |
| `http.client.tls.duration` | TLS 시간 |
| `http.client.circuit.state` | circuit 상태 |
| `http.client.circuit.state` | circuit 상태(1 = open) |
| `http.client.circuit.state.rejected` | circuit이 열려 거부한 호출 |
| `http.client.bulkhead.rejected` | bulkhead 거부 |
| `http.client.rate_limit.rejected` | 로컬 속도 제한 거부 |
| `http.client.oauth.refresh` | token 갱신 결과 |
| `http.client.ratelimit.rejected` | 로컬 속도 제한 거부 |
| `http.client.ssrf.rejected` | dynamic target 거부 |
이름은 정했지만 아직 아무 코드도 내지 않는 metric이다(`HttpClientObservationNames` 상수, `DeclaredMetricsAreEmittedTest`의
「아직 안 냄」 목록). 대시보드·경보에 쓰지 않는다. `docs/registries/metrics.yaml`에도 행이 없다.
| Metric | 내려면 필요한 것 |
|---|---|
| `http.client.active` | 논리 호출 observation 수명에 묶인 진행 중 gauge |
| `http.client.pool.acquire.duration` | engine마다 요청 단계 시간 |
| `http.client.dns.duration` | engine마다 요청 단계 시간 |
| `http.client.connect.duration` | engine마다 요청 단계 시간 |
| `http.client.tls.duration` | engine마다 요청 단계 시간 |
| `http.client.oauth.refresh` | token loader가 `MeterRegistry`를 받는 것 |
`http.client.requests`는 시도를 세고 `http.client.logical.calls`는 사용자 호출을 센다. 둘이 벌어지면 재시도가
실패를 흡수하고 있다는 뜻이다. 장애 때 가장 먼저 볼 곳이다.
@@ -35,8 +42,8 @@
|---|---|---|
| 논리 호출은 괜찮은데 시도가 치솟는다 | upstream이 나빠졌고 재시도가 흡수하고 있다 | 이유별 `http.client.retry.count` |
| `http.client.ambiguous`가 0이 아니다 | 멱등이 아닌 쓰기가 `SENT_NO_RESPONSE`에 닿는다 | upstream과 맞춰 본다. 멱등 key를 검토한다 |
| pool 대기가 오른다 | pool이 작거나 upstream이 느리다 | `http.client.pool.acquire.duration`, `pool.connections` |
| circuit이 열렸다 | 계속된 upstream 실패: transport 오류, 5xx, 408, 429 | `http.client.circuit.state`. 로컬 거부와 그 밖의 4xx는 circuit을 열지 않는다 |
| pool 대기가 오른다 | pool이 작거나 upstream이 느리다 | `http.client.pool.pending`, `pool.connections` |
| circuit이 열렸다 | 계속된 upstream 실패: transport 오류, 5xx, 408, 429 | `http.client.circuit.state`, `http.client.circuit.state.rejected`. 로컬 거부와 그 밖의 4xx는 circuit을 열지 않는다 |
| `http.client.ssrf.rejected`가 0이 아니다 | 호출자가 내부 URL을 넣고 있다 | Dynamic Target 정책과 감사 기록 |
## Actuator
+309 -30
View File
@@ -7,13 +7,19 @@
# - W3C 표준 헤더: 소문자 (traceparent, tracestate)
# - mdc_key: snake_case (foundation이 정본)
# - envelope_meta_field: camelCase (envelope이 정본)
# - 행은 코드가 실제로 읽거나 쓰는 헤더다. `source`는 셋 중 하나다(HeaderRegistryRuntimeAlignmentTest가 대조한다).
# - main 파일 경로: 그 이름 글자를 가지고 실제로 쓰는 파일. 이름이 상수면 그 상수를 쓰는 곳이 있어야 한다.
# - `service: <경로>`: 서비스 controller가 읽으라고 둔 `ApiHeaders` 상수다. 템플릿 main은 그 상수를 쓰지 않는다
# (파일 서버는 If-Match·If-None-Match를 Spring `HttpHeaders` 상수로 읽는다). 시험이 정한 헤더만 이 출처를 쓴다.
# - `framework: …`: Spring·라이브러리가 읽거나 쓴다.
headers:
# source: feature-operational-error-observability-foundation.md L97
# "request_id | inbound filter (생성 또는 X-Request-Id 헤더) | response header X-Request-Id"
- name: X-Request-Id
direction: both
type: ulid
type: uuid-or-caller-token
format: "UUID; 받는 값은 [A-Za-z0-9._-]{1,128}"
required: false
generated_if_missing: true
mdc_key: request_id
@@ -22,6 +28,7 @@ headers:
case_style: kebab
compatibility_impact: none
required_test: contract-verification:envelope-headers
source: "src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/mvc/filter/WebMvcRequestIdFilter.java"
# source: feature-api-contract-baseline.md L77 / feature-rate-limit-idempotency-contract.md L66-67
# "idempotency header 이름은 Idempotency-Key" / "기본 scope는 (authenticatedPrincipal, idempotencyKey, useCaseName)"
@@ -36,6 +43,7 @@ headers:
case_style: kebab
compatibility_impact: additive
required_test: contract-verification:idempotency-replay
source: "service: src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/http/ApiHeaders.java"
# source: feature-rate-limit-idempotency-contract.md L85 / foundation L85
# "RATE_LIMIT | ... | 429 | true (Retry-After 이후)" / "retry-after 기준 없이 429를 반환하면 실패"
@@ -50,6 +58,7 @@ headers:
case_style: kebab
compatibility_impact: additive
required_test: contract-verification:rate-limit-headers
source: "src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/http/ApiHeaders.java"
# source: feature-rate-limit-idempotency-contract.md scope L26 (rate limit response/log 기준)
# app.rate-limit.enabled=true인 요청 경로에서만 생성되는 rate-limit 응답 표면
@@ -64,6 +73,7 @@ headers:
case_style: kebab
compatibility_impact: additive
required_test: contract-verification:rate-limit-headers
source: "src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/http/ApiHeaders.java"
# source: feature-rate-limit-idempotency-contract.md scope L26 (rate limit response/log 기준)
- name: X-RateLimit-Remaining
@@ -77,6 +87,7 @@ headers:
case_style: kebab
compatibility_impact: additive
required_test: contract-verification:rate-limit-headers
source: "src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/http/ApiHeaders.java"
# source: feature-rate-limit-idempotency-contract.md scope L26 (rate limit response/log 기준)
- name: X-RateLimit-Reset
@@ -90,34 +101,7 @@ headers:
case_style: kebab
compatibility_impact: additive
required_test: contract-verification:rate-limit-headers
# source: feature-api-compatibility-deprecation-contract.md L87
# "deprecation marker | OpenAPI deprecated: true + design record | response header optional"
- name: Deprecation
direction: outbound
type: http-date
required: false
generated_if_missing: false
mdc_key: null
envelope_meta_field: null
owner_branch: feature-api-compatibility-deprecation-contract
case_style: kebab
compatibility_impact: additive
required_test: contract-verification:deprecation-marker
# source: feature-api-compatibility-deprecation-contract.md L87
# "deprecation marker | OpenAPI deprecated: true + design record | response header optional" (RFC 8594 Sunset)
- name: Sunset
direction: outbound
type: http-date
required: false
generated_if_missing: false
mdc_key: null
envelope_meta_field: null
owner_branch: feature-api-compatibility-deprecation-contract
case_style: kebab
compatibility_impact: additive
required_test: contract-verification:deprecation-marker
source: "src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/http/ApiHeaders.java"
# source: feature-distributed-tracing-contract.md L64, L85
# "propagation header는 W3C traceparent default" / "HTTP | traceparent, tracestate (W3C)"
@@ -132,6 +116,7 @@ headers:
case_style: kebab
compatibility_impact: none
required_test: contract-verification:trace-propagation
source: "src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/mvc/filter/WebMvcRequestIdFilter.java"
# source: feature-distributed-tracing-contract.md L66, L85
# "propagation format = W3C traceparent + tracestate only. B3 propagation은 forbidden"
@@ -146,12 +131,14 @@ headers:
case_style: kebab
compatibility_impact: none
required_test: contract-verification:trace-propagation
source: "framework: Micrometer Tracing(OTel)의 W3C 전파가 traceparent와 함께 읽고 쓴다"
# source: feature-operational-error-observability-foundation.md L100
# "correlation_id | inbound header X-Correlation-Id 또는 생성 | HTTP X-Correlation-Id, message header correlation_id"
- name: X-Correlation-Id
direction: both
type: ulid
type: uuid-or-caller-token
format: "UUID; 받는 값은 [A-Za-z0-9._-]{1,128}"
required: false
generated_if_missing: true
mdc_key: correlation_id
@@ -160,6 +147,7 @@ headers:
case_style: kebab
compatibility_impact: none
required_test: contract-verification:envelope-headers
source: "src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/mvc/filter/WebMvcRequestIdFilter.java"
# source: feature-security-operational-baseline.md L66
# "JWT Resource Server를 baseline security model로 둠" (Authorization 헤더의 Bearer 토큰)
@@ -174,6 +162,7 @@ headers:
case_style: kebab
compatibility_impact: none
required_test: contract-verification:jwt-resource-server
source: "framework: Spring Security bearer token resolver가 읽는다"
# source: feature-security-operational-baseline.md L83-90 (AuthN/AuthZ Decision Matrix)
# 401 응답 시 WWW-Authenticate (Bearer realm/error) — Spring Security JWT Resource Server의 표준 challenge 헤더
@@ -188,3 +177,293 @@ headers:
case_style: kebab
compatibility_impact: none
required_test: contract-verification:jwt-resource-server
source: "framework: HttpHeaders.WWW_AUTHENTICATE(AuthErrorResponseWriter가 401에 쓴다)"
# === web 응답·조건부 요청 (adapter:inbound:web) ===
# 모든 응답에 no-store(CacheControlFilter). 파일 다운로드는 자기 값을 쓴다.
- name: Cache-Control
direction: outbound
type: string
required: false
generated_if_missing: true
mdc_key: null
envelope_meta_field: null
owner_branch: web-platform
case_style: kebab
compatibility_impact: none
required_test: contract-verification:envelope-headers
source: "src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/http/ApiHeaders.java"
- name: Vary
direction: outbound
type: comma-separated
required: false
generated_if_missing: true
mdc_key: null
envelope_meta_field: null
owner_branch: web-platform
case_style: kebab
compatibility_impact: none
required_test: contract-verification:envelope-headers
source: "src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/http/ApiHeaders.java"
# 405 응답(GlobalExceptionHandler).
- name: Allow
direction: outbound
type: comma-separated
required: false
generated_if_missing: false
mdc_key: null
envelope_meta_field: null
owner_branch: web-platform
case_style: kebab
compatibility_impact: none
required_test: contract-verification:envelope-headers
source: "framework: Spring HttpHeaders.setAllow — GlobalExceptionHandler가 405 응답에 쓴다(ApiHeaders.ALLOW는 쓰지 않는다)"
# 201 생성 응답(durable operation, 파일 업로드).
- name: Location
direction: outbound
type: uri
required: false
generated_if_missing: false
mdc_key: null
envelope_meta_field: null
owner_branch: web-platform
case_style: kebab
compatibility_impact: none
required_test: contract-verification:envelope-headers
source: "src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/http/ApiHeaders.java"
- name: ETag
direction: outbound
type: entity-tag
required: false
generated_if_missing: false
mdc_key: null
envelope_meta_field: null
owner_branch: web-platform
case_style: kebab
compatibility_impact: none
required_test: contract-verification:envelope-headers
source: "src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/http/ApiHeaders.java"
- name: If-Match
direction: inbound
type: entity-tag
required: false
generated_if_missing: false
mdc_key: null
envelope_meta_field: null
owner_branch: web-platform
case_style: kebab
compatibility_impact: none
required_test: contract-verification:envelope-headers
source: "service: src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/http/ApiHeaders.java"
- name: If-None-Match
direction: inbound
type: entity-tag
required: false
generated_if_missing: false
mdc_key: null
envelope_meta_field: null
owner_branch: web-platform
case_style: kebab
compatibility_impact: none
required_test: contract-verification:envelope-headers
source: "service: src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/http/ApiHeaders.java"
# Redis 세션(쿠키) 모드의 CSRF 헤더 기본 이름.
- name: X-XSRF-TOKEN
direction: inbound
type: string
required: false
generated_if_missing: false
mdc_key: null
envelope_meta_field: null
owner_branch: web-platform
case_style: kebab
compatibility_impact: none
required_test: contract-verification:envelope-headers
source: "src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/settings/SecuritySettings.java"
# === 파일 서버 업로드·다운로드 (composition:fileserver-platform을 켤 때) ===
# Range·If-Range·Content-Range·Accept-Ranges·Content-Disposition·Last-Modified·If-Modified-Since·If-Unmodified-Since는
# HTTP 표준 헤더를 Spring HttpHeaders 상수로 쓴다(MvcDownloadResponseWriter, MvcConditionalRequestFactory). 아래는 이 플랫폼이
# 이름을 정한 헤더다.
- name: Tus-Resumable
direction: both
type: string
required: false
generated_if_missing: false
mdc_key: null
envelope_meta_field: null
owner_branch: fileserver-platform
case_style: kebab
compatibility_impact: none
required_test: contract-verification:envelope-headers
source: "src/adapter/inbound/web-fileserver/src/main/java/dev/caskeleton/adapter/inbound/web/fileserver/tus/TusHeaders.java"
- name: Tus-Version
direction: outbound
type: string
required: false
generated_if_missing: false
mdc_key: null
envelope_meta_field: null
owner_branch: fileserver-platform
case_style: kebab
compatibility_impact: none
required_test: contract-verification:envelope-headers
source: "src/adapter/inbound/web-fileserver/src/main/java/dev/caskeleton/adapter/inbound/web/fileserver/tus/TusHeaders.java"
- name: Tus-Extension
direction: outbound
type: string
required: false
generated_if_missing: false
mdc_key: null
envelope_meta_field: null
owner_branch: fileserver-platform
case_style: kebab
compatibility_impact: none
required_test: contract-verification:envelope-headers
source: "src/adapter/inbound/web-fileserver/src/main/java/dev/caskeleton/adapter/inbound/web/fileserver/tus/TusHeaders.java"
- name: Tus-Max-Size
direction: outbound
type: string
required: false
generated_if_missing: false
mdc_key: null
envelope_meta_field: null
owner_branch: fileserver-platform
case_style: kebab
compatibility_impact: none
required_test: contract-verification:envelope-headers
source: "src/adapter/inbound/web-fileserver/src/main/java/dev/caskeleton/adapter/inbound/web/fileserver/tus/TusHeaders.java"
- name: Upload-Defer-Length
direction: inbound
type: string
required: false
generated_if_missing: false
mdc_key: null
envelope_meta_field: null
owner_branch: fileserver-platform
case_style: kebab
compatibility_impact: none
required_test: contract-verification:envelope-headers
source: "src/adapter/inbound/web-fileserver/src/main/java/dev/caskeleton/adapter/inbound/web/fileserver/tus/TusHeaders.java"
- name: Upload-Metadata
direction: inbound
type: string
required: false
generated_if_missing: false
mdc_key: null
envelope_meta_field: null
owner_branch: fileserver-platform
case_style: kebab
compatibility_impact: none
required_test: contract-verification:envelope-headers
source: "src/adapter/inbound/web-fileserver/src/main/java/dev/caskeleton/adapter/inbound/web/fileserver/tus/TusHeaders.java"
- name: Upload-Expires
direction: outbound
type: string
required: false
generated_if_missing: false
mdc_key: null
envelope_meta_field: null
owner_branch: fileserver-platform
case_style: kebab
compatibility_impact: none
required_test: contract-verification:envelope-headers
source: "src/adapter/inbound/web-fileserver/src/main/java/dev/caskeleton/adapter/inbound/web/fileserver/tus/TusHeaders.java"
- name: Upload-Checksum
direction: inbound
type: string
required: false
generated_if_missing: false
mdc_key: null
envelope_meta_field: null
owner_branch: fileserver-platform
case_style: kebab
compatibility_impact: none
required_test: contract-verification:envelope-headers
source: "src/adapter/inbound/web-fileserver/src/main/java/dev/caskeleton/adapter/inbound/web/fileserver/tus/TusHeaders.java"
- name: Upload-Offset
direction: both
type: string
required: false
generated_if_missing: false
mdc_key: null
envelope_meta_field: null
owner_branch: fileserver-platform
case_style: kebab
compatibility_impact: none
required_test: contract-verification:envelope-headers
source: "src/adapter/inbound/web-fileserver/src/main/java/dev/caskeleton/adapter/inbound/web/fileserver/draft12/Draft12Headers.java"
- name: Upload-Length
direction: both
type: string
required: false
generated_if_missing: false
mdc_key: null
envelope_meta_field: null
owner_branch: fileserver-platform
case_style: kebab
compatibility_impact: none
required_test: contract-verification:envelope-headers
source: "src/adapter/inbound/web-fileserver/src/main/java/dev/caskeleton/adapter/inbound/web/fileserver/draft12/Draft12Headers.java"
- name: Upload-Complete
direction: both
type: string
required: false
generated_if_missing: false
mdc_key: null
envelope_meta_field: null
owner_branch: fileserver-platform
case_style: kebab
compatibility_impact: none
required_test: contract-verification:envelope-headers
source: "src/adapter/inbound/web-fileserver/src/main/java/dev/caskeleton/adapter/inbound/web/fileserver/draft12/Draft12Headers.java"
- name: Upload-Limit
direction: outbound
type: string
required: false
generated_if_missing: false
mdc_key: null
envelope_meta_field: null
owner_branch: fileserver-platform
case_style: kebab
compatibility_impact: none
required_test: contract-verification:envelope-headers
source: "src/adapter/inbound/web-fileserver/src/main/java/dev/caskeleton/adapter/inbound/web/fileserver/draft12/Draft12Headers.java"
# raw·draft-12 업로드의 원래 파일 이름.
- name: X-Filename
direction: inbound
type: string
required: false
generated_if_missing: false
mdc_key: null
envelope_meta_field: null
owner_branch: fileserver-platform
case_style: kebab
compatibility_impact: none
required_test: contract-verification:envelope-headers
source: "src/adapter/inbound/web-fileserver/src/main/java/dev/caskeleton/adapter/inbound/web/fileserver/draft12/Draft12UploadController.java"
- name: X-Content-Sha256
direction: inbound
type: string
required: false
generated_if_missing: false
mdc_key: null
envelope_meta_field: null
owner_branch: fileserver-platform
case_style: kebab
compatibility_impact: none
required_test: contract-verification:envelope-headers
source: "src/adapter/inbound/web-fileserver/src/main/java/dev/caskeleton/adapter/inbound/web/fileserver/mapper/RawUploadRequestMapper.java"
# 앞단 nginx에만 주는 내부 헤더다. nginx가 지우고 client에는 가지 않는다.
- name: X-Accel-Redirect
direction: outbound
type: uri
required: false
generated_if_missing: false
mdc_key: null
envelope_meta_field: null
owner_branch: fileserver-platform
case_style: kebab
compatibility_impact: none
required_test: contract-verification:envelope-headers
source: "src/adapter/inbound/web-fileserver/src/main/java/dev/caskeleton/adapter/inbound/web/fileserver/nginx/NginxDownloadStrategy.java"
+30 -220
View File
@@ -1,23 +1,38 @@
# Registry: MDC / Log Keys
# Schema owner: feature-contract-registry-governance
# MDC SSOT: feature-operational-error-observability-foundation
# Last updated: 2026-05-22
# Last updated: 2026-11-13
#
# 표기 규칙
# - MDC key 이름: snake_case (foundation L93 "snake_case 강제. camelCase / dot.case 금지.")
# - cardinality_safe_for_metric=true 인 key만 metric tag로 사용 가능
# - foundation L93-102 표 "MDC Key Standard (final)"의 key들이 핵심 정본이다
# - 행은 코드가 실제로 MDC에 넣는 key다. 코드의 정본은 `MdcKeys`(shared-contract)이고, 이 파일의 key 집합과
# `MdcKeys` 상수 집합이 같은지 `StructuredLogFieldContractTest`가 본다. `written_by`가 넣는 곳이다.
# - 구조화 로그 칸(`error.code`, `capability`, `operation`, `warning.kind` 등, dot.case 포함)은 MDC key가 아니라
# logstash `kv(...)` 인자다. 그 칸의 정본은 `docs/observability/log-fields.md`다. method·status·duration_ms·uri_template은
# 요청 로그 줄의 메시지 글자다(`RequestLoggingFilter`).
#
# 전송마다 넣는 key (전송마다 다르다. 같게 맞추지 않고 여기 적는다)
# | 전송 | request_id | correlation_id | trace_id·span_id |
# | --- | --- | --- | --- |
# | web(`WebMvcRequestIdFilter`) | 새 UUID. `app.web.mvc.trust-inbound-request-id=true`일 때만 caller의 `X-Request-Id`(`[A-Za-z0-9._-]{1,128}`) | caller의 `X-Correlation-Id`(같은 문법), 없거나 틀리면 새 UUID | 활성 span, 없으면 caller `traceparent`, 없으면 새로 만든다 |
# | gRPC(`GrpcCorrelationInterceptor`) | 호출마다 새 UUID(caller 값을 받지 않는다) | 넣지 않는다(연결·세션 개념이 없다) | 유효한 `traceparent` metadata가 있을 때만 |
# | STOMP(`WebSocketCorrelationInterceptor`) | frame마다 새 UUID | STOMP session id(한 연결의 frame을 잇는다) | 넣지 않는다 |
# | GraphQL(HTTP) | web filter가 넣은 값을 그대로 쓴다 | 같음 | 같음 |
# - user_principal은 web 요청 로그 줄을 쓰는 동안만 있다(HMAC 가명). 비동기 작업은 `AsyncContextTaskDecorator`가
# 호출한 쪽 MDC 전체를 옮긴다.
mdc_keys:
# source: feature-operational-error-observability-foundation.md L97
# "request_id | inbound filter (생성 또는 X-Request-Id 헤더) | response header X-Request-Id"
- key: request_id
type: ulid
type: uuid-or-caller-token
format: "UUID; web은 trust-inbound-request-id=true일 때 [A-Za-z0-9._-]{1,128}"
source: inbound_filter
written_by: [WebMvcRequestIdFilter, GrpcCorrelationInterceptor, WebSocketCorrelationInterceptor]
required_in: [request, dependency, security, application]
http_header_mapping: X-Request-Id
envelope_field: meta.requestId
propagation: [http, async, message]
propagation: [http, async]
owner_branch: feature-operational-error-observability-foundation
cardinality_safe_for_metric: false
case_style: snake
@@ -25,26 +40,26 @@ mdc_keys:
required_test: contract-verification:log-mdc-keys
# source: feature-operational-error-observability-foundation.md L98
# "trace_id | Micrometer Tracing | W3C traceparent header"
- key: trace_id
type: string
format: "W3C trace-id, 32 lowercase hex"
source: observation_context
written_by: [WebMvcRequestIdFilter, GrpcCorrelationInterceptor]
required_in: [request, dependency, application]
http_header_mapping: traceparent
envelope_field: meta.traceId
propagation: [http, async, message]
propagation: [http, async]
owner_branch: feature-operational-error-observability-foundation
cardinality_safe_for_metric: false
case_style: snake
compatibility_impact: none
required_test: contract-verification:log-mdc-keys
# source: feature-operational-error-observability-foundation.md L99
# "span_id | Micrometer Tracing | W3C traceparent"
# NOTE: background-job-async-contract L71 "span_id는 Micrometer Observation context에서 자동 전파(MDC explicit copy 불필요)"
- key: span_id
type: string
format: "W3C parent-id, 16 lowercase hex"
source: observation_context
written_by: [WebMvcRequestIdFilter, GrpcCorrelationInterceptor]
required_in: [request, dependency]
http_header_mapping: traceparent
envelope_field: null
@@ -56,10 +71,11 @@ mdc_keys:
required_test: contract-verification:log-mdc-keys
# source: feature-operational-error-observability-foundation.md L100
# "correlation_id | inbound header X-Correlation-Id 또는 생성 | HTTP X-Correlation-Id, message header correlation_id"
- key: correlation_id
type: ulid
type: uuid-or-caller-token
format: "web: caller X-Correlation-Id [A-Za-z0-9._-]{1,128} 또는 UUID; STOMP: session id"
source: inbound_filter
written_by: [WebMvcRequestIdFilter, WebSocketCorrelationInterceptor]
required_in: [request, dependency, application]
http_header_mapping: X-Correlation-Id
envelope_field: meta.correlationId
@@ -70,28 +86,12 @@ mdc_keys:
compatibility_impact: none
required_test: contract-verification:log-mdc-keys
# source: feature-operational-error-observability-foundation.md L101 + feature-tenant-context-policy.md L70
# "tenant_id | tenant context (활성 시) | downstream HTTP X-Tenant-Id (with allowlist)" /
# "tenant ID format = opaque ULID (26 chars Crockford base32)"
# NOTE: tenant L73 "tenant_id ULID 원본은 metric tag에 직접 사용 금지"
- key: tenant_id
type: ulid
source: security_context
required_in: [request, dependency, security, audit]
http_header_mapping: X-Tenant-Id
envelope_field: null
propagation: [http, async, message]
owner_branch: feature-tenant-context-policy
cardinality_safe_for_metric: false
case_style: snake
compatibility_impact: additive
required_test: contract-verification:tenant-leakage
# source: feature-operational-error-observability-foundation.md L102
# "user_principal | security context (pseudonymized only) | log only, headers forbidden"
- key: user_principal
type: string
format: "HMAC 가명(PrivacySettings)"
source: security_context
written_by: [RequestLoggingFilter]
required_in: [security, audit]
http_header_mapping: null
envelope_field: null
@@ -101,193 +101,3 @@ mdc_keys:
case_style: snake
compatibility_impact: none
required_test: contract-verification:log-mdc-keys
# ── 로그 종류별 확장 (log-management-contract L101-109 "Log Type별 필수 필드") ──
# source: feature-log-management-contract.md L105 "request | request_id, trace_id, method, uri_template, status, duration_ms"
# 참고: application-port-usecase-contract / 업무 쪽 operation 식별자 (uri_template과 따로 application이 정한다)
- key: operation
type: string
source: application_set
required_in: [application, dependency]
http_header_mapping: null
envelope_field: null
propagation: [none]
owner_branch: feature-log-management-contract
cardinality_safe_for_metric: true
case_style: snake
compatibility_impact: none
required_test: contract-verification:log-fields
# source: feature-log-management-contract.md L105 "request | request_id, trace_id, method, uri_template, status, duration_ms"
- key: method
type: string
source: inbound_filter
required_in: [request]
http_header_mapping: null
envelope_field: null
propagation: [none]
owner_branch: feature-log-management-contract
cardinality_safe_for_metric: true
case_style: snake
compatibility_impact: none
required_test: contract-verification:log-fields
# source: feature-log-management-contract.md L105 "request | request_id, trace_id, method, uri_template, status, duration_ms"
# 참고: metrics L86 "status_code | 7 (1xx-5xx + ok/other)" — 값 개수가 정해져 있다
- key: status
type: numeric
source: inbound_filter
required_in: [request]
http_header_mapping: null
envelope_field: null
propagation: [none]
owner_branch: feature-log-management-contract
cardinality_safe_for_metric: true
case_style: snake
compatibility_impact: none
required_test: contract-verification:log-fields
# source: feature-log-management-contract.md L105-106 "request | ... duration_ms" / "dependency | ... duration_ms"
- key: duration_ms
type: numeric
source: application_set
required_in: [request, dependency]
http_header_mapping: null
envelope_field: null
propagation: [none]
owner_branch: feature-log-management-contract
cardinality_safe_for_metric: false
case_style: snake
compatibility_impact: none
required_test: contract-verification:log-fields
# source: feature-log-management-contract.md L106 "dependency | dependency_name, dependency_type, duration_ms, outcome, error_code"
# 참고: metrics L88 "dependency_name | 50" — 값 개수가 정해져 있다
- key: dependency_name
type: string
source: application_set
required_in: [dependency]
http_header_mapping: null
envelope_field: null
propagation: [none]
owner_branch: feature-log-management-contract
cardinality_safe_for_metric: true
case_style: snake
compatibility_impact: none
required_test: contract-verification:log-fields
# source: feature-log-management-contract.md L106 "dependency | dependency_name, dependency_type, ..."
- key: dependency_type
type: string
source: application_set
required_in: [dependency]
http_header_mapping: null
envelope_field: null
propagation: [none]
owner_branch: feature-log-management-contract
cardinality_safe_for_metric: true
case_style: snake
compatibility_impact: none
required_test: contract-verification:log-fields
# source: feature-log-management-contract.md L106 + metrics L91 "outcome (resilience4j) | 5 (SUCCESS/FAILURE/CIRCUIT_OPEN/TIMEOUT/REJECTED)"
- key: outcome
type: string
source: application_set
required_in: [dependency]
http_header_mapping: null
envelope_field: null
propagation: [none]
owner_branch: feature-log-management-contract
cardinality_safe_for_metric: true
case_style: snake
compatibility_impact: none
required_test: contract-verification:log-fields
# source: feature-log-management-contract.md L106 "dependency | ... error_code (실패 시)"
# 참고: metrics L89 "error_code | 100 — error registry row 상한과 정합" — 값 개수가 정해져 있다
- key: error_code
type: string
source: application_set
required_in: [dependency]
http_header_mapping: null
envelope_field: null
propagation: [none]
owner_branch: feature-log-management-contract
cardinality_safe_for_metric: true
case_style: snake
compatibility_impact: none
required_test: contract-verification:log-fields
# source: feature-log-management-contract.md L107
# "security | event_type, user_principal (pseudonymized), source_ip (anonymized — last octet zeroed)"
- key: event_type
type: string
source: application_set
required_in: [security, audit]
http_header_mapping: null
envelope_field: null
propagation: [none]
owner_branch: feature-log-management-contract
cardinality_safe_for_metric: true
case_style: snake
compatibility_impact: none
required_test: contract-verification:log-fields
# source: feature-log-management-contract.md L107 "security | ... source_ip (anonymized — last octet zeroed)"
# NOTE: metrics L93 "high-cardinality 금지 tag: ... ip_address"
- key: source_ip_anon
type: string
source: inbound_filter
required_in: [security]
http_header_mapping: null
envelope_field: null
propagation: [none]
owner_branch: feature-log-management-contract
cardinality_safe_for_metric: false
case_style: snake
compatibility_impact: none
required_test: contract-verification:log-fields
# source: feature-log-management-contract.md L108 "audit | actor, action, target, before_hash, after_hash, occurred_at"
- key: actor
type: string
source: security_context
required_in: [audit]
http_header_mapping: null
envelope_field: null
propagation: [none]
owner_branch: feature-log-management-contract
cardinality_safe_for_metric: false
case_style: snake
compatibility_impact: none
required_test: contract-verification:log-fields
# source: feature-log-management-contract.md L108 "audit | actor, action, target, ..."
- key: action
type: string
source: application_set
required_in: [audit]
http_header_mapping: null
envelope_field: null
propagation: [none]
owner_branch: feature-log-management-contract
cardinality_safe_for_metric: true
case_style: snake
compatibility_impact: none
required_test: contract-verification:log-fields
# source: feature-log-management-contract.md L108 "audit | actor, action, target, ..."
- key: target
type: string
source: application_set
required_in: [audit]
http_header_mapping: null
envelope_field: null
propagation: [none]
owner_branch: feature-log-management-contract
cardinality_safe_for_metric: false
case_style: snake
compatibility_impact: none
required_test: contract-verification:log-fields
+1150 -265
View File
File diff suppressed because it is too large Load Diff
+35 -74
View File
@@ -15,9 +15,14 @@
# RR-07-04). 비밀값만 본다: 이 파일의 `secret` 행(SecretSourceValidator.CLASSIFIED_SECRETS,
# SecretsClassificationRegistryTest가 1:1로 묶음), 모듈이 기여한 비밀, `secret://…/<VAR>` 참조가
# 가리키는 변수. HOSTNAME·앱 이름 같은 비밀이 아닌 값은 보지 않는다 (review 2026-11-04 RR2-04-01).
# - 가림(masking) 기본 = `full_except_last_4` (feature-secrets-config-source-contract 2026-05-22:
# "full mask except last 4 chars for non-secret tokens" — 비밀이 아닌 토큰은 끝 4자만 남기고 가린다).
# 진짜 secret(password/private key)은 `full`.
# - `masking_rule`은 그 값이 로그에 나타났을 때 Layer 1 가림(`LogMaskingPatterns`, JSON·pattern 로그 공통)이
# 하는 일이다. 값 셋만 쓴다(`SecretsClassificationRegistryTest`가 묶음):
# full — 값 전체. 비밀 이름(password·secret·token·api key 등)의 key=value와 Authorization 값을 가린다.
# 한 줄 값은 다음 공백·따옴표·구분자까지, PEM 블록은 여러 줄이어도 BEGIN~END 사이 전체다.
# 진짜 secret(password/private key/HMAC key)은 이것이다.
# userinfo — URI의 사용자 정보 비밀번호(`scheme://user:****@host`). 접속 URI 행이다.
# none — 가리지 않는다.
# - `required_test`는 그 행의 약속을 지키는 app-bootstrap 시험 클래스 이름이다(같은 시험이 클래스가 있는지 본다).
# - 이름 접미사는 보조 신호다 (feature-secrets-config-source-contract: "_TOKEN, _KEY, _PASSWORD").
# - public-config 항목은 env-keys.yaml에서 직접 정의되며 본 파일에는 reference row만 둠.
@@ -39,7 +44,7 @@ secrets:
owner_branch: feature-secrets-config-source-contract
masking_rule: full
compatibility_impact: breaking
required_test: secrets-contract:db-password-no-leak-in-actuator
required_test: SecretSourceValidatorTest
- name: SPRING_MAIL_PASSWORD
# source: notification/fileserver techlead review H2 — Spring Mail이 직접 읽는 자격 증명이라 APP_* 별칭을 두지
@@ -53,7 +58,7 @@ secrets:
owner_branch: 2026-09-21-notification-review-remediation
masking_rule: full
compatibility_impact: additive
required_test: secrets-contract:smtp-password-no-leak
required_test: SecretSourceValidatorTest
- name: APP_CACHE_REDIS_PASSWORD
# source: feature-secrets-config-source-contract 2026-05-22
@@ -69,7 +74,7 @@ secrets:
owner_branch: feature-secrets-config-source-contract
masking_rule: full
compatibility_impact: breaking
required_test: secrets-contract:redis-password-no-leak
required_test: SecretSourceValidatorTest
- name: APP_CACHE_REDIS_TRUST_PEM
# 공개 CA bundle 내용이지만 무결성이 중요하고, 마운트된 환경이 준다.
@@ -81,7 +86,7 @@ secrets:
owner_branch: redis-production-capability
masking_rule: full
compatibility_impact: additive
required_test: secrets-contract:redis-trust-reference-no-leak
required_test: SecretsClassificationRegistryTest
- name: APP_CACHE_REDIS_KEY_HMAC_SECRET
# 바뀌지 않는 캐시 key HMAC 자료. Redis 인증 자격 증명과 다르다.
@@ -95,7 +100,7 @@ secrets:
owner_branch: codex-phase-a-ci-recovery
masking_rule: full
compatibility_impact: breaking
required_test: secrets-contract:redis-key-hmac-no-leak
required_test: SecretSourceValidatorTest
- name: APP_RATE_LIMIT_REDIS_PASSWORD
# coordination role 전용 Redis 자격 증명. 캐시 Redis에서 물려받지 않는다.
@@ -109,7 +114,7 @@ secrets:
owner_branch: redis-distributed-rate-limit
masking_rule: full
compatibility_impact: additive
required_test: secrets-contract:rate-limit-redis-password-no-leak
required_test: SecretSourceValidatorTest
- name: APP_RATE_LIMIT_REDIS_TRUST_PEM
# coordination role CA bundle 내용. 무결성이 중요하지만 자격 증명 자료는 아니다.
@@ -121,7 +126,7 @@ secrets:
owner_branch: redis-production-capability
masking_rule: full
compatibility_impact: additive
required_test: secrets-contract:rate-limit-redis-trust-reference-no-leak
required_test: SecretsClassificationRegistryTest
- name: APP_RATE_LIMIT_REDIS_KEY_HMAC_SECRET
# rate-limit 대상과 정책 개정에 쓰는, 바뀌지 않는 비공개 key 파생 자료.
@@ -135,7 +140,7 @@ secrets:
owner_branch: redis-distributed-rate-limit
masking_rule: full
compatibility_impact: additive
required_test: secrets-contract:rate-limit-redis-key-hmac-no-leak
required_test: SecretSourceValidatorTest
- name: APP_SESSION_REDIS_PASSWORD
# session role 전용 ACL 자격 증명. 캐시나 coordination과 몰래 함께 쓰지 않는다.
@@ -149,7 +154,7 @@ secrets:
owner_branch: redis-production-capability
masking_rule: full
compatibility_impact: additive
required_test: secrets-contract:session-redis-password-no-leak
required_test: SecretSourceValidatorTest
- name: APP_SESSION_REDIS_TRUST_PEM
# session role CA bundle 내용. 무결성이 중요하지만 자격 증명 자료는 아니다.
@@ -161,7 +166,7 @@ secrets:
owner_branch: redis-production-capability
masking_rule: full
compatibility_impact: additive
required_test: secrets-contract:session-redis-trust-reference-no-leak
required_test: SecretsClassificationRegistryTest
- name: APP_SESSION_REDIS_KEY_HMAC_SECRET
# 가명 Redis session key에 쓰는, 바뀌지 않는 비공개 파생 자료.
@@ -175,7 +180,7 @@ secrets:
owner_branch: redis-production-capability
masking_rule: full
compatibility_impact: additive
required_test: secrets-contract:session-redis-key-hmac-no-leak
required_test: SecretSourceValidatorTest
- name: APP_IDEMPOTENCY_REDIS_KEY_HMAC_SECRET
# owner-safe 요청 replay key가 tenant·scope·요청 식별자를 드러내면 안 된다.
@@ -189,7 +194,7 @@ secrets:
owner_branch: redis-production-capability-completion
masking_rule: full
compatibility_impact: additive
required_test: secrets-contract:idempotency-redis-key-hmac-no-leak
required_test: SecretSourceValidatorTest
- name: APP_LEASE_REDIS_KEY_HMAC_SECRET
# 효율 lease의 자원·소유자 scope는 전용 파생 key를 쓴다.
@@ -203,7 +208,7 @@ secrets:
owner_branch: redis-production-capability-completion
masking_rule: full
compatibility_impact: additive
required_test: secrets-contract:lease-redis-key-hmac-no-leak
required_test: SecretSourceValidatorTest
- name: APP_PRIVACY_PSEUDONYMIZATION_SALT
# source: feature-data-retention-privacy-contract 2026-05-22
@@ -218,7 +223,7 @@ secrets:
owner_branch: feature-data-retention-privacy-contract
masking_rule: full
compatibility_impact: breaking
required_test: secrets-contract:pseudonymization-salt-rotation
required_test: SecretSourceValidatorTest
# === 2등급: sensitive-config (토큰이 든 URL이나 노출을 제한할 id) ===
@@ -235,7 +240,7 @@ secrets:
owner_branch: worktree-notification-platform
masking_rule: full
compatibility_impact: behavior-change
required_test: secrets-contract:notification-contact-encryption-no-leak
required_test: SecretSourceValidatorTest
- name: APP_NOTIFICATION_PLATFORM_CONTACT_LOOKUP_HMAC_KEY
# 연락처의 blind index. 조회에 평문이 필요 없게 한다.
@@ -250,7 +255,7 @@ secrets:
owner_branch: worktree-notification-platform
masking_rule: full
compatibility_impact: behavior-change
required_test: secrets-contract:notification-contact-lookup-hmac-no-leak
required_test: SecretSourceValidatorTest
- name: APP_NOTIFICATION_PLATFORM_CALLBACK_SIGNING_KEY
# provider가 전달 결과를 보내는 callback URL에 서명한다.
@@ -265,7 +270,7 @@ secrets:
owner_branch: worktree-notification-platform
masking_rule: full
compatibility_impact: behavior-change
required_test: secrets-contract:notification-callback-signing-no-leak
required_test: SecretSourceValidatorTest
- name: APP_NOTIFICATION_PLATFORM_PROVIDER_CREDENTIAL_KEY
# 저장된 provider 자격 증명(그 자체가 비밀)을 암호화한다.
@@ -280,7 +285,7 @@ secrets:
owner_branch: worktree-notification-platform
masking_rule: full
compatibility_impact: behavior-change
required_test: secrets-contract:notification-provider-credential-no-leak
required_test: SecretSourceValidatorTest
- name: APP_NOTIFICATION_PLATFORM_PAYLOAD_ENCRYPTION_KEY
# 저장된 알림 변수와 보관한 callback 본문을 암호화한다.
@@ -295,7 +300,7 @@ secrets:
owner_branch: worktree-notification-platform
masking_rule: full
compatibility_impact: behavior-change
required_test: secrets-contract:notification-payload-encryption-no-leak
required_test: SecretSourceValidatorTest
- name: APP_NOTIFICATION_PLATFORM_PROVIDER_REQUEST_LOOKUP_HMAC_KEY
# provider 쪽 식별자인 provider request id의 key 있는 hash.
@@ -310,7 +315,7 @@ secrets:
owner_branch: worktree-notification-platform
masking_rule: full
compatibility_impact: behavior-change
required_test: secrets-contract:notification-provider-request-lookup-hmac-no-leak
required_test: SecretSourceValidatorTest
- name: APP_NOTIFICATION_PLATFORM_CALLBACK_FINGERPRINT_HMAC_KEY
# callback 본문의 key 있는 fingerprint. replay를 찾는 데 쓴다.
@@ -325,35 +330,7 @@ secrets:
owner_branch: worktree-notification-platform
masking_rule: full
compatibility_impact: behavior-change
required_test: secrets-contract:notification-callback-fingerprint-hmac-no-leak
- name: APP_NOTIFICATION_SLACK_WEBHOOK_URL
# source: feature-integration-adapter-templates 2026-05-22
# "Slack | disabled optional module | notification failure policy"
# Slack webhook URL은 token을 path에 포함하므로 sensitive-config (URL 형태이지만 secret과 동급 취급)
classification: sensitive-config
source: secret-manager
rotation_policy: manual
prod_default: null
dev_sentinel_prefix: __LOCAL_DEV_
owner_branch: feature-secrets-config-source-contract
masking_rule: full_except_last_4
compatibility_impact: breaking
required_test: secrets-contract:slack-webhook-no-leak
- name: APP_SECURITY_GOOGLE_OAUTH_CLIENT_ID
# source: feature-secrets-config-source-contract 2026-05-22
# "sensitive-config" 등급 (id이지만 노출 제한)
# + feature-integration-adapter-templates "Google Email | disabled optional module"
classification: sensitive-config
source: mounted-env
rotation_policy: manual
prod_default: null
dev_sentinel_prefix: __LOCAL_DEV_
owner_branch: feature-secrets-config-source-contract
masking_rule: full_except_last_4
compatibility_impact: behavior-change
required_test: secrets-contract:google-oauth-client-id-masked
required_test: SecretSourceValidatorTest
- name: APP_DATASOURCE_USERNAME
# source: feature-secrets-config-source-contract 2026-05-22 — "sensitive-config" 등급
@@ -364,9 +341,9 @@ secrets:
prod_default: null
dev_sentinel_prefix: __LOCAL_DEV_
owner_branch: feature-secrets-config-source-contract
masking_rule: full_except_last_4
masking_rule: none
compatibility_impact: breaking
required_test: secrets-contract:datasource-username-masked-in-actuator
required_test: SecretsClassificationRegistryTest
- name: SPRING_MONGODB_URI
# MongoDB URI에는 사용자 이름·비밀번호가 들어 있을 수 있어 public config로 로그에 남기면 안 된다.
@@ -377,9 +354,9 @@ secrets:
prod_default: null
dev_sentinel_prefix: __LOCAL_DEV_
owner_branch: persistence-mongo-runtime-remediation
masking_rule: full_except_last_4
masking_rule: userinfo
compatibility_impact: additive
required_test: secrets-contract:mongodb-uri-masked
required_test: LogMaskingPatternsTest
- name: APP_DATASOURCE_URL
# source: feature-secrets-config-source-contract 2026-05-22 — JDBC URL은 host/db 포함하므로 sensitive-config
@@ -390,20 +367,12 @@ secrets:
prod_default: null
dev_sentinel_prefix: __LOCAL_DEV_
owner_branch: feature-secrets-config-source-contract
masking_rule: full_except_last_4
masking_rule: userinfo
compatibility_impact: breaking
required_test: secrets-contract:datasource-url-masked-in-actuator
required_test: LogMaskingPatternsTest
# === 1등급: public-config (참조만 — 행 전체는 env-keys.yaml에 있다) ===
- name: APP_PROFILE
# source: feature-env-driven-runtime-configuration — public-config 등급 참조
classification: public-config
source: application-yml
owner_branch: feature-env-driven-runtime-configuration
masking_rule: none
reference: env-keys.yaml#APP_PROFILE
- name: APP_NAME
# source: feature-env-driven-runtime-configuration — public-config 등급 참조
classification: public-config
@@ -412,14 +381,6 @@ secrets:
masking_rule: none
reference: env-keys.yaml#APP_NAME
- name: SERVER_PORT
# source: feature-env-driven-runtime-configuration — Spring 자체 키, public-config 등급 참조
classification: public-config
source: application-yml
owner_branch: feature-env-driven-runtime-configuration
masking_rule: none
reference: env-keys.yaml#SERVER_PORT
- name: SPRING_PROFILES_ACTIVE
# source: feature-env-driven-runtime-configuration — Spring 자체 키, public-config 등급 참조
classification: public-config
+3 -4
View File
@@ -25,11 +25,10 @@ status: 초안
## 진단
1. 경합 비율. `APP_MULTI_INSTANCE_ENABLED=true`이면 JDBC 락에 메트릭이 붙는다.
1. 경합 비율. 프로세스 안 락(`APP_MULTI_INSTANCE_ENABLED=false`, 기본값)과 JDBC 락 모두 메트릭이 붙는다.
`lock.acquisition{outcome="timeout"}`을 `lock.acquisition{outcome="acquired"}`와 비교한다. 이 counter에는
락 이름도 대기 시간도 없다. 키는 메트릭 태그가 되지 않는다(`docs/registries/metrics.yaml`). 프로세스 안 락
(`APP_MULTI_INSTANCE_ENABLED=false`, 기본값)은 메트릭이 없고 DB에 아무것도 남기지 않는다. 아래 단계는 JDBC
락에만 해당한다.
락 이름도 대기 시간도 없다. 키는 메트릭 태그가 되지 않는다(`docs/registries/metrics.yaml`). 프로세스 안 락은
DB에 아무것도 남기지 않는다. 아래 단계는 JDBC 락에만 해당한다.
2. 지금 누가 락을 쥐고 있나. `INT_LOCK`에는 쥔 락마다 한 행이 있다. `CLIENT_ID`는 쥔 인스턴스의 락 저장소 id이고,
시각은 UTC다. `EXPIRED_AFTER`가 지난 행은 죽은 lease다. 그 키를 다음에 잡는 쪽이 넘겨받는다. 가장 오래된
살아 있는 행이 오래 쥔 쪽이다.
+1 -1
View File
@@ -15,7 +15,7 @@ redis 기반 limiter를 쓸 수 있다(fail-closed):
1. 모듈을 런타임에 둔다: `runtimeOnly project(':adapter:outbound:cache-redis')`.
2. `APP_REDIS_ENABLED=true` + redis 접속(`APP_*_REDIS_*`).
3. `APP_RATE_LIMIT_ENABLED=true`, `APP_RATE_LIMIT_PROVIDER=redis`, `APP_RATE_LIMIT_FAILURE_POLICY=fail-closed`.
4. 클라이언트 IP 해석: 운영 정본은 `APP_SERVER_FORWARD_HEADERS_STRATEGY=native` + Tomcat `remoteip.internal-proxies`로 `getRemoteAddr()` 하나를 쓴다. `APP_RATE_LIMIT_CLIENT_IP_MODE`의 XFF-왼쪽 모드는 호출자가 위조할 수 있으니 신뢰 프록시 체인이 설 때만 쓴다(docs/capability-status.md, I-5a·NEW-10c).
4. 클라이언트 IP 해석: `APP_SERVER_FORWARD_HEADERS_STRATEGY=native` + Tomcat `server.tomcat.remoteip.internal-proxies`(신뢰하는 프록시의 IP 정규식)로 `getRemoteAddr()` 하나를 쓴다. limiter는 그 값만 읽고 따로 고르는 IP 모드가 없다(옛 `APP_RATE_LIMIT_CLIENT_IP_MODE`는 지웠다, `docs/capability-status.md`). `framework`는 모든 peer의 `X-Forwarded-*`를 믿어 호출자가 자기 IP를 고를 수 있으니 쓰지 않는다(`src/bootstrap/app/src/main/resources/config/server.yml`).
자세한 키는 `docs/registries/env-keys.yaml`의 `APP_RATE_LIMIT_*`, 모듈 기본값은 `src/adapter/outbound/cache-redis/src/main/resources/config/module-defaults/cache-redis.yml`.
@@ -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번 둘 말고 그대로다. 응답 모양도 그대로다.