This commit is contained in:
@@ -43,7 +43,7 @@ paths:
|
||||
## 이 분야에서 실패는 이렇게 보인다
|
||||
|
||||
- [ ] 새 구조화 칸은 `docs/observability/log-fields.md`에, 새 MDC 키는 `docs/registries/mdc-keys.yaml`에, 새 지표는 `docs/registries/metrics.yaml`에 먼저 있다. 헤더와 짝이면 `docs/registries/headers.yaml`도. — 각 파일 머리말
|
||||
- [ ] 지표 이름은 dot.case에 단위 접미사(`.seconds`·`.bytes`·`.total`)이고, tag마다 cardinality 상한이 있다. `error_code` tag는 registry 행 수를 넘지 않는다. — `docs/registries/metrics.yaml`
|
||||
- [ ] 지표 이름은 dot.case이고 단위는 registry 행의 `unit`(`seconds`·`bytes`·`total`)이 말한다. tag마다 cardinality 상한이 있다. `error_code` tag는 registry 행 수를 넘지 않는다. — `docs/registries/metrics.yaml`
|
||||
- [ ] 레벨: 클라이언트 탓 WARN, 서버 탓 ERROR + `ServerFailureLog`, 기동 실패는 `StartupFailures`(`startup.phase`, `error.code`). — A8, `docs/observability/log-fields.md`
|
||||
- [ ] 메시지 문장은 사람용, 칸은 기계용이다. 검색·필터·경보는 칸으로 한다. — `docs/observability/log-fields.md`
|
||||
- [ ] 예외는 원인(cause)을 잃지 않게 감싸되, 메시지에 입력값을 넣지 않는다. — 일반 원칙, A8
|
||||
@@ -58,8 +58,8 @@ paths:
|
||||
|
||||
Gradle은 desktop에서 돈다(`docs/work/operate.md` 4.1절).
|
||||
|
||||
- registry와 코드 대조: app-bootstrap `test`의 `MetricsAlertingContractTest`, `StructuredLogFieldContractTest`, `DistributedTracingContractTest`, `HeaderRegistryRuntimeAlignmentTest`, `RunbookCoverageContractTest`, `OperationalErrorRegistryContractTest` → `scripts/verify.sh leaf :app-bootstrap`
|
||||
- 새어 나감: `SqlLoggingForbiddenContractTest`, `PiiTokenBodyForbiddenContractTest`(같은 leaf), `:adapter:inbound:web:jpaPersistenceRedactionContractTest`(DB 실패가 로그·span에 닿지 않음)
|
||||
- registry 파일을 읽는 대조는 `document-contract` 태그라 `test`에서 빠지고 `:app-bootstrap:documentContractTest`(main 단계)에서 돈다: `HeaderRegistryRuntimeAlignmentTest`, `RunbookCoverageContractTest`, `OperationalErrorRegistryContractTest`, `MetricsRegistryCodeAlignmentTest`(지표 행 ↔ 등록 코드 두 방향), `SecretsClassificationRegistryTest`(가림 규칙이 실제로 가리는지), 그리고 `MetricsAlertingContractTest`·`StructuredLogFieldContractTest`·`DistributedTracingContractTest`의 태그 붙은 메서드. 그 세 클래스의 나머지 메서드는 app-bootstrap `test` → `scripts/verify.sh leaf :app-bootstrap`
|
||||
- 새어 나감: `SqlLoggingForbiddenContractTest`(`repository-contract` → `:app-bootstrap:repositoryContractTest`), `PiiTokenBodyForbiddenContractTest`(app-bootstrap `test`, 그 안의 `requestLoggingHasNoBodyCapturePath`는 `repository-contract`), `:adapter:inbound:web:jpaPersistenceRedactionContractTest`(DB 실패가 로그·span에 닿지 않음)
|
||||
- runtime 배선: `scripts/verify.sh leaf :composition:service-runtime`, span 내보내기는 app-bootstrap `systemTest`의 `TracingExportSystemTest`
|
||||
- runbook 숫자·SQL이 문서와 맞는지: document-contract lane(`:app-bootstrap:documentContractTest`, main 단계)과 runbook SQL을 실 PostgreSQL에서 도는 lane(`:adapter:outbound:persistence-jpa:postgresqlOutboxDispositionRunbookIntegrationTest` 등)
|
||||
|
||||
|
||||
@@ -80,7 +80,7 @@ Gradle·Docker는 desktop에서 돈다(`docs/work/operate.md` 4.1절). 명령은
|
||||
- 공개 경로·보안 체인을 바꿨으면 `./gradlew verifyPublicPathSnapshot`. 스냅숏 갱신은 리뷰 뒤 `-PapprovePublicPathChange`. — `docs/work/reference/gates.md` 2절
|
||||
- JWT·JWKS·CORS 경계: `:adapter:inbound:web:webSecurityBoundaryTest`(skip 거부), 오류 디스패치는 `JwtChainErrorDispatchIT`(web `systemTest`).
|
||||
- 권한 구조: `./gradlew :app-bootstrap:architectureTest`(`ApplicationBoundaryArchitectureTest`, `RequiresPermissionProxyabilityTest`, `ForbiddenApiArchitectureTest`).
|
||||
- 비밀·로그: app-bootstrap `test`의 `SecretsClassificationRegistryTest`, `PiiTokenBodyForbiddenContractTest`, `SqlLoggingForbiddenContractTest`, `ManagementActuatorSecurityContractTest` → `scripts/verify.sh leaf :app-bootstrap`
|
||||
- 비밀·로그: `SecretsClassificationRegistryTest`와 `ManagementActuatorSecurityContractTest`의 registry 메서드(`document-contract` → `:app-bootstrap:documentContractTest`), `SqlLoggingForbiddenContractTest`(`repository-contract` → `:app-bootstrap:repositoryContractTest`), `PiiTokenBodyForbiddenContractTest`의 `requestLoggingHasNoBodyCapturePath`(`repository-contract`), `PiiTokenBodyForbiddenContractTest`·`ManagementActuatorSecurityContractTest`의 나머지(app-bootstrap `test` → `scripts/verify.sh leaf :app-bootstrap`)
|
||||
- DB 역할: `:adapter:outbound:persistence-jpa:postgresqlSecurityBaselineIntegrationTest`, `:adapter:outbound:persistence-jpa:jpaPlatformSecurityTest`
|
||||
- 정적 분석: `qualityCheck`(SpotBugs + FindSecBugs, PR의 `ci` 안).
|
||||
- 취약점: workflow `vulnerabilities` job(`scripts/ci/trivy-scan.sh`). desktop에서는 이미 설치된 trivy로만 돌린다. 없으면 못 돌림으로 적는다. — `docs/work/reference/gates.md` 3절 (다)
|
||||
|
||||
+5
-5
@@ -106,7 +106,7 @@ services:
|
||||
# these; a service that selects the relational capability does.
|
||||
APP_DATASOURCE_URL: "jdbc:postgresql://db:5432/${POSTGRES_DB:-ca_skeleton}"
|
||||
APP_DATASOURCE_USERNAME: "${APP_DATASOURCE_USERNAME:-ca_skeleton}"
|
||||
APP_DATASOURCE_PASSWORD: "${APP_DATASOURCE_PASSWORD:-ca_skeleton}"
|
||||
APP_DATASOURCE_PASSWORD: "${APP_DATASOURCE_PASSWORD:-__LOCAL_DEV_db_password__}"
|
||||
# ---- Read-only root filesystem (D2) -------------------------------------
|
||||
# The application must write only to the tmpfs mount declared below.
|
||||
# /tmp — Tomcat basedir (see -Dserver.tomcat.basedir=/tmp in Dockerfile).
|
||||
@@ -160,7 +160,7 @@ services:
|
||||
environment:
|
||||
POSTGRES_DB: "${POSTGRES_DB:-ca_skeleton}"
|
||||
POSTGRES_USER: "${APP_DATASOURCE_USERNAME:-ca_skeleton}"
|
||||
POSTGRES_PASSWORD: "${APP_DATASOURCE_PASSWORD:-ca_skeleton}"
|
||||
POSTGRES_PASSWORD: "${APP_DATASOURCE_PASSWORD:-__LOCAL_DEV_db_password__}"
|
||||
TZ: "UTC"
|
||||
volumes:
|
||||
- type: volume
|
||||
@@ -339,7 +339,7 @@ services:
|
||||
command: ["server", "/data"]
|
||||
environment:
|
||||
MINIO_ROOT_USER: "${MINIO_ROOT_USER:-caskeleton}"
|
||||
MINIO_ROOT_PASSWORD: "${MINIO_ROOT_PASSWORD:-caskeleton-local}"
|
||||
MINIO_ROOT_PASSWORD: "${MINIO_ROOT_PASSWORD:-__LOCAL_DEV_minio_root__}"
|
||||
volumes:
|
||||
- type: volume
|
||||
source: caskeleton-minio-data
|
||||
@@ -368,7 +368,7 @@ services:
|
||||
environment:
|
||||
MINIO_ENDPOINT: "http://minio:9000"
|
||||
MINIO_ROOT_USER: "${MINIO_ROOT_USER:-caskeleton}"
|
||||
MINIO_ROOT_PASSWORD: "${MINIO_ROOT_PASSWORD:-caskeleton-local}"
|
||||
MINIO_ROOT_PASSWORD: "${MINIO_ROOT_PASSWORD:-__LOCAL_DEV_minio_root__}"
|
||||
MINIO_BUCKET: "${MINIO_BUCKET:-ca-skeleton-objects}"
|
||||
volumes:
|
||||
- type: bind
|
||||
@@ -390,7 +390,7 @@ services:
|
||||
entrypoint: ["/bin/bash", "/opt/keycloak-entrypoint/entrypoint.sh"]
|
||||
environment:
|
||||
KC_BOOTSTRAP_ADMIN_USERNAME: "${KEYCLOAK_ADMIN:-admin}"
|
||||
KC_BOOTSTRAP_ADMIN_PASSWORD: "${KEYCLOAK_ADMIN_PASSWORD:-admin}"
|
||||
KC_BOOTSTRAP_ADMIN_PASSWORD: "${KEYCLOAK_ADMIN_PASSWORD:-__LOCAL_DEV_keycloak_admin__}"
|
||||
KC_HEALTH_ENABLED: "true"
|
||||
volumes:
|
||||
- type: bind
|
||||
|
||||
+2
-1
@@ -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 기본).
|
||||
|
||||
### 분산 추적
|
||||
|
||||
|
||||
@@ -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` | 운영 코드가 부르지 않았다. 요청 로그는 헤더를 싣지 않는다 |
|
||||
|
||||
@@ -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
@@ -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
@@ -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
File diff suppressed because it is too large
Load Diff
@@ -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
|
||||
|
||||
@@ -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다. 그 키를 다음에 잡는 쪽이 넘겨받는다. 가장 오래된
|
||||
살아 있는 행이 오래 쥔 쪽이다.
|
||||
|
||||
@@ -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번 둘 말고 그대로다. 응답 모양도 그대로다.
|
||||
+2
-1
@@ -329,7 +329,8 @@
|
||||
"source_path": "src/bootstrap/outbox-relay",
|
||||
"allowed_dependencies": [
|
||||
"application-core",
|
||||
"adapter-outbound-support"
|
||||
"adapter-outbound-support",
|
||||
"shared-contract"
|
||||
]
|
||||
},
|
||||
{
|
||||
|
||||
@@ -266,7 +266,7 @@ run_lane() {
|
||||
#
|
||||
# The database credentials are additionally *exported*, because two different mechanisms have to
|
||||
# agree on them. The application reads this file; the `db` service takes its POSTGRES_USER and
|
||||
# POSTGRES_PASSWORD from Compose interpolation — `${APP_DATASOURCE_PASSWORD:-ca_skeleton}` — and
|
||||
# POSTGRES_PASSWORD from Compose interpolation — `${APP_DATASOURCE_PASSWORD:-__LOCAL_DEV_db_password__}` — and
|
||||
# interpolation reads the process environment and the project .env file, never a service's
|
||||
# env_file. So the application got the generated password and the database got the literal
|
||||
# default, and no lane whose overlay did not happen to restate the value could ever authenticate.
|
||||
|
||||
+5
-1
@@ -14,7 +14,11 @@ import java.util.function.Supplier;
|
||||
import org.slf4j.MDC;
|
||||
|
||||
/**
|
||||
* Puts a call's correlation on MDC under the same keys the HTTP path uses (review X2-P2-5).
|
||||
* Puts a call's correlation on MDC under the HTTP path's key names (review X2-P2-5) — a subset of
|
||||
* them: {@code request_id}, and {@code trace_id}/{@code span_id} only when the caller sent a {@code
|
||||
* traceparent}. No {@code correlation_id}: a gRPC call has no session to join, and the
|
||||
* per-transport table in {@code docs/registries/mdc-keys.yaml} records that (this line used to say
|
||||
* "the same keys", review 2026-11-12).
|
||||
*
|
||||
* <p>Correlation used to stop at the servlet filter: a log line written while a gRPC call ran
|
||||
* carried no {@code request_id}, so it could not be joined to anything. Each call gets its own
|
||||
|
||||
@@ -490,13 +490,15 @@ commit-aware response wrapper 계약을 구현한다. 또한 이 모듈은 HTML
|
||||
필터는 KEYED 가 아닌 엔드포인트까지 막아 버렸다.
|
||||
|
||||
### ApiHeaders
|
||||
- 인바운드 web 어댑터 전역의 HTTP 헤더명 상수 — `docs/registries/headers.yaml`의
|
||||
코드 미러. 리터럴을 중앙집중해 controller/filter/advice 가 casing 으로 drift 하지 않게 하고, 레지스트리
|
||||
일관성 테스트가 단일 출처를 참조하게 한다.
|
||||
- 소유권: `X-Api-Version`(D2)·`Idempotency-Key`(D3 — 이름만; key shape/scope/replay 정책은
|
||||
application-core 소유)는 여기서 생산. conditional-request(D15)·cache(D16)·method/negotiation/
|
||||
LRO(D12/D17)·pagination(D18)·rate-limit signaling(generated_if_missing=true; Limit/Remaining 은 numeric, Reset 은
|
||||
rfc3339 = fixed-window end)·deep-offset deprecation marker(D18)·always-emitted(D24)는 표준 RFC 9110/9111 이름 참조.
|
||||
- 인바운드 web 어댑터가 쓰는 HTTP 헤더명 상수. 리터럴을 한 곳에 모아 controller/filter/advice 가 casing 으로
|
||||
drift 하지 않게 한다. `docs/registries/headers.yaml` 의 web 행은 이 파일을 `source` 로 가리키고,
|
||||
`HeaderRegistryRuntimeAlignmentTest` 가 그 이름 글자가 이 파일에 있고 그 상수를 쓰는 main 코드가 있는지 본다
|
||||
(`service:` 행은 서비스용 상수라 쓰는 곳을 보지 않는다).
|
||||
- 템플릿 main 이 쓰는 상수: `Retry-After`, rate-limit 신호(`X-RateLimit-Limit`·`-Remaining` 은 숫자, `-Reset` 은
|
||||
rfc3339 = fixed window 끝), `Cache-Control`·`Vary`, `ETag`·`Location`(CORS 노출 목록).
|
||||
- 서비스 controller 가 읽으라고 둔 상수: `Idempotency-Key`(이름만. key shape/scope/replay 정책은 application-core 소유),
|
||||
`If-Match`·`If-None-Match`(조건부 요청, 비교는 `conditional.ETags`), `Allow`. `Deprecation`·`Date` 상수는 있지만 아무
|
||||
코드도 쓰지 않는다. `X-Api-Version` 은 없다.
|
||||
|
||||
---
|
||||
|
||||
@@ -508,20 +510,22 @@ commit-aware response wrapper 계약을 구현한다. 또한 이 모듈은 HTML
|
||||
같은 논리 ID 의 envelope 형태(camelCase)와 HTTP 헤더 형태(kebab-case)는 D19 projection 이며,
|
||||
변환 단일 지점은 `ResponseMetaFactory`.
|
||||
|
||||
### LoggedPath
|
||||
- 서버 로그 줄이 요청을 부르는 경로 하나다. 401·403 보안 줄의 `path=`(`AuthErrorResponseWriter`), 요청 로그 줄의
|
||||
`uri_template=`(`RequestLoggingFilter`), 처리하지 못한 예외 줄(`GlobalExceptionHandler`)이 같이 쓴다.
|
||||
- DispatcherServlet이 handler를 고르면 그 pattern(`/v1/orders/{id}`)이다. 정적 자원 handler가 받은 없는 경로는
|
||||
`/**`다. 그 밖(보안 chain이 dispatch 전에 거부한 요청, 어떤 handler mapping도 받지 않은 요청)은 요청 경로에서
|
||||
값이 들 수 있는 마디를 `{}`로 가린다. 글자·하이픈만인 마디와 API 버전(`v1`)만 남기고, 8마디까지만 쓴다.
|
||||
- 모양으로 가르는 규칙이라 가장자리가 둘이다. 글자만인 값(`/users/alice`)은 남으니 경로에 이름을 넣는 route는 id로
|
||||
바꾼다. 숫자나 점이 든 route 글자(`oauth2`, `.well-known`)는 값처럼 가려진다. handler가 고른 요청은 pattern으로
|
||||
남아 둘 다 해당하지 않는다.
|
||||
|
||||
### MdcCorrelationIdPortAdapter
|
||||
- `WebMvcRequestIdFilter`가 무해화하고 MDC `correlation_id`에 넣은 값을 application-core의
|
||||
`CorrelationIdPort`로 투영한다.
|
||||
- absent/blank는 `Optional.empty()`로 반환한다. application 계층은 SLF4J/MDC를 직접
|
||||
참조하지 않고 event-id fallback 정책만 소유한다.
|
||||
|
||||
### HeaderSanitizer
|
||||
- 이제 `X-Correlation-Id` 는 쓰지 않는다(요청 id 규칙으로 바뀜, 리뷰 02-11). 공개 유틸리티로 남아 있다.
|
||||
- 인바운드 헤더 값을 MDC/로그 도달 전에 무해화(D14, OWASP-LOG-C3/C5, CWE-117). 스켈레톤은 구조화 JSON 로깅을
|
||||
가정하므로 위협은 CR/LF/제어문자를 통한 로그 라인 위조 — 값은 보존하되 `\r`/`\n`/ASCII 제어문자(`< 0x20`)를
|
||||
제거 후 길이 제한.
|
||||
- `프로젝트 선택`: 구체 문자셋 정책(strip vs encode)과 최대 길이는 ca-tmpl 트레이드오프. OWASP 는
|
||||
원칙만 규정하고 정규식/한계는 규정하지 않는다.
|
||||
|
||||
### ResponseMetaFactory
|
||||
- snake_case MDC 진단 키를 camelCase `ResponseMeta` wire 객체로 projection 하는 D19 단일 변환 지점. adapter-web
|
||||
에 위치하는 이유: shared-contract 는 프레임워크 중립이라 MDC 를 읽으면 안 된다.
|
||||
|
||||
+5
-2
@@ -1,6 +1,7 @@
|
||||
package dev.caskeleton.adapter.inbound.web.auth;
|
||||
|
||||
import dev.caskeleton.adapter.inbound.web.error.EnvelopeResponseWriter;
|
||||
import dev.caskeleton.adapter.inbound.web.observability.LoggedPath;
|
||||
import dev.caskeleton.adapter.inbound.web.observability.RetryAfterAdvisor;
|
||||
import dev.caskeleton.shared.error.OperationalError;
|
||||
import jakarta.servlet.http.HttpServletRequest;
|
||||
@@ -29,7 +30,9 @@ class AuthErrorResponseWriter {
|
||||
|
||||
void write(HttpServletRequest request, HttpServletResponse response, OperationalError code)
|
||||
throws IOException {
|
||||
// Log only safe metadata — never the token or the raw failure message. A 5xx is the server's
|
||||
// Log only safe metadata — never the token, the raw failure message or the raw path: the chain
|
||||
// refuses before dispatch, so there is no route template, and the path is redacted. A 5xx is
|
||||
// the server's
|
||||
// own failure (the key service is down, the decoder is misconfigured) and is an ERROR, as a 5xx
|
||||
// is on every other path (ServerFailureLog); a 4xx is the caller's and stays a WARN.
|
||||
log.atLevel(code.httpStatus() >= 500 ? Level.ERROR : Level.WARN)
|
||||
@@ -38,7 +41,7 @@ class AuthErrorResponseWriter {
|
||||
code.code(),
|
||||
code.category(),
|
||||
request.getMethod(),
|
||||
request.getRequestURI());
|
||||
LoggedPath.of(request));
|
||||
|
||||
// A 401 response carries a minimal WWW-Authenticate header (no issuer / token detail).
|
||||
if (code.httpStatus() == 401) {
|
||||
|
||||
+9
-1
@@ -3,6 +3,7 @@ package dev.caskeleton.adapter.inbound.web.error;
|
||||
import dev.caskeleton.adapter.inbound.web.auth.SecurityErrorClassifier;
|
||||
import dev.caskeleton.adapter.inbound.web.conditional.PreconditionFailedException;
|
||||
import dev.caskeleton.adapter.inbound.web.http.ApiHeaders;
|
||||
import dev.caskeleton.adapter.inbound.web.observability.LoggedPath;
|
||||
import dev.caskeleton.adapter.inbound.web.observability.RetryAfterAdvisor;
|
||||
import dev.caskeleton.adapter.inbound.web.pagination.PageValidationException;
|
||||
import dev.caskeleton.shared.error.ApiErrorCarrier;
|
||||
@@ -212,11 +213,18 @@ public class GlobalExceptionHandler extends ResponseEntityExceptionHandler {
|
||||
if (carrier.isPresent()) {
|
||||
return handleCarrier(carrier.get());
|
||||
}
|
||||
log.error("unhandled exception on {}", req.getDescription(false), ex);
|
||||
// The redacted path, not getDescription(false): that is "uri=" plus the raw request URI.
|
||||
log.error("unhandled exception on {}", loggedPath(req), ex);
|
||||
spanErrorRecorder.recordException(ex, OperationalError.INTERNAL_ERROR.code());
|
||||
return ErrorResponseFactory.envelope(OperationalError.INTERNAL_ERROR, null);
|
||||
}
|
||||
|
||||
private static String loggedPath(WebRequest request) {
|
||||
return request instanceof ServletWebRequest servlet
|
||||
? LoggedPath.of(servlet.getRequest())
|
||||
: LoggedPath.HIDDEN;
|
||||
}
|
||||
|
||||
@Override
|
||||
protected ResponseEntity<Object> handleMethodArgumentNotValid(
|
||||
MethodArgumentNotValidException ex,
|
||||
|
||||
+4
-5
@@ -1,6 +1,7 @@
|
||||
package dev.caskeleton.adapter.inbound.web.filter;
|
||||
|
||||
import dev.caskeleton.adapter.inbound.web.auth.AuthenticatedPrincipal;
|
||||
import dev.caskeleton.adapter.inbound.web.observability.LoggedPath;
|
||||
import dev.caskeleton.application.observability.UserPrincipalPseudonymizerPort;
|
||||
import dev.caskeleton.shared.observability.MdcKeys;
|
||||
import jakarta.servlet.FilterChain;
|
||||
@@ -15,7 +16,6 @@ import org.springframework.security.core.Authentication;
|
||||
import org.springframework.security.core.context.SecurityContextHolder;
|
||||
import org.springframework.stereotype.Component;
|
||||
import org.springframework.web.filter.OncePerRequestFilter;
|
||||
import org.springframework.web.servlet.HandlerMapping;
|
||||
|
||||
/**
|
||||
* Logs one structured line per HTTP request. The correlation ids on MDC ({@code request_id}, {@code
|
||||
@@ -60,12 +60,11 @@ public class RequestLoggingFilter extends OncePerRequestFilter {
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns the low-cardinality matched route template ({@code BEST_MATCHING_PATTERN_ATTRIBUTE}),
|
||||
* falling back to the raw request URI for unmatched requests (e.g. 404s).
|
||||
* Returns the low-cardinality matched route template, falling back to the redacted request path
|
||||
* for unmatched requests (e.g. 404s) — {@link LoggedPath}. The fallback used to be the raw URI.
|
||||
*/
|
||||
private static String resolveUriTemplate(HttpServletRequest req) {
|
||||
Object pattern = req.getAttribute(HandlerMapping.BEST_MATCHING_PATTERN_ATTRIBUTE);
|
||||
return pattern instanceof String s ? s : req.getRequestURI();
|
||||
return LoggedPath.of(req);
|
||||
}
|
||||
|
||||
/**
|
||||
|
||||
-25
@@ -1,25 +0,0 @@
|
||||
package dev.caskeleton.adapter.inbound.web.observability;
|
||||
|
||||
/**
|
||||
* Neutralizes inbound header values before they reach MDC / logs by stripping every {@code \r},
|
||||
* {@code \n} and ASCII control char ({@code < 0x20}) and length-capping the result. See README for
|
||||
* the design rationale.
|
||||
*/
|
||||
public final class HeaderSanitizer {
|
||||
|
||||
private HeaderSanitizer() {}
|
||||
|
||||
public static String sanitize(String raw, int maxLength) {
|
||||
if (raw == null) {
|
||||
return null;
|
||||
}
|
||||
StringBuilder sb = new StringBuilder(Math.min(raw.length(), maxLength));
|
||||
for (int i = 0; i < raw.length() && sb.length() < maxLength; i++) {
|
||||
char c = raw.charAt(i);
|
||||
if (c >= 0x20) {
|
||||
sb.append(c);
|
||||
}
|
||||
}
|
||||
return sb.toString();
|
||||
}
|
||||
}
|
||||
+70
@@ -0,0 +1,70 @@
|
||||
package dev.caskeleton.adapter.inbound.web.observability;
|
||||
|
||||
import jakarta.servlet.http.HttpServletRequest;
|
||||
import java.util.StringJoiner;
|
||||
import java.util.regex.Pattern;
|
||||
import org.springframework.web.servlet.HandlerMapping;
|
||||
|
||||
/**
|
||||
* The path a server log line names a request by.
|
||||
*
|
||||
* <p>The matched pattern when the dispatcher found a handler ({@code /v1/orders/{id}}): low
|
||||
* cardinality and free of identifiers. An unmatched path that Boot's static-resource handler takes
|
||||
* is named {@code /**} that way. Otherwise — a request the security chain refused before dispatch,
|
||||
* a request no handler mapping took — the request path with every segment that could carry an
|
||||
* identifier or a personal value replaced by {@value #HIDDEN}: only a segment of letters and
|
||||
* hyphens ({@code orders}, {@code notificationTemplates}) or an API version ({@code v1}) stays, and
|
||||
* at most {@value #MAX_SEGMENTS} segments are kept. The raw {@code getRequestURI()} used to be
|
||||
* logged on those paths (review 2026-11-12), so an email address, a token or an object id in the
|
||||
* path reached the log.
|
||||
*
|
||||
* <p>The rule is by shape, so it has two known edges. A segment of letters only stays even when it
|
||||
* is a value ({@code /users/alice}): a service that puts names in paths gets them in these lines
|
||||
* and should give such routes ids instead. A route literal with a digit or a dot ({@code oauth2},
|
||||
* {@code .well-known}) is hidden like a value. A matched request is named by its template and has
|
||||
* neither edge.
|
||||
*/
|
||||
public final class LoggedPath {
|
||||
|
||||
/** What a segment that may carry a value is replaced by. */
|
||||
public static final String HIDDEN = "{}";
|
||||
|
||||
/** Segments kept before the rest is cut to {@code /...}. */
|
||||
static final int MAX_SEGMENTS = 8;
|
||||
|
||||
private static final Pattern PLAIN_SEGMENT =
|
||||
Pattern.compile("[A-Za-z][A-Za-z-]{0,39}|v[0-9]{1,3}");
|
||||
|
||||
private LoggedPath() {}
|
||||
|
||||
/** The matched route template, or the redacted request path. */
|
||||
public static String of(HttpServletRequest request) {
|
||||
Object template = request.getAttribute(HandlerMapping.BEST_MATCHING_PATTERN_ATTRIBUTE);
|
||||
if (template instanceof String matched && !matched.isBlank()) {
|
||||
return matched;
|
||||
}
|
||||
return redacted(request.getRequestURI());
|
||||
}
|
||||
|
||||
/** The path with every segment outside the plain form replaced. */
|
||||
public static String redacted(String path) {
|
||||
if (path == null || path.isEmpty() || "/".equals(path)) {
|
||||
return "/";
|
||||
}
|
||||
String[] segments = path.split("/", -1);
|
||||
StringJoiner out = new StringJoiner("/");
|
||||
int kept = 0;
|
||||
for (String segment : segments) {
|
||||
if (segment.isEmpty()) {
|
||||
out.add("");
|
||||
continue;
|
||||
}
|
||||
if (kept++ == MAX_SEGMENTS) {
|
||||
out.add("...");
|
||||
break;
|
||||
}
|
||||
out.add(PLAIN_SEGMENT.matcher(segment).matches() ? segment : HIDDEN);
|
||||
}
|
||||
return out.toString();
|
||||
}
|
||||
}
|
||||
+26
-1
@@ -9,6 +9,7 @@ import dev.caskeleton.shared.error.Category;
|
||||
import dev.caskeleton.shared.error.ClientErrorMessages;
|
||||
import java.io.IOException;
|
||||
import java.util.List;
|
||||
import org.junit.jupiter.api.DisplayName;
|
||||
import org.junit.jupiter.api.Test;
|
||||
import org.junit.jupiter.api.extension.ExtendWith;
|
||||
import org.slf4j.LoggerFactory;
|
||||
@@ -178,13 +179,18 @@ class EnvelopeAuthenticationEntryPointTest {
|
||||
|
||||
/** The lines the security writer logs while the entry point answers {@code failure}. */
|
||||
private List<ILoggingEvent> writerLinesFor(AuthenticationException failure) throws Exception {
|
||||
return writerLinesFor(failure, "/v1/things");
|
||||
}
|
||||
|
||||
private List<ILoggingEvent> writerLinesFor(AuthenticationException failure, String path)
|
||||
throws Exception {
|
||||
Logger logger = (Logger) LoggerFactory.getLogger(AuthErrorResponseWriter.class);
|
||||
ListAppender<ILoggingEvent> appender = new ListAppender<>();
|
||||
appender.start();
|
||||
logger.addAppender(appender);
|
||||
try {
|
||||
entryPoint.commence(
|
||||
new MockHttpServletRequest("GET", "/v1/things"), new MockHttpServletResponse(), failure);
|
||||
new MockHttpServletRequest("GET", path), new MockHttpServletResponse(), failure);
|
||||
} finally {
|
||||
logger.detachAppender(appender);
|
||||
appender.stop();
|
||||
@@ -192,6 +198,25 @@ class EnvelopeAuthenticationEntryPointTest {
|
||||
return appender.list;
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("보안 실패 줄은 원본 경로 대신 식별자를 가린 경로를 남긴다(route 를 찾기 전이라 template 이 없다)")
|
||||
void theSecurityLineNamesARedactedPathNotTheRawOne() throws Exception {
|
||||
// given
|
||||
AuthenticationException missing =
|
||||
new org.springframework.security.authentication.InsufficientAuthenticationException("x");
|
||||
|
||||
// when
|
||||
List<ILoggingEvent> lines = writerLinesFor(missing, "/v1/users/alice@example.com/orders/42");
|
||||
|
||||
// then
|
||||
assertThat(lines)
|
||||
.singleElement()
|
||||
.extracting(ILoggingEvent::getFormattedMessage)
|
||||
.isEqualTo(
|
||||
"security failure: code=AUTH_TOKEN_MISSING category=AUTH method=GET"
|
||||
+ " path=/v1/users/{}/orders/{}");
|
||||
}
|
||||
|
||||
@Test
|
||||
void tokenValueNeverLeaksIntoResponseBodyOrLogs(CapturedOutput output) throws Exception {
|
||||
// §테스트 계약: a JWT value must never appear in the response or the log output.
|
||||
|
||||
+27
@@ -365,6 +365,33 @@ class GlobalExceptionHandlerTest {
|
||||
}
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("처리하지 못한 예외의 ERROR 줄은 원본 경로가 아니라 식별자 마디를 가린 경로를 싣는다")
|
||||
void anUnhandledFailureIsLoggedWithTheRedactedPathNotTheRawUri() {
|
||||
// given
|
||||
ch.qos.logback.classic.Logger logger =
|
||||
(ch.qos.logback.classic.Logger) LoggerFactory.getLogger(GlobalExceptionHandler.class);
|
||||
ListAppender<ILoggingEvent> appender = new ListAppender<>();
|
||||
appender.start();
|
||||
logger.addAppender(appender);
|
||||
|
||||
// when
|
||||
try {
|
||||
handler.handleUnknown(
|
||||
new RuntimeException("boom"),
|
||||
new ServletWebRequest(new MockHttpServletRequest("GET", "/v1/orders/SECRET-0042/items")));
|
||||
} finally {
|
||||
logger.detachAppender(appender);
|
||||
appender.stop();
|
||||
}
|
||||
|
||||
// then
|
||||
assertThat(appender.list)
|
||||
.singleElement()
|
||||
.extracting(ILoggingEvent::getFormattedMessage)
|
||||
.isEqualTo("unhandled exception on /v1/orders/{}/items");
|
||||
}
|
||||
|
||||
@Test
|
||||
void internalErrorIsNotRetryableAndHidesMessage() {
|
||||
ResponseEntity<Envelope<Void>> response =
|
||||
|
||||
+22
@@ -12,6 +12,7 @@ import java.util.List;
|
||||
import java.util.Set;
|
||||
import java.util.concurrent.atomic.AtomicReference;
|
||||
import org.junit.jupiter.api.AfterEach;
|
||||
import org.junit.jupiter.api.DisplayName;
|
||||
import org.junit.jupiter.api.Test;
|
||||
import org.slf4j.LoggerFactory;
|
||||
import org.slf4j.MDC;
|
||||
@@ -93,6 +94,27 @@ class RequestLoggingFilterTest {
|
||||
}
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("route 를 못 찾은 요청 줄은 원본 경로가 아니라 식별자 마디를 가린 경로를 싣는다")
|
||||
void anUnmatchedRequestIsLoggedWithTheRedactedPath() throws Exception {
|
||||
// given
|
||||
MockHttpServletRequest req = new MockHttpServletRequest("GET", "/v1/orders/SECRET-0042/items");
|
||||
MockHttpServletResponse res = new MockHttpServletResponse();
|
||||
ListAppender<ILoggingEvent> listAppender = attachAppender();
|
||||
|
||||
// when
|
||||
String msg;
|
||||
try {
|
||||
filter.doFilter(req, res, (rq, rs) -> {});
|
||||
msg = httpRequestEvent(listAppender).getFormattedMessage();
|
||||
} finally {
|
||||
detach(listAppender);
|
||||
}
|
||||
|
||||
// then
|
||||
assertThat(msg).contains("uri_template=/v1/orders/{}/items").doesNotContain("SECRET-0042");
|
||||
}
|
||||
|
||||
// DRIFT-6: user_principal on MDC must be pseudonymized, never raw
|
||||
@Test
|
||||
void putsPseudonymizedUserPrincipalOnMdcNotRawId() throws Exception {
|
||||
|
||||
-39
@@ -1,39 +0,0 @@
|
||||
package dev.caskeleton.adapter.inbound.web.observability;
|
||||
|
||||
import static org.assertj.core.api.Assertions.assertThat;
|
||||
|
||||
import org.junit.jupiter.api.Test;
|
||||
|
||||
class HeaderSanitizerTest {
|
||||
|
||||
@Test
|
||||
void stripsCrLfSoALogForgingPayloadStaysOneLine() {
|
||||
String sanitized = HeaderSanitizer.sanitize("foo\r\nFAKE LOG ENTRY", 200);
|
||||
assertThat(sanitized).isEqualTo("fooFAKE LOG ENTRY");
|
||||
assertThat(sanitized).doesNotContain("\r").doesNotContain("\n");
|
||||
}
|
||||
|
||||
@Test
|
||||
void stripsAsciiControlCharactersButKeepsNormalSpace() {
|
||||
// \t (0x09) and are control chars (< 0x20) and are removed;
|
||||
// a normal space (0x20) is preserved.
|
||||
String sanitized = HeaderSanitizer.sanitize("abc\td e", 200);
|
||||
assertThat(sanitized).isEqualTo("abcd e");
|
||||
}
|
||||
|
||||
@Test
|
||||
void capsLength() {
|
||||
String sanitized = HeaderSanitizer.sanitize("abcdef", 3);
|
||||
assertThat(sanitized).isEqualTo("abc");
|
||||
}
|
||||
|
||||
@Test
|
||||
void nullInNullOut() {
|
||||
assertThat(HeaderSanitizer.sanitize(null, 10)).isNull();
|
||||
}
|
||||
|
||||
@Test
|
||||
void preservesNormalPrintableValue() {
|
||||
assertThat(HeaderSanitizer.sanitize("01HZX9-ok_value", 64)).isEqualTo("01HZX9-ok_value");
|
||||
}
|
||||
}
|
||||
+48
@@ -0,0 +1,48 @@
|
||||
package dev.caskeleton.adapter.inbound.web.observability;
|
||||
|
||||
import static org.assertj.core.api.Assertions.assertThat;
|
||||
|
||||
import org.junit.jupiter.api.DisplayName;
|
||||
import org.junit.jupiter.api.Test;
|
||||
import org.junit.jupiter.params.ParameterizedTest;
|
||||
import org.junit.jupiter.params.provider.CsvSource;
|
||||
import org.springframework.mock.web.MockHttpServletRequest;
|
||||
import org.springframework.web.servlet.HandlerMapping;
|
||||
|
||||
class LoggedPathTest {
|
||||
|
||||
@ParameterizedTest
|
||||
@CsvSource({
|
||||
"/v1/things, /v1/things",
|
||||
"/api/users/alice@example.com, /api/users/{}",
|
||||
"/api/orders/42/items, /api/orders/{}/items",
|
||||
"/internal/notification/callbacks/ses/ses-events, /internal/notification/callbacks/ses/ses-events",
|
||||
"/files/01J9ZP3QX8, /files/{}",
|
||||
"/a/b/c/d/e/f/g/h/i/j, /a/b/c/d/e/f/g/h/...",
|
||||
"/notificationTemplates/tpl_1, /notificationTemplates/{}"
|
||||
})
|
||||
@DisplayName("route 를 못 찾은 요청은 식별자가 들 수 있는 마디를 {} 로 가린 경로로 남는다")
|
||||
void anUnmatchedPathKeepsOnlyPlainSegments(String raw, String logged) {
|
||||
// given
|
||||
MockHttpServletRequest request = new MockHttpServletRequest("GET", raw);
|
||||
|
||||
// when
|
||||
String path = LoggedPath.of(request);
|
||||
|
||||
// then
|
||||
assertThat(path).isEqualTo(logged);
|
||||
}
|
||||
|
||||
@Test
|
||||
void aMatchedRequestIsNamedByItsRouteTemplate() {
|
||||
// given
|
||||
MockHttpServletRequest request = new MockHttpServletRequest("GET", "/v1/orders/42");
|
||||
request.setAttribute(HandlerMapping.BEST_MATCHING_PATTERN_ATTRIBUTE, "/v1/orders/{id}");
|
||||
|
||||
// when
|
||||
String path = LoggedPath.of(request);
|
||||
|
||||
// then
|
||||
assertThat(path).isEqualTo("/v1/orders/{id}");
|
||||
}
|
||||
}
|
||||
+1
-1
@@ -103,7 +103,7 @@ public final class MicrometerFileserverMetrics implements FileserverMetricsPort
|
||||
@Override
|
||||
public void recordOffsetMismatch(UploadMode mode, String clientType) {
|
||||
increment(
|
||||
"fileserver.upload.offset_mismatch",
|
||||
"fileserver.upload.offset.mismatch",
|
||||
Tags.of("mode", tag(mode.name()), "client_type", tag(clientType)));
|
||||
}
|
||||
|
||||
|
||||
+2
-1
@@ -26,8 +26,9 @@ public final class HttpClientObservationNames {
|
||||
public static final String CONNECT_DURATION = "http.client.connect.duration";
|
||||
public static final String TLS_DURATION = "http.client.tls.duration";
|
||||
public static final String CIRCUIT_STATE = "http.client.circuit.state";
|
||||
public static final String CIRCUIT_REJECTED = "http.client.circuit.state.rejected";
|
||||
public static final String BULKHEAD_REJECTED = "http.client.bulkhead.rejected";
|
||||
public static final String RATE_LIMIT_REJECTED = "http.client.rate_limit.rejected";
|
||||
public static final String RATE_LIMIT_REJECTED = "http.client.ratelimit.rejected";
|
||||
public static final String OAUTH_REFRESH = "http.client.oauth.refresh";
|
||||
public static final String SSRF_REJECTED = "http.client.ssrf.rejected";
|
||||
|
||||
|
||||
+2
-2
@@ -11,7 +11,7 @@ import java.util.function.Supplier;
|
||||
/**
|
||||
* Publishes the local back-pressure signals the platform already produced but never recorded.
|
||||
*
|
||||
* <p>{@code http.client.rate_limit.rejected}, {@code http.client.bulkhead.rejected} and {@code
|
||||
* <p>{@code http.client.ratelimit.rejected}, {@code http.client.bulkhead.rejected} and {@code
|
||||
* http.client.circuit.state} were declared in the metric vocabulary, documented in the support
|
||||
* matrix, and emitted by nothing. That is the worst arrangement of the three possibilities: an
|
||||
* operator building a dashboard finds the names, charts them, and sees a flat zero during the exact
|
||||
@@ -76,7 +76,7 @@ public interface ResilienceRejectionRecorder {
|
||||
return new ResilienceRejectionRecorder() {
|
||||
@Override
|
||||
public void circuitOpen() {
|
||||
registry.counter(HttpClientObservationNames.CIRCUIT_STATE + ".rejected", tags).increment();
|
||||
registry.counter(HttpClientObservationNames.CIRCUIT_REJECTED, tags).increment();
|
||||
}
|
||||
|
||||
@Override
|
||||
|
||||
@@ -24,8 +24,8 @@ bean과 함께 Boot의 JDBC·Hibernate·Spring Data JPA·Flyway 자동 설정도
|
||||
필요한 다른 capability(notification·fileserver 저장소, messaging JDBC outbox/inbox 등)와 함께 끌 수는 없다)
|
||||
|
||||
- 포트 구현: `TransactionPort`(`SpringTransaction`), `DistributedLockPort`(단일 인스턴스는
|
||||
in-process, `APP_MULTI_INSTANCE_ENABLED=true`면 JDBC `INT_LOCK` + `MeteredDistributedLock`
|
||||
데코레이터 = `distributedLockProvider`), outbox store(`OutboxStorePort`, `APP_OUTBOX_ENABLED=true`),
|
||||
in-process, `APP_MULTI_INSTANCE_ENABLED=true`면 JDBC `INT_LOCK` = `distributedLockProvider`. 둘 다
|
||||
`MeteredDistributedLock` 데코레이터 안에 있다), outbox store(`OutboxStorePort`, `APP_OUTBOX_ENABLED=true`),
|
||||
PostgreSQL 멱등성 store(`APP_IDEMPOTENCY_PROVIDER=postgresql`), audit·operation·live-event store.
|
||||
- 엔티티/리포지토리 스캔, vendor 조립(PostgreSQL 기본, H2는 개발용), Flyway 위치.
|
||||
- 기동 정책(`startup` 패키지, `JpaStartupAutoConfiguration`): Flyway 마이그레이션 전략
|
||||
@@ -573,7 +573,8 @@ provider 선택(flag → bean → registry)의 정본은 설정 코드 `lock/Dis
|
||||
### `DistributedLockPersistenceConfig` 와이어링 결정
|
||||
- `jdbcDistributedLock` 빈은 일부러 `@Primary` 가 아니다. 같은 설정이 이를 metrics
|
||||
데코레이터(`MeteredDistributedLock`, package-private)로 감싸 `@Primary`
|
||||
`distributedLockProvider` 빈으로 노출한다. 예전에는 app-bootstrap의 `DistributedLockConfig`가
|
||||
`distributedLockProvider` 빈으로 노출한다. 단일 인스턴스의 `inProcessDistributedLock` 도 같은 데코레이터 안에 있어
|
||||
`lock.acquisition` 이 두 경로를 모두 센다. 예전에는 app-bootstrap의 `DistributedLockConfig`가
|
||||
감쌌지만, JDBC 락이 있을 때만 의미가 있는 코드라 이 모듈로 옮겼다. SI 타입은 여전히 이 모듈
|
||||
밖으로 보이지 않는다(SI 는 `implementation` 의존).
|
||||
- `DefaultLockRepository` 는 `InitializingBean`/`SmartLifecycle` 을 구현해 Spring 이 lifecycle 을
|
||||
|
||||
+13
-3
@@ -37,7 +37,14 @@ public class DistributedLockPersistenceConfig {
|
||||
return LockSettings.bind(environment);
|
||||
}
|
||||
|
||||
/** In-process adapter; active when {@code multi-instance-enabled} is {@code false} or absent. */
|
||||
/**
|
||||
* In-process adapter; active when {@code multi-instance-enabled} is {@code false} or absent.
|
||||
*
|
||||
* <p>Behind the same metrics decorator as the JDBC one, so {@code lock.acquisition} counts every
|
||||
* call on both paths. It used to be the bare adapter, and on the default single-instance path the
|
||||
* meter stayed at zero while the registry and README said it counted every call (review
|
||||
* 2026-11-12).
|
||||
*/
|
||||
@Bean
|
||||
@Primary
|
||||
@ConditionalOnProperty(
|
||||
@@ -45,8 +52,11 @@ public class DistributedLockPersistenceConfig {
|
||||
name = "multi-instance-enabled",
|
||||
havingValue = "false",
|
||||
matchIfMissing = true)
|
||||
DistributedLockPort inProcessDistributedLock(LockSettings settings) {
|
||||
return new LockRegistryDistributedLock(new DefaultLockRegistry(), settings.leaseTtl());
|
||||
DistributedLockPort inProcessDistributedLock(
|
||||
LockSettings settings, ObjectProvider<MeterRegistry> meterRegistry) {
|
||||
return new MeteredDistributedLock(
|
||||
new LockRegistryDistributedLock(new DefaultLockRegistry(), settings.leaseTtl()),
|
||||
meterRegistry);
|
||||
}
|
||||
|
||||
/**
|
||||
|
||||
+29
@@ -4,6 +4,9 @@ import static org.assertj.core.api.Assertions.assertThat;
|
||||
import static org.mockito.Mockito.mock;
|
||||
|
||||
import dev.caskeleton.application.lock.DistributedLockPort;
|
||||
import io.micrometer.core.instrument.MeterRegistry;
|
||||
import io.micrometer.core.instrument.simple.SimpleMeterRegistry;
|
||||
import java.time.Duration;
|
||||
import javax.sql.DataSource;
|
||||
import org.junit.jupiter.api.DisplayName;
|
||||
import org.junit.jupiter.api.Test;
|
||||
@@ -35,6 +38,32 @@ class DistributedLockPersistenceConfigTest {
|
||||
});
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("단일 인스턴스의 in-process lock 도 lock.acquisition 을 센다")
|
||||
void theInProcessLockIsMeteredToo() {
|
||||
contextRunner
|
||||
.withBean(MeterRegistry.class, SimpleMeterRegistry::new)
|
||||
.withPropertyValues("app.runtime.multi-instance-enabled=false")
|
||||
.run(
|
||||
context -> {
|
||||
// when
|
||||
context
|
||||
.getBean(DistributedLockPort.class)
|
||||
.tryAcquire("orders", Duration.ZERO, Duration.ofSeconds(5))
|
||||
.close();
|
||||
|
||||
// then
|
||||
assertThat(
|
||||
context
|
||||
.getBean(MeterRegistry.class)
|
||||
.get("lock.acquisition")
|
||||
.tag("outcome", "acquired")
|
||||
.counter()
|
||||
.count())
|
||||
.isEqualTo(1.0);
|
||||
});
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("app.lock 아래 오타 키는 기동을 실패시킨다")
|
||||
void aMisspelledLockKeyFailsStartup() {
|
||||
|
||||
@@ -323,6 +323,9 @@ relay 조립(`OutboxRelayAutoConfiguration`, 스케줄러·metrics·leader token
|
||||
- **시크릿 값만 가리고 키/스킴은 남긴다.** `token=abc123` → `token=****`,
|
||||
`Authorization: Bearer eyJ...` → `Authorization: Bearer ****`처럼 동작한다. 키와 인증 스킴(`Bearer`
|
||||
등)을 남기는 이유는 진단할 때 "어떤 종류의 자격증명이 있었는지"는 알아야 하기 때문이다.
|
||||
- **URI의 사용자 정보 비밀번호와 PEM 블록도 가린다.** `jdbc:postgresql://app:pw@db` → `jdbc:postgresql://app:****@db`
|
||||
(사용자 이름은 남긴다, secrets registry의 `userinfo` 규칙). `-----BEGIN …-----`부터 `-----END …-----`까지(키·인증서)는
|
||||
여러 줄이어도 본문 전체를 가리고 두 경계 줄만 남긴다. 같은 라벨의 END가 없으면 끝까지 가린다.
|
||||
- **정규식 마스킹은 보증이 아니라 심층 방어(defence-in-depth)의 보조 수단이다.** 1차 방어선은
|
||||
"로거가 애초에 본문/페이로드를 받지 않도록 설계한 것"(`FailOpenDependencyLogger`)이고, 이 정규식은
|
||||
그걸 빠져나간 누출을 잡는 그물이다. 키 접두어 없는 Base64URL 블롭 같은 난독화된 형태는 놓칠 수
|
||||
@@ -346,6 +349,10 @@ relay 조립(`OutboxRelayAutoConfiguration`, 스케줄러·metrics·leader token
|
||||
(`FilterReply.NEUTRAL`). 진단·장애 신호인 경고/오류는 100% 보장해야 하고, 샘플링 대상은 `INFO`
|
||||
이하만이라는 정책 때문이다. `INFO` 이하는 확률 `rate`로 보존하고 나머지는 `FilterReply.DENY`로
|
||||
버린다.
|
||||
- **감사·보안 기록은 레벨과 상관없이 샘플링하지 않는다.** logger 이름의 마지막 마디가 `audit`·`security`이거나
|
||||
(`notification.audit`, `dev.caskeleton.fileserver.audit`, `notification.security`) `AUDIT` marker를 단 줄이다.
|
||||
감사 logger가 INFO로 쓰므로 그렇지 않으면 prod 권장값 `0.1`에서 감사 기록 열에 아홉이 버려진다.
|
||||
다른 이름의 감사 logger는 `AUDIT` marker를 단다.
|
||||
- **단일 `rate` 노브로 제어한다.** `APP_LOG_SAMPLING_RATE`(logback `springProperty`)에서 주입되고,
|
||||
운영자가 런타임별로 설정한다(prod `0.1` = INFO 10% 샘플링, dev/local `1.0` = 전부 보존).
|
||||
고트래픽 vs 일반 엔드포인트의 더 세밀한 분기는 이 전역 rate 위에 마커 기반 확장으로 문서화만 되어
|
||||
|
||||
@@ -47,7 +47,7 @@ services:
|
||||
environment:
|
||||
PGHOST: "db"
|
||||
PGUSER: "${APP_DATASOURCE_USERNAME:-ca_skeleton}"
|
||||
PGPASSWORD: "${APP_DATASOURCE_PASSWORD:-ca_skeleton}"
|
||||
PGPASSWORD: "${APP_DATASOURCE_PASSWORD:-__LOCAL_DEV_db_password__}"
|
||||
PGDATABASE: "${POSTGRES_DB:-ca_skeleton}"
|
||||
CAPABILITY_STREAMS: "${CAPABILITY_STREAMS:-}"
|
||||
volumes:
|
||||
@@ -82,7 +82,7 @@ services:
|
||||
environment:
|
||||
PGHOST: "db"
|
||||
PGUSER: "${APP_DATASOURCE_USERNAME:-ca_skeleton}"
|
||||
PGPASSWORD: "${APP_DATASOURCE_PASSWORD:-ca_skeleton}"
|
||||
PGPASSWORD: "${APP_DATASOURCE_PASSWORD:-__LOCAL_DEV_db_password__}"
|
||||
PGDATABASE: "${POSTGRES_DB:-ca_skeleton}"
|
||||
CAPABILITY_STREAMS: "${CAPABILITY_STREAMS:-}"
|
||||
volumes:
|
||||
@@ -176,7 +176,7 @@ services:
|
||||
environment:
|
||||
MINIO_ENDPOINT: "http://minio:9000"
|
||||
MINIO_ROOT_USER: "${MINIO_ROOT_USER:-caskeleton}"
|
||||
MINIO_ROOT_PASSWORD: "${MINIO_ROOT_PASSWORD:-caskeleton-local}"
|
||||
MINIO_ROOT_PASSWORD: "${MINIO_ROOT_PASSWORD:-__LOCAL_DEV_minio_root__}"
|
||||
MINIO_BUCKET: "${MINIO_BUCKET:-ca-skeleton-objects}"
|
||||
volumes:
|
||||
- type: bind
|
||||
|
||||
+30
-3
@@ -7,7 +7,11 @@ import net.logstash.logback.mask.ValueMasker;
|
||||
|
||||
/**
|
||||
* SSOT for secret-masking regex rules (shared by the JSON-encoder and pattern-layout paths). See
|
||||
* README for the design rationale.
|
||||
* README for the design rationale. The rules are the {@code masking_rule} values of {@code
|
||||
* docs/registries/secrets-classification.yaml}: {@code full} (rules 0–3) and {@code userinfo} (rule
|
||||
* 4). Rule 1 knows the secret names that registry uses — password, secret, token, api key, salt,
|
||||
* PEM, and HMAC/signing/encryption/credential/private keys — so a {@code NAME=value} of any {@code
|
||||
* full} row is masked; {@code SecretsClassificationRegistryTest} checks every such row.
|
||||
*/
|
||||
public final class LogMaskingPatterns {
|
||||
|
||||
@@ -22,11 +26,20 @@ public final class LogMaskingPatterns {
|
||||
|
||||
private static final List<Rule> RULES =
|
||||
List.of(
|
||||
// 0. A PEM block, multi-line included: rule 1 alone stops at the first space and would
|
||||
// mask only "-----BEGIN". The armour lines stay so a line still says what it held.
|
||||
// A block cut short (no END with its own label) is masked to the end of the text: what
|
||||
// follows the armour is key material either way.
|
||||
new Rule(
|
||||
Pattern.compile(
|
||||
"(-----BEGIN ([A-Z0-9 ]{1,40})-----)[\\s\\S]*?(-----END \\2-----|\\z)"),
|
||||
"$1" + MASK + "$3"),
|
||||
// 1. key=value / "key":"value" secrets — keep the key + separator, mask the value.
|
||||
new Rule(
|
||||
Pattern.compile(
|
||||
"(?i)(password|passwd|pwd|secret|token|api[_-]?key|access[_-]?token"
|
||||
+ "|refresh[_-]?token|client[_-]?secret)("
|
||||
+ "|refresh[_-]?token|client[_-]?secret|salt|pem"
|
||||
+ "|(?:hmac|signing|encryption|credential|private)[_-]?key)("
|
||||
+ SEP
|
||||
+ ")("
|
||||
+ VALUE
|
||||
@@ -38,7 +51,21 @@ public final class LogMaskingPatterns {
|
||||
"(?i)(authorization" + SEP + ")((?:bearer|basic|negotiate)\\s+)?(" + VALUE + ")"),
|
||||
"$1$2" + MASK),
|
||||
// 3. Standalone bearer token not preceded by an "authorization" key.
|
||||
new Rule(Pattern.compile("(?i)(bearer\\s+)([A-Za-z0-9._~+/=-]{8,})"), "$1" + MASK));
|
||||
new Rule(Pattern.compile("(?i)(bearer\\s+)([A-Za-z0-9._~+/=-]{8,})"), "$1" + MASK),
|
||||
// 4. The password in a URI's userinfo (jdbc:postgresql://app:pw@db, mongodb+srv://…),
|
||||
// the secrets registry's "userinfo" rule. The user name stays, so a line still says
|
||||
// which account connected (review 2026-11-12: the rule was declared, nothing did it).
|
||||
new Rule(
|
||||
// The password ends at the first '@' that a host[:port] and a delimiter follow, so a
|
||||
// raw '@', '/', '#' or '?' in it is masked too, and an '@' later in a path or query
|
||||
// is not taken for one. "user:8080/" is a port, not a password. The password is
|
||||
// bounded and never crosses another "://", so a long line stays linear.
|
||||
Pattern.compile(
|
||||
"(?i)(?<![a-z0-9+.-])([a-z][a-z0-9+.-]*://[^:/@\\s\"']*:)"
|
||||
+ "(?!\\d{1,5}(?:[/?#\\s]|$))"
|
||||
+ "((?:(?!://)[^\\s\"]){1,256}?)(@)"
|
||||
+ "(?=[a-z0-9.-]+(?::\\d+)?(?:[/?#,;\\s\"']|$))"),
|
||||
"$1" + MASK + "$3"));
|
||||
|
||||
private LogMaskingPatterns() {}
|
||||
|
||||
|
||||
+41
@@ -0,0 +1,41 @@
|
||||
package dev.caskeleton.bootstrap.logging;
|
||||
|
||||
import ch.qos.logback.classic.spi.ILoggingEvent;
|
||||
import com.fasterxml.jackson.core.JsonGenerator;
|
||||
import java.io.IOException;
|
||||
import net.logstash.logback.composite.AbstractFieldJsonProvider;
|
||||
import net.logstash.logback.composite.JsonWritingUtils;
|
||||
|
||||
/**
|
||||
* Writes the JSON {@code profile} field from the logger context property at the moment each line is
|
||||
* written.
|
||||
*
|
||||
* <p>{@code customFields} in {@code logback-spring.xml} is substituted once, when Logback reads the
|
||||
* file — before {@link ResolvedProfileLoggingContextListener} replaces the property with the
|
||||
* resolved profile. So the field kept the environment variable's value (or {@code unresolved})
|
||||
* while the property beside it was corrected, and the characterization test, which read only the
|
||||
* property, passed (review 2026-11-12). Reading the property per line is what makes the correction
|
||||
* reach the line.
|
||||
*/
|
||||
public class ResolvedProfileJsonProvider extends AbstractFieldJsonProvider<ILoggingEvent> {
|
||||
|
||||
/** The JSON field name. */
|
||||
static final String FIELD = "profile";
|
||||
|
||||
/** What the field says before any profile is known. */
|
||||
static final String UNRESOLVED = "unresolved";
|
||||
|
||||
public ResolvedProfileJsonProvider() {
|
||||
setFieldName(FIELD);
|
||||
}
|
||||
|
||||
@Override
|
||||
public void writeTo(JsonGenerator generator, ILoggingEvent event) throws IOException {
|
||||
String profile =
|
||||
getContext() == null
|
||||
? null
|
||||
: getContext().getProperty(ResolvedProfileLoggingContextListener.PROFILE_PROPERTY);
|
||||
JsonWritingUtils.writeStringField(
|
||||
generator, getFieldName(), profile == null || profile.isBlank() ? UNRESOLVED : profile);
|
||||
}
|
||||
}
|
||||
+4
@@ -30,6 +30,10 @@ import org.springframework.core.env.ConfigurableEnvironment;
|
||||
* sentinel {@code unresolved}; it no longer guesses {@code local}. Once the environment-prepared
|
||||
* event fires, this listener replaces that sentinel with the resolved profile.
|
||||
*
|
||||
* <p>The property is what {@link ResolvedProfileJsonProvider} reads for each JSON line. The JSON
|
||||
* field used to come from {@code customFields}, which Logback substitutes once when it reads the
|
||||
* file, so this correction changed the property and not the field (review 2026-11-12).
|
||||
*
|
||||
* <p>Registered in {@code META-INF/spring.factories}. A listener for this event cannot be a bean:
|
||||
* the event fires long before there is a context to hold one.
|
||||
*/
|
||||
|
||||
+37
-2
@@ -4,6 +4,10 @@ import ch.qos.logback.classic.Level;
|
||||
import ch.qos.logback.classic.Logger;
|
||||
import ch.qos.logback.classic.turbo.TurboFilter;
|
||||
import ch.qos.logback.core.spi.FilterReply;
|
||||
import java.util.Locale;
|
||||
import java.util.Map;
|
||||
import java.util.Set;
|
||||
import java.util.concurrent.ConcurrentHashMap;
|
||||
import java.util.concurrent.ThreadLocalRandom;
|
||||
import org.slf4j.Marker;
|
||||
|
||||
@@ -11,11 +15,27 @@ import org.slf4j.Marker;
|
||||
* Level-aware log sampler. {@code WARN}/{@code ERROR} are never sampled because they are
|
||||
* diagnostic/incident signals that must be guaranteed; only {@code INFO} and below are sampled. See
|
||||
* README for the design rationale.
|
||||
*
|
||||
* <p>An audit or security record is never sampled either, whatever its level: a logger whose name
|
||||
* ends in an {@code audit} or {@code security} segment ({@code notification.audit}, {@code
|
||||
* dev.caskeleton.fileserver.audit}, {@code notification.security}), or a line carrying the {@value
|
||||
* #AUDIT_MARKER} marker. The last segment only, so a library package such as {@code
|
||||
* org.springframework.security.web.FilterChainProxy} is still sampled. The answer is kept per
|
||||
* logger name: the filter runs before the level check, on every call below WARN. Those loggers
|
||||
* write at INFO, so at the recommended production rate of 0.1 nine audit records in ten were
|
||||
* dropped (review 2026-11-12). An audit trail with holes is not one.
|
||||
*/
|
||||
public class SamplingTurboFilter extends TurboFilter {
|
||||
|
||||
private static final double KEEP_ALL = 1.0d;
|
||||
|
||||
/** A marker that exempts one line from sampling, for an audit logger with another name. */
|
||||
public static final String AUDIT_MARKER = "AUDIT";
|
||||
|
||||
private static final Set<String> NEVER_SAMPLED_SEGMENTS = Set.of("audit", "security");
|
||||
|
||||
private final Map<String, Boolean> auditLoggers = new ConcurrentHashMap<>();
|
||||
|
||||
private volatile double rate = KEEP_ALL;
|
||||
|
||||
/** Logback Joran setter — {@code <rate>${LOG_SAMPLING_RATE}</rate>}. */
|
||||
@@ -46,8 +66,8 @@ public class SamplingTurboFilter extends TurboFilter {
|
||||
if (level.toInt() >= Level.WARN_INT) {
|
||||
return FilterReply.NEUTRAL;
|
||||
}
|
||||
// <= INFO: keep with probability `rate`.
|
||||
if (rate >= KEEP_ALL) {
|
||||
// <= INFO: keep with probability `rate`, audit and security records always.
|
||||
if (rate >= KEEP_ALL || isAuditRecord(marker, logger)) {
|
||||
return FilterReply.NEUTRAL;
|
||||
}
|
||||
if (rate <= 0.0d) {
|
||||
@@ -55,4 +75,19 @@ public class SamplingTurboFilter extends TurboFilter {
|
||||
}
|
||||
return ThreadLocalRandom.current().nextDouble() < rate ? FilterReply.NEUTRAL : FilterReply.DENY;
|
||||
}
|
||||
|
||||
private boolean isAuditRecord(Marker marker, Logger logger) {
|
||||
// The marker's own name: SLF4J 2 deprecates marker references, so a line carries the AUDIT
|
||||
// marker itself rather than one that refers to it.
|
||||
if (marker != null && AUDIT_MARKER.equals(marker.getName())) {
|
||||
return true;
|
||||
}
|
||||
return logger != null
|
||||
&& auditLoggers.computeIfAbsent(logger.getName(), SamplingTurboFilter::endsInAuditSegment);
|
||||
}
|
||||
|
||||
private static boolean endsInAuditSegment(String loggerName) {
|
||||
String last = loggerName.substring(loggerName.lastIndexOf('.') + 1);
|
||||
return NEVER_SAMPLED_SEGMENTS.contains(last.toLowerCase(Locale.ROOT));
|
||||
}
|
||||
}
|
||||
|
||||
@@ -52,7 +52,7 @@ spring:
|
||||
# H2 is still available and now has to be asked for: `./gradlew :app-bootstrap:bootRunH2`.
|
||||
url: ${APP_DATASOURCE_URL:jdbc:postgresql://localhost:5433/ca_skeleton}
|
||||
username: ${APP_DATASOURCE_USERNAME:ca_skeleton}
|
||||
password: ${APP_DATASOURCE_PASSWORD:ca_skeleton}
|
||||
password: ${APP_DATASOURCE_PASSWORD:__LOCAL_DEV_db_password__}
|
||||
driver-class-name: ${APP_DATASOURCE_DRIVER:org.postgresql.Driver}
|
||||
hikari:
|
||||
maximum-pool-size: 10
|
||||
@@ -118,7 +118,9 @@ server:
|
||||
port: ${APP_SERVER_PORT:8080}
|
||||
shutdown: graceful
|
||||
# No proxy in front of a local run, so trusting X-Forwarded-* would let a caller forge its own
|
||||
# client IP. dev/prod sit behind a load balancer and set this to framework via env.
|
||||
# client IP. dev/prod behind a load balancer set APP_SERVER_FORWARD_HEADERS_STRATEGY=native and
|
||||
# list their proxies' IPs (a regex) in server.tomcat.remoteip.internal-proxies — never framework,
|
||||
# which believes every peer (config/server.yml).
|
||||
forward-headers-strategy: none
|
||||
tomcat:
|
||||
threads:
|
||||
|
||||
@@ -55,7 +55,8 @@
|
||||
<springProperty scope="context" name="JSON_LOGGER_NAME_LENGTH"
|
||||
source="app.logging.json.logger-name-length" defaultValue="0"/>
|
||||
|
||||
<!-- D5/D8: ≤INFO sampling rate (prod 0.1 = 10%); WARN/ERROR always kept. -->
|
||||
<!-- D5/D8: ≤INFO sampling rate (prod 0.1 = 10%); WARN/ERROR always kept, and so are audit and
|
||||
security records at any level (SamplingTurboFilter). -->
|
||||
<springProperty scope="context" name="LOG_SAMPLING_RATE"
|
||||
source="app.logging.sampling-rate" defaultValue="1.0"/>
|
||||
|
||||
@@ -64,7 +65,8 @@
|
||||
<conversionRule conversionWord="maskedMsg"
|
||||
class="dev.caskeleton.bootstrap.logging.SecretMaskingMessageConverter"/>
|
||||
|
||||
<!-- Sampling Policy (final): drop a share of ≤INFO events; WARN/ERROR pass unconditionally. -->
|
||||
<!-- Sampling Policy (final): drop a share of ≤INFO events; WARN/ERROR, the AUDIT marker and loggers
|
||||
whose last segment is audit or security pass unconditionally. -->
|
||||
<turboFilter class="dev.caskeleton.bootstrap.logging.SamplingTurboFilter">
|
||||
<rate>${LOG_SAMPLING_RATE}</rate>
|
||||
</turboFilter>
|
||||
@@ -86,7 +88,10 @@
|
||||
<appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
|
||||
<encoder class="net.logstash.logback.encoder.LogstashEncoder">
|
||||
<includeContext>false</includeContext>
|
||||
<customFields>{"app":"${APP_NAME}","profile":"${APP_PROFILE}"}</customFields>
|
||||
<customFields>{"app":"${APP_NAME}"}</customFields>
|
||||
<!-- profile per line from the context property the resolved environment sets;
|
||||
customFields is fixed when this file is read (ResolvedProfileJsonProvider). -->
|
||||
<provider class="dev.caskeleton.bootstrap.logging.ResolvedProfileJsonProvider"/>
|
||||
<includeMdcKeyName>trace_id</includeMdcKeyName>
|
||||
<includeMdcKeyName>span_id</includeMdcKeyName>
|
||||
<includeMdcKeyName>request_id</includeMdcKeyName>
|
||||
@@ -119,7 +124,10 @@
|
||||
</rollingPolicy>
|
||||
<encoder class="net.logstash.logback.encoder.LogstashEncoder">
|
||||
<includeContext>false</includeContext>
|
||||
<customFields>{"app":"${APP_NAME}","profile":"${APP_PROFILE}"}</customFields>
|
||||
<customFields>{"app":"${APP_NAME}"}</customFields>
|
||||
<!-- profile per line from the context property the resolved environment sets;
|
||||
customFields is fixed when this file is read (ResolvedProfileJsonProvider). -->
|
||||
<provider class="dev.caskeleton.bootstrap.logging.ResolvedProfileJsonProvider"/>
|
||||
<includeMdcKeyName>trace_id</includeMdcKeyName>
|
||||
<includeMdcKeyName>span_id</includeMdcKeyName>
|
||||
<includeMdcKeyName>request_id</includeMdcKeyName>
|
||||
|
||||
+8
-11
@@ -131,8 +131,9 @@ class DistributedTracingContractTest {
|
||||
/**
|
||||
* Asserts the {@code traceparent} row in {@code headers.yaml} has {@code generated_if_missing:
|
||||
* true}, {@code mdc_key: trace_id}, {@code envelope_meta_field: traceId}, and that the {@code
|
||||
* tracestate} row exists with {@code generated_if_missing: false}; AND that code agrees: {@code
|
||||
* MdcKeys.TRACE_ID == "trace_id"} and {@link ResponseMeta} has a {@code traceId} component.
|
||||
* tracestate} row is the framework's (the W3C propagator carries it next to traceparent; no
|
||||
* template code reads it); AND that code agrees: {@code MdcKeys.TRACE_ID == "trace_id"} and
|
||||
* {@link ResponseMeta} has a {@code traceId} component.
|
||||
*/
|
||||
@Tag("document-contract")
|
||||
@Test
|
||||
@@ -157,15 +158,11 @@ class DistributedTracingContractTest {
|
||||
.as("traceparent: envelope_meta_field must be 'traceId'")
|
||||
.isEqualTo("traceId");
|
||||
|
||||
// tracestate row: generated_if_missing=false
|
||||
Map<String, Object> tracestateRow =
|
||||
headers.stream()
|
||||
.filter(h -> "tracestate".equals(h.get("name")))
|
||||
.findFirst()
|
||||
.orElseThrow(() -> new AssertionError("headers.yaml must contain a 'tracestate' row"));
|
||||
assertThat(tracestateRow.get("generated_if_missing"))
|
||||
.as("tracestate: generated_if_missing must be false")
|
||||
.isEqualTo(false);
|
||||
// tracestate travels with traceparent through the W3C propagator; no template code reads it.
|
||||
assertThat(headers)
|
||||
.filteredOn(h -> "tracestate".equals(h.get("name")))
|
||||
.singleElement()
|
||||
.satisfies(row -> assertThat(String.valueOf(row.get("source"))).startsWith("framework:"));
|
||||
|
||||
// Code alignment: MdcKeys.TRACE_ID constant must match the registry mdc_key value
|
||||
assertThat(MdcKeys.TRACE_ID)
|
||||
|
||||
+54
-3
@@ -3,13 +3,18 @@ package dev.caskeleton.bootstrap.contract;
|
||||
import static org.assertj.core.api.Assertions.assertThat;
|
||||
|
||||
import dev.caskeleton.adapter.inbound.web.ratelimit.RateLimitWebConfig;
|
||||
import dev.caskeleton.bootstrap.contract.support.MainSources;
|
||||
import dev.caskeleton.bootstrap.contract.support.RepositoryContractResources;
|
||||
import java.io.IOException;
|
||||
import java.io.InputStream;
|
||||
import java.nio.file.Files;
|
||||
import java.nio.file.Path;
|
||||
import java.util.ArrayList;
|
||||
import java.util.List;
|
||||
import java.util.Map;
|
||||
import java.util.Set;
|
||||
import org.junit.jupiter.api.BeforeAll;
|
||||
import org.junit.jupiter.api.DisplayName;
|
||||
import org.junit.jupiter.api.Tag;
|
||||
import org.junit.jupiter.api.Test;
|
||||
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
|
||||
@@ -18,6 +23,16 @@ import org.yaml.snakeyaml.Yaml;
|
||||
@Tag("document-contract")
|
||||
class HeaderRegistryRuntimeAlignmentTest {
|
||||
|
||||
/** A source prefix: a constant the template declares for service controllers to read. */
|
||||
private static final String SERVICE = "service: ";
|
||||
|
||||
/**
|
||||
* The only headers a {@code service:} row may name — README 「ApiHeaders」's constants for service
|
||||
* controllers. Anything else must name the main file that reads or writes it.
|
||||
*/
|
||||
private static final Set<String> FOR_SERVICE_CONTROLLERS =
|
||||
Set.of("Idempotency-Key", "If-Match", "If-None-Match");
|
||||
|
||||
private static List<Map<String, Object>> headers;
|
||||
|
||||
@BeforeAll
|
||||
@@ -40,12 +55,48 @@ class HeaderRegistryRuntimeAlignmentTest {
|
||||
}
|
||||
|
||||
@Test
|
||||
void deprecationDatesUseTheHttpDateWireType() {
|
||||
assertThat(row("Deprecation").get("type")).isEqualTo("http-date");
|
||||
assertThat(row("Sunset").get("type")).isEqualTo("http-date");
|
||||
void theRateLimitResetUsesTheRfc3339WireType() {
|
||||
assertThat(row("X-RateLimit-Reset").get("type")).isEqualTo("rfc3339-date");
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("headers.yaml 의 행마다 그 헤더를 쓰는 main 파일이 있다 — 선언만 있는 상수는 정해 둔 서비스용 상수일 때만 된다")
|
||||
void everyRowNamesTheMainFileThatReadsOrWritesIt() throws IOException {
|
||||
// given
|
||||
Path root = RepositoryContractResources.fromSystemProperty().repositoryRoot();
|
||||
MainSources main = MainSources.under(root);
|
||||
|
||||
// when
|
||||
List<String> unbacked = new ArrayList<>();
|
||||
for (Map<String, Object> header : headers) {
|
||||
String name = String.valueOf(header.get("name"));
|
||||
String source = String.valueOf(header.get("source"));
|
||||
if (source.startsWith("framework:")) {
|
||||
continue;
|
||||
}
|
||||
boolean forServices = source.startsWith(SERVICE);
|
||||
Path file = root.resolve(forServices ? source.substring(SERVICE.length()) : source);
|
||||
if (!file.toString().contains("/src/main/")
|
||||
|| !Files.isRegularFile(file)
|
||||
|| !Files.readString(file).contains("\"" + name + "\"")
|
||||
|| (forServices && !FOR_SERVICE_CONTROLLERS.contains(name))
|
||||
|| (forServices && main.valueIsUsed(file, name))
|
||||
|| (!forServices && !main.valueIsUsed(file, name))) {
|
||||
unbacked.add(name + " <- " + source);
|
||||
}
|
||||
}
|
||||
|
||||
// then
|
||||
assertThat(unbacked).isEmpty();
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("X-Request-Id·X-Correlation-Id 형식은 filter 가 받는 문법이다(ulid 가 아니다)")
|
||||
void requestAndCorrelationIdsCarryTheFiltersGrammar() {
|
||||
assertThat(List.of(row("X-Request-Id").get("type"), row("X-Correlation-Id").get("type")))
|
||||
.containsOnly("uuid-or-caller-token");
|
||||
}
|
||||
|
||||
@Test
|
||||
void rateLimitHeadersAreGeneratedOnlyInsideTheEnabledRateLimitCapability() {
|
||||
for (String name : List.of("X-RateLimit-Limit", "X-RateLimit-Remaining", "X-RateLimit-Reset")) {
|
||||
|
||||
+70
-55
@@ -18,6 +18,8 @@ import java.nio.file.Files;
|
||||
import java.nio.file.Path;
|
||||
import java.util.List;
|
||||
import java.util.Map;
|
||||
import java.util.Set;
|
||||
import java.util.TreeSet;
|
||||
import org.junit.jupiter.api.DisplayName;
|
||||
import org.junit.jupiter.api.Tag;
|
||||
import org.junit.jupiter.api.Test;
|
||||
@@ -215,82 +217,75 @@ class MetricsAlertingContractTest {
|
||||
|
||||
@Tag("document-contract")
|
||||
@Test
|
||||
@DisplayName("§테스트 계약 #1: http.server.requests row exists with method/status/uri_template tags")
|
||||
void httpServerRequestsRowExistsWithRequiredTags() throws Exception {
|
||||
@DisplayName(
|
||||
"http.server.requests 행은 Spring Framework convention 이 실제로 다는 tag(method·status·uri·outcome)를 적는다")
|
||||
void httpServerRequestsRowNamesTheTagsSpringRecords() throws Exception {
|
||||
// given
|
||||
loadRegistry();
|
||||
|
||||
// when
|
||||
Map<String, Object> row = findRow("http.server.requests");
|
||||
|
||||
// then
|
||||
assertThat(row).as("metrics.yaml must contain an 'http.server.requests' row").isNotNull();
|
||||
|
||||
List<String> tagNames = tagNames(row);
|
||||
assertThat(tagNames)
|
||||
.as("http.server.requests must have tags: method, status, uri_template")
|
||||
.contains("method", "status", "uri_template");
|
||||
assertThat(tagNames(row))
|
||||
.as("the tags Spring MVC's request observation records, not uri_template or 2xx buckets")
|
||||
.contains("method", "status", "uri", "outcome")
|
||||
.doesNotContain("uri_template");
|
||||
}
|
||||
|
||||
@Tag("document-contract")
|
||||
@Test
|
||||
@DisplayName(
|
||||
"§테스트 계약 #2: dependency.client.requests row exists with dependency_name/dependency_type tags and P1 alert")
|
||||
@SuppressWarnings(
|
||||
"unchecked") // SnakeYAML returns untyped Object; the registry shape is fixed by the
|
||||
// metrics.yaml contract
|
||||
void dependencyClientRequestsRowExistsWithRequiredTagsAndP1Alert() throws Exception {
|
||||
"outbound HTTP 행은 httpclient 가 내는 http.client.requests 이고 clientName·outcome tag 를 적는다")
|
||||
void outboundHttpRowIsTheOneTheClientRecords() throws Exception {
|
||||
// given
|
||||
loadRegistry();
|
||||
|
||||
// when
|
||||
Map<String, Object> row = findRow("http.client.requests");
|
||||
|
||||
// then
|
||||
assertThat(row).as("metrics.yaml must contain an 'http.client.requests' row").isNotNull();
|
||||
assertThat(tagNames(row)).contains("clientName", "outcome");
|
||||
}
|
||||
|
||||
@Tag("document-contract")
|
||||
@Test
|
||||
@DisplayName("아무 코드도 등록하지 않는 dependency.client.requests 행은 없다")
|
||||
void theUnregisteredDependencyClientRowIsGone() throws Exception {
|
||||
// given
|
||||
loadRegistry();
|
||||
|
||||
// when
|
||||
Map<String, Object> row = findRow("dependency.client.requests");
|
||||
assertThat(row).as("metrics.yaml must contain a 'dependency.client.requests' row").isNotNull();
|
||||
|
||||
List<String> tagNames = tagNames(row);
|
||||
assertThat(tagNames)
|
||||
.as("dependency.client.requests must have tags: dependency_name, dependency_type")
|
||||
.contains("dependency_name", "dependency_type");
|
||||
|
||||
//noinspection unchecked
|
||||
Map<String, Object> thresholds = (Map<String, Object>) row.get("alert_severity_thresholds");
|
||||
assertThat(thresholds)
|
||||
.as("dependency.client.requests must have non-empty alert_severity_thresholds (§테스트 계약 #4)")
|
||||
.isNotNull()
|
||||
.isNotEmpty();
|
||||
assertThat(thresholds)
|
||||
.as(
|
||||
"dependency.client.requests must have a P1 alert entry (§테스트 계약 #4 — dependency outage)")
|
||||
.containsKey("p1");
|
||||
// then
|
||||
assertThat(row)
|
||||
.as("no code registers dependency.client.requests; the row was removed")
|
||||
.isNull();
|
||||
}
|
||||
|
||||
@Tag("document-contract")
|
||||
@Test
|
||||
@DisplayName(
|
||||
"§테스트 계약 #3: hikaricp.connections.acquire row exists with outcome tag containing TIMEOUT and non-empty alerts")
|
||||
@DisplayName("DB pool 고갈은 HikariCP 의 hikaricp.connections.timeout counter 로 P1 경보를 건다")
|
||||
@SuppressWarnings(
|
||||
"unchecked") // SnakeYAML returns untyped Object; the registry shape is fixed by the
|
||||
// metrics.yaml contract
|
||||
void hikaricpConnectionsAcquireRowExistsWithTimeoutOutcome() throws Exception {
|
||||
void hikaricpTimeoutRowCarriesThePoolExhaustionAlert() throws Exception {
|
||||
// given
|
||||
loadRegistry();
|
||||
Map<String, Object> row = findRow("hikaricp.connections.acquire");
|
||||
|
||||
// when
|
||||
Map<String, Object> row = findRow("hikaricp.connections.timeout");
|
||||
|
||||
// then
|
||||
assertThat(row)
|
||||
.as(
|
||||
"metrics.yaml must contain a 'hikaricp.connections.acquire' row (DB pool exhaustion metric)")
|
||||
.as("metrics.yaml must contain a 'hikaricp.connections.timeout' row")
|
||||
.isNotNull();
|
||||
|
||||
//noinspection unchecked
|
||||
List<Map<String, Object>> tags = (List<Map<String, Object>>) row.get("tags");
|
||||
Map<String, Object> outcomeTag =
|
||||
tags.stream().filter(t -> "outcome".equals(t.get("name"))).findFirst().orElse(null);
|
||||
assertThat(outcomeTag)
|
||||
.as("hikaricp.connections.acquire must have an 'outcome' tag")
|
||||
.isNotNull();
|
||||
|
||||
//noinspection unchecked
|
||||
List<String> allowedValues = (List<String>) outcomeTag.get("allowed_values");
|
||||
assertThat(allowedValues)
|
||||
.as("hikaricp.connections.acquire outcome tag must contain 'TIMEOUT'")
|
||||
.contains("TIMEOUT");
|
||||
|
||||
//noinspection unchecked
|
||||
Map<String, Object> thresholds = (Map<String, Object>) row.get("alert_severity_thresholds");
|
||||
assertThat(thresholds)
|
||||
.as("hikaricp.connections.acquire must have non-empty alert_severity_thresholds")
|
||||
.isNotNull()
|
||||
.isNotEmpty();
|
||||
assertThat((Map<String, Object>) row.get("alert_severity_thresholds"))
|
||||
.as("pool exhaustion is a P1 alert")
|
||||
.containsKey("p1");
|
||||
}
|
||||
|
||||
@Tag("document-contract")
|
||||
@@ -375,6 +370,26 @@ class MetricsAlertingContractTest {
|
||||
.isNull();
|
||||
}
|
||||
|
||||
@Tag("document-contract")
|
||||
@Test
|
||||
@DisplayName("metrics.yaml 의 slo_driven 행과 MetricsDistributionMeterFilter 의 대상은 같은 집합이다")
|
||||
void theSloDrivenRowsAreExactlyTheFiltersTargets() throws Exception {
|
||||
// given
|
||||
loadRegistry();
|
||||
|
||||
// when
|
||||
Set<String> sloDrivenRows = new TreeSet<>();
|
||||
for (Map<String, Object> row : metrics) {
|
||||
if ("slo_driven".equals(row.get("histogram_buckets"))) {
|
||||
sloDrivenRows.add((String) row.get("name"));
|
||||
}
|
||||
}
|
||||
|
||||
// then
|
||||
assertThat(sloDrivenRows)
|
||||
.isEqualTo(new TreeSet<>(MetricsDistributionMeterFilter.sloDrivenTimers()));
|
||||
}
|
||||
|
||||
@Tag("document-contract")
|
||||
@Test
|
||||
@DisplayName(
|
||||
|
||||
+188
@@ -0,0 +1,188 @@
|
||||
package dev.caskeleton.bootstrap.contract;
|
||||
|
||||
import static org.assertj.core.api.Assertions.assertThat;
|
||||
|
||||
import dev.caskeleton.bootstrap.contract.support.MainSources;
|
||||
import dev.caskeleton.bootstrap.contract.support.RepositoryContractResources;
|
||||
import java.io.IOException;
|
||||
import java.io.InputStream;
|
||||
import java.nio.file.Files;
|
||||
import java.nio.file.Path;
|
||||
import java.util.ArrayList;
|
||||
import java.util.HashMap;
|
||||
import java.util.List;
|
||||
import java.util.Map;
|
||||
import java.util.Set;
|
||||
import java.util.TreeSet;
|
||||
import java.util.regex.Matcher;
|
||||
import java.util.regex.Pattern;
|
||||
import org.junit.jupiter.api.DisplayName;
|
||||
import org.junit.jupiter.api.Tag;
|
||||
import org.junit.jupiter.api.Test;
|
||||
import org.yaml.snakeyaml.Yaml;
|
||||
|
||||
/**
|
||||
* Every row of {@code docs/registries/metrics.yaml} is a meter some code registers.
|
||||
*
|
||||
* <p>A row's {@code source} is either {@code framework: …} — Spring Boot, Micrometer or HikariCP
|
||||
* registers it — or the repository path of the main file that holds the meter name as a string
|
||||
* literal. When that file only declares the name as a constant, the row also names the {@code
|
||||
* constant} and the {@code registered_by} file that uses it; a name constant nothing uses does not
|
||||
* count. In the other direction, every meter a main file registers has a row: under a literal name,
|
||||
* a constant of the same file or {@code SomeClass.CONSTANT}, through a builder, a registry
|
||||
* shortcut, the global {@code Metrics} shortcut or {@code Observation.createNotStarted}. A name
|
||||
* passed in a variable cannot be resolved and is not checked; a scan that resolves one name of each
|
||||
* form proves the scan itself still works. The registry used to list eleven meters nothing
|
||||
* registered and miss dozens that the code did (review 2026-11-12); without this check the two
|
||||
* drift apart again the first time a meter is renamed.
|
||||
*/
|
||||
@Tag("document-contract")
|
||||
class MetricsRegistryCodeAlignmentTest {
|
||||
|
||||
private static final String FRAMEWORK = "framework:";
|
||||
|
||||
/**
|
||||
* A meter registration and its name argument: a builder, a registry shortcut, the global {@code
|
||||
* Metrics} shortcut, or an observation (its timer carries the observation's name). The argument
|
||||
* is a literal, a constant, or {@code SomeClass.CONSTANT}.
|
||||
*/
|
||||
static final Pattern REGISTRATION =
|
||||
Pattern.compile(
|
||||
"(?:(?:Counter|Timer|Gauge|DistributionSummary|LongTaskTimer|FunctionCounter|FunctionTimer"
|
||||
+ "|TimeGauge|MultiGauge)\\.builder"
|
||||
+ "|\\b(?:\\w*[rR]egistry|Metrics)\\.(?:counter|timer|gauge|summary)"
|
||||
+ "|\\bObservation\\.createNotStarted)"
|
||||
+ "\\(\\s*(\"[^\"]+\"|[A-Za-z_][\\w.]*)");
|
||||
|
||||
/** A string constant that holds a dotted meter name. */
|
||||
private static final Pattern NAME_CONSTANT =
|
||||
Pattern.compile("\\b([A-Z][A-Z0-9_]*)\\s*=\\s*\"([a-z][a-z0-9_]*(?:\\.[a-z0-9_]+)+)\"");
|
||||
|
||||
@Test
|
||||
@DisplayName("metrics.yaml 의 행마다 등록하는 main 파일이 있고 그 파일에 meter 이름 글자가 있다")
|
||||
void everyRowNamesTheMainFileThatRegistersIt() throws IOException {
|
||||
// given
|
||||
RepositoryContractResources repository = RepositoryContractResources.fromSystemProperty();
|
||||
List<Map<String, Object>> rows = rows(repository);
|
||||
MainSources main = MainSources.under(repository.repositoryRoot());
|
||||
|
||||
// when
|
||||
List<String> unbacked = new ArrayList<>();
|
||||
for (Map<String, Object> row : rows) {
|
||||
String name = String.valueOf(row.get("name"));
|
||||
String source = String.valueOf(row.get("source"));
|
||||
if (source.startsWith(FRAMEWORK)) {
|
||||
continue;
|
||||
}
|
||||
Path file = repository.repositoryRoot().resolve(source);
|
||||
if (!source.startsWith("src/")
|
||||
|| !source.contains("/src/main/")
|
||||
|| !Files.isRegularFile(file)
|
||||
|| !Files.readString(file).contains("\"" + name + "\"")) {
|
||||
unbacked.add(name + " <- " + source);
|
||||
continue;
|
||||
}
|
||||
Object constant = row.get("constant");
|
||||
if (constant == null && !main.valueIsUsed(file, name)) {
|
||||
unbacked.add(name + " <- " + source + " only declares it in a constant nothing uses");
|
||||
continue;
|
||||
}
|
||||
if (constant != null) {
|
||||
String simpleConstant =
|
||||
String.valueOf(constant).substring(String.valueOf(constant).indexOf('.') + 1);
|
||||
Path user = repository.repositoryRoot().resolve(String.valueOf(row.get("registered_by")));
|
||||
if (!Files.readString(file).contains(simpleConstant + " = \"" + name + "\"")
|
||||
|| !Files.isRegularFile(user)
|
||||
|| !Files.readString(user).contains(String.valueOf(constant))) {
|
||||
unbacked.add(name + " <- " + constant + " used by " + row.get("registered_by"));
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// then
|
||||
assertThat(unbacked).as("rows whose source does not register the meter").isEmpty();
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("main 파일이 글자·상수 이름으로 등록하는 meter 는 모두 metrics.yaml 행이 있다")
|
||||
void everyMeterRegisteredUnderAResolvableNameHasARow() throws IOException {
|
||||
// given
|
||||
RepositoryContractResources repository = RepositoryContractResources.fromSystemProperty();
|
||||
Set<String> rows = new TreeSet<>();
|
||||
rows(repository).forEach(row -> rows.add(String.valueOf(row.get("name"))));
|
||||
|
||||
// when
|
||||
Set<String> registered = registeredMeters(repository);
|
||||
|
||||
// then
|
||||
assertThat(rows).containsAll(registered);
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("등록 형태마다 meter 하나씩을 찾는다 — 아무것도 못 찾는 scan 은 위 시험을 거짓으로 통과시킨다")
|
||||
void theScanResolvesOneMeterOfEachRegistrationForm() throws IOException {
|
||||
// given
|
||||
RepositoryContractResources repository = RepositoryContractResources.fromSystemProperty();
|
||||
|
||||
// when
|
||||
Set<String> registered = registeredMeters(repository);
|
||||
|
||||
// then
|
||||
assertThat(registered)
|
||||
.contains(
|
||||
"fileserver.upload.duration", // a literal builder name
|
||||
"executor.rejected.total", // a constant of the same file
|
||||
"http.client.circuit.state.rejected", // SomeClass.CONSTANT
|
||||
"log.appender.dropped.total", // the global Metrics shortcut
|
||||
"notification.callback"); // an observation
|
||||
}
|
||||
|
||||
/** Every meter name a main file registers that the scan can resolve. */
|
||||
private static Set<String> registeredMeters(RepositoryContractResources repository) {
|
||||
Map<Path, String> sources = MainSources.under(repository.repositoryRoot()).all();
|
||||
Map<String, String> qualifiedConstants = new HashMap<>();
|
||||
sources.forEach(
|
||||
(file, text) ->
|
||||
constants(text)
|
||||
.forEach(
|
||||
(constant, value) ->
|
||||
qualifiedConstants.put(
|
||||
MainSources.simpleName(file) + "." + constant, value)));
|
||||
Set<String> registered = new TreeSet<>();
|
||||
sources.forEach(
|
||||
(file, text) -> {
|
||||
Map<String, String> local = constants(text);
|
||||
Matcher matcher = REGISTRATION.matcher(text);
|
||||
while (matcher.find()) {
|
||||
String argument = matcher.group(1);
|
||||
String meter =
|
||||
argument.startsWith("\"")
|
||||
? argument.substring(1, argument.length() - 1)
|
||||
: local.getOrDefault(argument, qualifiedConstants.get(argument));
|
||||
if (meter != null) {
|
||||
registered.add(meter);
|
||||
}
|
||||
}
|
||||
});
|
||||
return registered;
|
||||
}
|
||||
|
||||
private static Map<String, String> constants(String text) {
|
||||
Map<String, String> constants = new HashMap<>();
|
||||
Matcher matcher = NAME_CONSTANT.matcher(text);
|
||||
while (matcher.find()) {
|
||||
constants.put(matcher.group(1), matcher.group(2));
|
||||
}
|
||||
return constants;
|
||||
}
|
||||
|
||||
@SuppressWarnings("unchecked") // SnakeYAML returns untyped maps; the registry shape is fixed
|
||||
private static List<Map<String, Object>> rows(RepositoryContractResources repository)
|
||||
throws IOException {
|
||||
Path registry = repository.requireTrackedFile("docs/registries/metrics.yaml");
|
||||
try (InputStream in = Files.newInputStream(registry)) {
|
||||
Map<String, Object> root = new Yaml().load(in);
|
||||
return (List<Map<String, Object>>) root.get("metrics");
|
||||
}
|
||||
}
|
||||
}
|
||||
+65
@@ -3,7 +3,9 @@ package dev.caskeleton.bootstrap.contract;
|
||||
import static org.assertj.core.api.Assertions.assertThat;
|
||||
|
||||
import dev.caskeleton.bootstrap.contract.support.RepositoryContractResources;
|
||||
import dev.caskeleton.bootstrap.logging.LogMaskingPatterns;
|
||||
import dev.caskeleton.bootstrap.runtime.SecretSourceValidator;
|
||||
import java.io.IOException;
|
||||
import java.io.InputStream;
|
||||
import java.nio.file.Files;
|
||||
import java.nio.file.Path;
|
||||
@@ -11,6 +13,7 @@ import java.util.LinkedHashSet;
|
||||
import java.util.List;
|
||||
import java.util.Map;
|
||||
import java.util.Set;
|
||||
import java.util.stream.Stream;
|
||||
import org.junit.jupiter.api.BeforeAll;
|
||||
import org.junit.jupiter.api.DisplayName;
|
||||
import org.junit.jupiter.api.Tag;
|
||||
@@ -115,4 +118,66 @@ class SecretsClassificationRegistryTest {
|
||||
.isIn(VALID_TIERS);
|
||||
}
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName(
|
||||
"masking_rule 은 LogMaskingPatterns 가 하는 셋(full·userinfo·none)뿐이다 — 구현 없는 규칙을 약속하지 않는다")
|
||||
void everyMaskingRuleIsOneTheMaskingLayerImplements() {
|
||||
// when
|
||||
Set<Object> rules = new LinkedHashSet<>();
|
||||
registryRows.forEach(row -> rules.add(row.get("masking_rule")));
|
||||
|
||||
// then
|
||||
assertThat(rules).isSubsetOf("full", "userinfo", "none");
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("required_test 는 app-bootstrap 시험 폴더에 있는 시험 클래스 이름이다")
|
||||
void everyRequiredTestNamesATestClassThatExists() throws IOException {
|
||||
// given
|
||||
Path tests =
|
||||
RepositoryContractResources.fromSystemProperty()
|
||||
.requireTrackedDirectory("src/bootstrap/app/src/test/java");
|
||||
Set<String> classNames = new LinkedHashSet<>();
|
||||
try (Stream<Path> files = Files.walk(tests)) {
|
||||
files
|
||||
.map(path -> path.getFileName().toString())
|
||||
.filter(name -> name.endsWith("Test.java"))
|
||||
.forEach(name -> classNames.add(name.substring(0, name.length() - ".java".length())));
|
||||
}
|
||||
|
||||
// when
|
||||
Set<Object> named = new LinkedHashSet<>();
|
||||
registryRows.stream()
|
||||
.map(row -> row.get("required_test"))
|
||||
.filter(java.util.Objects::nonNull)
|
||||
.forEach(named::add);
|
||||
|
||||
// then
|
||||
assertThat(classNames).containsAll(named.stream().map(String::valueOf).toList());
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("masking_rule 이 full 인 행의 NAME=값 과 userinfo 행의 URI 비밀번호는 Layer 1 가림이 실제로 가린다")
|
||||
void everyMaskingRuleIsHonouredByTheMaskingLayer() {
|
||||
// given
|
||||
String secret = "s3cr3t-Value-1234";
|
||||
|
||||
// when
|
||||
List<String> leaked = new java.util.ArrayList<>();
|
||||
for (Map<String, Object> row : registryRows) {
|
||||
String name = String.valueOf(row.get("name"));
|
||||
Object rule = row.get("masking_rule");
|
||||
String line =
|
||||
"full".equals(rule)
|
||||
? name + "=" + secret
|
||||
: "userinfo".equals(rule) ? "scheme://user:" + secret + "@host/db" : null;
|
||||
if (line != null && LogMaskingPatterns.mask(line).contains(secret)) {
|
||||
leaked.add(name);
|
||||
}
|
||||
}
|
||||
|
||||
// then
|
||||
assertThat(leaked).isEmpty();
|
||||
}
|
||||
}
|
||||
|
||||
+45
@@ -3,13 +3,17 @@ package dev.caskeleton.bootstrap.contract;
|
||||
import static org.assertj.core.api.Assertions.assertThat;
|
||||
|
||||
import dev.caskeleton.bootstrap.contract.support.RepositoryContractResources;
|
||||
import dev.caskeleton.shared.observability.MdcKeys;
|
||||
import java.io.IOException;
|
||||
import java.io.InputStream;
|
||||
import java.lang.reflect.Field;
|
||||
import java.lang.reflect.Modifier;
|
||||
import java.nio.charset.StandardCharsets;
|
||||
import java.nio.file.Files;
|
||||
import java.nio.file.Path;
|
||||
import java.util.LinkedHashSet;
|
||||
import java.util.Set;
|
||||
import java.util.TreeSet;
|
||||
import java.util.regex.Matcher;
|
||||
import java.util.regex.Pattern;
|
||||
import org.junit.jupiter.api.DisplayName;
|
||||
@@ -72,6 +76,25 @@ class StructuredLogFieldContractTest {
|
||||
.containsAll(emittedFields);
|
||||
}
|
||||
|
||||
@Tag("document-contract")
|
||||
@Test
|
||||
@DisplayName("mdc-keys.yaml 의 key 는 코드가 MDC 에 넣는 MdcKeys 상수와 같은 집합이다")
|
||||
void theRegistryListsExactlyTheKeysTheCodePutsOnMdc() throws Exception {
|
||||
// given
|
||||
Set<String> codeKeys = new TreeSet<>();
|
||||
for (Field field : MdcKeys.class.getFields()) {
|
||||
if (Modifier.isStatic(field.getModifiers()) && field.getType() == String.class) {
|
||||
codeKeys.add((String) field.get(null));
|
||||
}
|
||||
}
|
||||
|
||||
// when
|
||||
Set<String> registryKeys = new TreeSet<>(registryKeys());
|
||||
|
||||
// then
|
||||
assertThat(registryKeys).isEqualTo(codeKeys);
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("Logback은 로깅 설정을 app.logging.* 한 곳에서 읽고, 프로필·앱 이름은 env 이름으로 읽는다")
|
||||
void logbackReadsLoggingKnobsFromTheSettingsTreeAndIdentityFromTheEnvironment()
|
||||
@@ -100,6 +123,28 @@ class StructuredLogFieldContractTest {
|
||||
.contains("source=\"SPRING_PROFILES_ACTIVE\"");
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName(
|
||||
"JSON encoder 마다 profile 칸은 ResolvedProfileJsonProvider 가 쓰고 customFields 에 profile 이 없다")
|
||||
void everyJsonEncoderWritesTheProfileThroughTheResolvedProfileProvider() throws IOException {
|
||||
// given
|
||||
String logback = logbackText();
|
||||
|
||||
// when
|
||||
int encoders = occurrences(logback, "net.logstash.logback.encoder.LogstashEncoder");
|
||||
int providers =
|
||||
occurrences(logback, "dev.caskeleton.bootstrap.logging.ResolvedProfileJsonProvider");
|
||||
|
||||
// then
|
||||
assertThat(encoders).isPositive();
|
||||
assertThat(providers).isEqualTo(encoders);
|
||||
assertThat(logback).doesNotContain("\"profile\":");
|
||||
}
|
||||
|
||||
private static int occurrences(String text, String needle) {
|
||||
return text.split(Pattern.quote(needle), -1).length - 1;
|
||||
}
|
||||
|
||||
/** Distinct {@code <includeMdcKeyName>} values from the structured JSON appenders. */
|
||||
private static Set<String> includeMdcKeyNames() throws IOException {
|
||||
String logback = logbackText();
|
||||
|
||||
+89
@@ -0,0 +1,89 @@
|
||||
package dev.caskeleton.bootstrap.contract.support;
|
||||
|
||||
import java.io.IOException;
|
||||
import java.io.UncheckedIOException;
|
||||
import java.nio.file.Files;
|
||||
import java.nio.file.Path;
|
||||
import java.util.LinkedHashMap;
|
||||
import java.util.Map;
|
||||
import java.util.regex.Matcher;
|
||||
import java.util.regex.Pattern;
|
||||
import java.util.stream.Stream;
|
||||
|
||||
/**
|
||||
* The repository's main Java sources, read once, for registry tests that ask whether a name the
|
||||
* registry lists is really used by shipped code.
|
||||
*
|
||||
* <p>A registry row that points at a file holding its name only proves the name is declared. When
|
||||
* the name sits in a constant ({@code DEPRECATION = "Deprecation"}), the row is backed only if
|
||||
* something uses that constant: it appears again in its own file, or another main file names it as
|
||||
* {@code DeclaringClass.CONSTANT}.
|
||||
*/
|
||||
public final class MainSources {
|
||||
|
||||
private final Map<Path, String> sources;
|
||||
|
||||
private MainSources(Map<Path, String> sources) {
|
||||
this.sources = sources;
|
||||
}
|
||||
|
||||
/** Reads every {@code src/**}{@code /src/main/java/**}{@code .java} file under the root. */
|
||||
public static MainSources under(Path repositoryRoot) {
|
||||
Map<Path, String> sources = new LinkedHashMap<>();
|
||||
try (Stream<Path> files = Files.walk(repositoryRoot.resolve("src"))) {
|
||||
for (Path file :
|
||||
files
|
||||
.filter(path -> path.toString().endsWith(".java"))
|
||||
.filter(path -> path.toString().contains("/src/main/java/"))
|
||||
.toList()) {
|
||||
sources.put(file, Files.readString(file));
|
||||
}
|
||||
} catch (IOException failure) {
|
||||
throw new UncheckedIOException(failure);
|
||||
}
|
||||
return new MainSources(sources);
|
||||
}
|
||||
|
||||
/** File → text, in walk order. */
|
||||
public Map<Path, String> all() {
|
||||
return sources;
|
||||
}
|
||||
|
||||
/**
|
||||
* Whether {@code value}, held by {@code file}, is used: a literal that is not a constant counts
|
||||
* as used; a constant must appear again in the file or as {@code FileClass.CONSTANT} elsewhere.
|
||||
*/
|
||||
public boolean valueIsUsed(Path file, String value) {
|
||||
String text = sources.get(file);
|
||||
if (text == null) {
|
||||
return false;
|
||||
}
|
||||
Matcher declaration =
|
||||
Pattern.compile("\\b([A-Z][A-Z0-9_]*)\\s*=\\s*\"" + Pattern.quote(value) + "\"")
|
||||
.matcher(text);
|
||||
if (!declaration.find()) {
|
||||
return true;
|
||||
}
|
||||
String constant = declaration.group(1);
|
||||
if (occurrences(text, constant) > 1) {
|
||||
return true;
|
||||
}
|
||||
String qualified = simpleName(file) + "." + constant;
|
||||
return sources.values().stream().anyMatch(other -> other.contains(qualified));
|
||||
}
|
||||
|
||||
/** The simple class name of a source file. */
|
||||
public static String simpleName(Path file) {
|
||||
String name = file.getFileName().toString();
|
||||
return name.substring(0, name.length() - ".java".length());
|
||||
}
|
||||
|
||||
private static int occurrences(String text, String identifier) {
|
||||
Matcher uses = Pattern.compile("\\b" + Pattern.quote(identifier) + "\\b").matcher(text);
|
||||
int count = 0;
|
||||
while (uses.find()) {
|
||||
count++;
|
||||
}
|
||||
return count;
|
||||
}
|
||||
}
|
||||
+59
@@ -0,0 +1,59 @@
|
||||
package dev.caskeleton.bootstrap.contract.support;
|
||||
|
||||
import static org.assertj.core.api.Assertions.assertThat;
|
||||
|
||||
import java.io.IOException;
|
||||
import java.nio.file.Files;
|
||||
import java.nio.file.Path;
|
||||
import java.util.List;
|
||||
import org.junit.jupiter.api.DisplayName;
|
||||
import org.junit.jupiter.api.Test;
|
||||
import org.junit.jupiter.api.io.TempDir;
|
||||
|
||||
class MainSourcesTest {
|
||||
|
||||
@TempDir Path root;
|
||||
|
||||
@Test
|
||||
@DisplayName("이름을 선언만 한 상수는 쓰이지 않은 것이고, 같은 파일이나 다른 파일의 Class.CONST 로 쓰면 쓰인 것이다")
|
||||
void aDeclaredOnlyConstantIsNotUsedButOneReferencedAnywhereIs() throws IOException {
|
||||
// given
|
||||
Path names =
|
||||
write(
|
||||
"src/lib/src/main/java/demo/Names.java",
|
||||
"""
|
||||
class Names {
|
||||
static final String DECLARED = "declared.only";
|
||||
static final String LOCAL = "used.here";
|
||||
static final String SHARED = "used.elsewhere";
|
||||
void record() { count(LOCAL); }
|
||||
void count(String name) {}
|
||||
String literal() { return "no.constant"; }
|
||||
}
|
||||
""");
|
||||
write(
|
||||
"src/app/src/main/java/demo/Recorder.java",
|
||||
"class Recorder { void record() { new Names().count(Names.SHARED); } }\n");
|
||||
write(
|
||||
"src/lib/src/test/java/demo/NamesTest.java",
|
||||
"class NamesTest { void t() { new Names().count(Names.DECLARED); } }\n");
|
||||
MainSources main = MainSources.under(root);
|
||||
|
||||
// when
|
||||
List<Boolean> used =
|
||||
List.of(
|
||||
main.valueIsUsed(names, "declared.only"),
|
||||
main.valueIsUsed(names, "used.here"),
|
||||
main.valueIsUsed(names, "used.elsewhere"),
|
||||
main.valueIsUsed(names, "no.constant"));
|
||||
|
||||
// then
|
||||
assertThat(used).containsExactly(false, true, true, true);
|
||||
}
|
||||
|
||||
private Path write(String relative, String text) throws IOException {
|
||||
Path file = root.resolve(relative);
|
||||
Files.createDirectories(file.getParent());
|
||||
return Files.writeString(file, text);
|
||||
}
|
||||
}
|
||||
+93
@@ -2,7 +2,11 @@ package dev.caskeleton.bootstrap.logging;
|
||||
|
||||
import static org.assertj.core.api.Assertions.assertThat;
|
||||
|
||||
import org.junit.jupiter.api.DisplayName;
|
||||
import org.junit.jupiter.api.Test;
|
||||
import org.junit.jupiter.params.ParameterizedTest;
|
||||
import org.junit.jupiter.params.provider.CsvSource;
|
||||
import org.junit.jupiter.params.provider.ValueSource;
|
||||
|
||||
/**
|
||||
* Guards the Redaction Layer 1 secret catalog (feature-log-management-contract 테스트 계약:
|
||||
@@ -76,4 +80,93 @@ class LogMaskingPatternsTest {
|
||||
Object number = 42;
|
||||
assertThat(LogMaskingPatterns.valueMasker().mask(null, number)).isSameAs(number);
|
||||
}
|
||||
|
||||
@ParameterizedTest
|
||||
@CsvSource(
|
||||
delimiter = '|',
|
||||
value = {
|
||||
"connecting to jdbc:postgresql://app:hunter2@db:5432/ca | connecting to jdbc:postgresql://app:****@db:5432/ca",
|
||||
"uri=mongodb+srv://reader:s3cr3t-pw@cluster0.example.net/app | uri=mongodb+srv://reader:****@cluster0.example.net/app",
|
||||
"redis://default:pw@cache:6379 | redis://default:****@cache:6379",
|
||||
"redis://:pw@cache:6379 | redis://:****@cache:6379",
|
||||
"jdbc:postgresql://app:it's-a-secret@db/ca | jdbc:postgresql://app:****@db/ca",
|
||||
"jdbc:postgresql://app:p@ss@db:5432/ca | jdbc:postgresql://app:****@db:5432/ca",
|
||||
"redis://default:Ab/cd+ef@cache:6379 | redis://default:****@cache:6379",
|
||||
"redis://default:P#ssw0rd@cache:6379 | redis://default:****@cache:6379",
|
||||
"redis://default:pa?ss@cache:6379 | redis://default:****@cache:6379",
|
||||
"redis://u:pw@h,redis://u2:pw2@h2 | redis://u:****@h,redis://u2:****@h2",
|
||||
"mongodb://u:p@h1:27017,h2:27017/db | mongodb://u:****@h1:27017,h2:27017/db"
|
||||
})
|
||||
@DisplayName("URI 사용자 정보의 비밀번호를 가리고 사용자 이름은 남긴다(secrets registry 의 userinfo 규칙)")
|
||||
void masksThePasswordInAUrisUserinfo(String line, String masked) {
|
||||
assertThat(LogMaskingPatterns.mask(line)).isEqualTo(masked);
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("PEM 블록은 여러 줄이어도 BEGIN·END 사이를 모두 가린다 — 첫 공백에서 멈추지 않는다")
|
||||
void masksAWholePemBlockAcrossLines() {
|
||||
// given
|
||||
String line =
|
||||
"trust_pem=-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0BAQEFAASC\nSECRETBODY\n"
|
||||
+ "-----END PRIVATE KEY----- loaded";
|
||||
|
||||
// when
|
||||
String masked = LogMaskingPatterns.mask(line);
|
||||
|
||||
// then
|
||||
assertThat(masked)
|
||||
.doesNotContain("MIIEvQIBADANBgkqhkiG9w0BAQEFAASC", "SECRETBODY")
|
||||
.contains("-----END PRIVATE KEY----- loaded");
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("END 가 없는 PEM 블록은 BEGIN 줄만 남기고 끝까지 가린다")
|
||||
void masksAPemBlockCutShortToTheEnd() {
|
||||
// when
|
||||
String masked =
|
||||
LogMaskingPatterns.mask(
|
||||
"key=-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0BAQEFAASC\nSECRETBODY");
|
||||
|
||||
// then
|
||||
assertThat(masked).isEqualTo("key=-----BEGIN PRIVATE KEY-----****");
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("다른 라벨의 END 만 있는 PEM 블록도 BEGIN 줄만 남기고 끝까지 가린다")
|
||||
void masksAPemBlockClosedUnderAnotherLabelToTheEnd() {
|
||||
// when
|
||||
String masked =
|
||||
LogMaskingPatterns.mask(
|
||||
"-----BEGIN RSA PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0BAQEFAASC\n"
|
||||
+ "-----END PRIVATE KEY-----\nSECRETBODY");
|
||||
|
||||
// then
|
||||
assertThat(masked).isEqualTo("-----BEGIN RSA PRIVATE KEY-----****");
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("공백 없는 긴 줄도 가림 규칙이 선형으로 끝난다 — 줄 길이의 제곱으로 느려지지 않는다")
|
||||
void aLongLineWithoutSpacesIsMaskedInLinearTime() {
|
||||
// given
|
||||
String line = "a://:".repeat(32_000) + "http://h:1/".repeat(15_000) + "a".repeat(40_000);
|
||||
|
||||
// when
|
||||
long started = System.nanoTime();
|
||||
LogMaskingPatterns.mask(line);
|
||||
long elapsedMillis = (System.nanoTime() - started) / 1_000_000;
|
||||
|
||||
// then
|
||||
assertThat(elapsedMillis).as("masking a 365 KB line").isLessThan(1_000);
|
||||
}
|
||||
|
||||
@ParameterizedTest
|
||||
@ValueSource(
|
||||
strings = {
|
||||
"calling https://api.example.com:8443/v1/things",
|
||||
"calling https://api.example.com:8443/v1/users?email=a@b.example",
|
||||
"GET http://localhost:8080/v1/users/alice@example.com"
|
||||
})
|
||||
void aUriWithoutUserinfoIsUntouched(String line) {
|
||||
assertThat(LogMaskingPatterns.mask(line)).isSameAs(line);
|
||||
}
|
||||
}
|
||||
|
||||
+56
@@ -0,0 +1,56 @@
|
||||
package dev.caskeleton.bootstrap.logging;
|
||||
|
||||
import static org.assertj.core.api.Assertions.assertThat;
|
||||
|
||||
import ch.qos.logback.classic.LoggerContext;
|
||||
import ch.qos.logback.classic.spi.LoggingEvent;
|
||||
import com.fasterxml.jackson.core.JsonFactory;
|
||||
import com.fasterxml.jackson.core.JsonGenerator;
|
||||
import java.io.IOException;
|
||||
import java.io.StringWriter;
|
||||
import org.junit.jupiter.api.DisplayName;
|
||||
import org.junit.jupiter.api.Test;
|
||||
|
||||
class ResolvedProfileJsonProviderTest {
|
||||
|
||||
@Test
|
||||
@DisplayName("JSON profile 칸은 줄을 쓸 때의 context 속성이다 — 기동 중 바로잡은 profile 이 그 뒤 줄에 실린다")
|
||||
void theFieldFollowsThePropertyCorrectedAfterConfiguration() throws IOException {
|
||||
// given
|
||||
LoggerContext context = new LoggerContext();
|
||||
context.putProperty(ResolvedProfileLoggingContextListener.PROFILE_PROPERTY, "prod");
|
||||
ResolvedProfileJsonProvider provider = new ResolvedProfileJsonProvider();
|
||||
provider.setContext(context);
|
||||
provider.start();
|
||||
context.putProperty(ResolvedProfileLoggingContextListener.PROFILE_PROPERTY, "dev");
|
||||
|
||||
// when
|
||||
String json = written(provider);
|
||||
|
||||
// then
|
||||
assertThat(json).isEqualTo("{\"profile\":\"dev\"}");
|
||||
}
|
||||
|
||||
@Test
|
||||
void aContextWithoutTheProfileSaysUnresolved() throws IOException {
|
||||
// given
|
||||
ResolvedProfileJsonProvider provider = new ResolvedProfileJsonProvider();
|
||||
provider.setContext(new LoggerContext());
|
||||
|
||||
// when
|
||||
String json = written(provider);
|
||||
|
||||
// then
|
||||
assertThat(json).isEqualTo("{\"profile\":\"unresolved\"}");
|
||||
}
|
||||
|
||||
private static String written(ResolvedProfileJsonProvider provider) throws IOException {
|
||||
StringWriter out = new StringWriter();
|
||||
try (JsonGenerator generator = new JsonFactory().createGenerator(out)) {
|
||||
generator.writeStartObject();
|
||||
provider.writeTo(generator, new LoggingEvent());
|
||||
generator.writeEndObject();
|
||||
}
|
||||
return out.toString();
|
||||
}
|
||||
}
|
||||
+61
@@ -5,7 +5,11 @@ import static org.assertj.core.api.Assertions.assertThat;
|
||||
import ch.qos.logback.classic.Level;
|
||||
import ch.qos.logback.classic.LoggerContext;
|
||||
import ch.qos.logback.core.spi.FilterReply;
|
||||
import org.junit.jupiter.api.DisplayName;
|
||||
import org.junit.jupiter.api.Test;
|
||||
import org.junit.jupiter.params.ParameterizedTest;
|
||||
import org.junit.jupiter.params.provider.ValueSource;
|
||||
import org.slf4j.MarkerFactory;
|
||||
|
||||
/**
|
||||
* Tests the level-aware log sampler (feature-log-management-contract §Sampling Policy, D5/D8):
|
||||
@@ -71,4 +75,61 @@ class SamplingTurboFilterTest {
|
||||
assertThat(negative.getRate()).isEqualTo(1.0);
|
||||
assertThat(decide(negative, Level.INFO)).isEqualTo(FilterReply.NEUTRAL);
|
||||
}
|
||||
|
||||
@ParameterizedTest
|
||||
@ValueSource(
|
||||
strings = {"notification.audit", "dev.caskeleton.fileserver.audit", "notification.security"})
|
||||
@DisplayName("감사·보안 logger 의 INFO 는 표본 비율 0 에서도 버리지 않는다")
|
||||
void auditAndSecurityLoggersAreNeverSampled(String loggerName) {
|
||||
// given
|
||||
SamplingTurboFilter filter = started(0.0);
|
||||
LoggerContext context = new LoggerContext();
|
||||
|
||||
// when
|
||||
FilterReply reply =
|
||||
filter.decide(null, context.getLogger(loggerName), Level.INFO, "msg", null, null);
|
||||
|
||||
// then
|
||||
assertThat(reply).isEqualTo(FilterReply.NEUTRAL);
|
||||
}
|
||||
|
||||
@Test
|
||||
void aLineMarkedAuditIsNeverSampled() {
|
||||
// given
|
||||
SamplingTurboFilter filter = started(0.0);
|
||||
LoggerContext context = new LoggerContext();
|
||||
|
||||
// when
|
||||
FilterReply reply =
|
||||
filter.decide(
|
||||
MarkerFactory.getMarker(SamplingTurboFilter.AUDIT_MARKER),
|
||||
context.getLogger("dev.caskeleton.feature.Orders"),
|
||||
Level.INFO,
|
||||
"msg",
|
||||
null,
|
||||
null);
|
||||
|
||||
// then
|
||||
assertThat(reply).isEqualTo(FilterReply.NEUTRAL);
|
||||
}
|
||||
|
||||
@ParameterizedTest
|
||||
@ValueSource(
|
||||
strings = {
|
||||
"dev.caskeleton.feature.Orders",
|
||||
"org.springframework.security.web.FilterChainProxy"
|
||||
})
|
||||
@DisplayName("마지막 마디가 audit·security 가 아닌 logger 는 표본 대상이다(라이브러리 security 패키지 포함)")
|
||||
void anOrdinaryLoggerIsStillSampled(String loggerName) {
|
||||
// given
|
||||
SamplingTurboFilter filter = started(0.0);
|
||||
|
||||
// when
|
||||
FilterReply reply =
|
||||
filter.decide(
|
||||
null, new LoggerContext().getLogger(loggerName), Level.INFO, "msg", null, null);
|
||||
|
||||
// then
|
||||
assertThat(reply).isEqualTo(FilterReply.DENY);
|
||||
}
|
||||
}
|
||||
|
||||
+35
-12
@@ -10,7 +10,12 @@ import dev.caskeleton.application.fileserver.recovery.FileReconciliationService;
|
||||
import dev.caskeleton.application.fileserver.recovery.ReconcileRecoverableFilesCommand;
|
||||
import dev.caskeleton.application.fileserver.recovery.ReconcileRecoverableFilesUseCase;
|
||||
import dev.caskeleton.application.fileserver.recovery.ReconciliationResult;
|
||||
import dev.caskeleton.shared.error.ApiErrorCarrier;
|
||||
import dev.caskeleton.shared.error.ApiErrorCode;
|
||||
import dev.caskeleton.shared.error.ServerFailureLog;
|
||||
import java.util.Arrays;
|
||||
import java.util.List;
|
||||
import java.util.Optional;
|
||||
import org.slf4j.Logger;
|
||||
import org.slf4j.LoggerFactory;
|
||||
|
||||
@@ -82,13 +87,8 @@ public final class FileserverCleanupWorker {
|
||||
kv("reconcile.examined", results.size()));
|
||||
}
|
||||
} catch (RuntimeException failure) {
|
||||
LOG.warn(
|
||||
"fileserver.reconcile pass failed; the next run looks again",
|
||||
kv("capability", "fileserver"),
|
||||
kv("operation", "reconcile"),
|
||||
kv("warning.kind", "scheduled-task-failed"),
|
||||
kv("retry.disposition", "next-run"),
|
||||
failure);
|
||||
logPassFailure(
|
||||
"fileserver.reconcile pass failed; the next run looks again", "reconcile", failure);
|
||||
}
|
||||
}
|
||||
|
||||
@@ -113,13 +113,36 @@ public final class FileserverCleanupWorker {
|
||||
kv("cleanup.reclaimed_bytes", result.reclaimedBytes()));
|
||||
}
|
||||
} catch (RuntimeException failure) {
|
||||
LOG.warn(
|
||||
logPassFailure(
|
||||
"fileserver.cleanup batch failed; the next run retries the same queue",
|
||||
kv("capability", "fileserver"),
|
||||
kv("operation", "cleanup"),
|
||||
kv("warning.kind", "scheduled-task-failed"),
|
||||
kv("retry.disposition", "next-run"),
|
||||
"cleanup",
|
||||
failure);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* One WARN line per failed pass. A classified failure is written as every transport writes it
|
||||
* ({@link ServerFailureLog}): a persistence failure by its classification only, because its cause
|
||||
* holds SQL, constraint names and values; any other carrier, client-side code included, with its
|
||||
* stack ({@link ServerFailureLog#forBackgroundTask}). The whole exception used to be attached
|
||||
* whatever it was (review 2026-11-12). An unclassified failure is a defect and keeps its stack.
|
||||
*/
|
||||
private static void logPassFailure(String message, String operation, RuntimeException failure) {
|
||||
Object[] fields = {
|
||||
kv("capability", "fileserver"),
|
||||
kv("operation", operation),
|
||||
kv("warning.kind", "scheduled-task-failed"),
|
||||
kv("retry.disposition", "next-run")
|
||||
};
|
||||
Optional<Throwable> carrier = ApiErrorCarrier.firstIn(failure);
|
||||
if (carrier.isPresent()) {
|
||||
ApiErrorCode code = ((ApiErrorCarrier) carrier.get()).errorCode();
|
||||
ServerFailureLog line = ServerFailureLog.forBackgroundTask(carrier.get(), code);
|
||||
LOG.warn(line.format("; " + message), line.arguments(fields));
|
||||
return;
|
||||
}
|
||||
Object[] withFailure = Arrays.copyOf(fields, fields.length + 1);
|
||||
withFailure[fields.length] = failure;
|
||||
LOG.warn(message, withFailure);
|
||||
}
|
||||
}
|
||||
|
||||
+45
@@ -1,14 +1,23 @@
|
||||
package dev.caskeleton.composition.fileserver;
|
||||
|
||||
import static org.assertj.core.api.Assertions.assertThat;
|
||||
import static org.assertj.core.api.Assertions.tuple;
|
||||
|
||||
import ch.qos.logback.classic.Level;
|
||||
import ch.qos.logback.classic.Logger;
|
||||
import ch.qos.logback.classic.spi.ILoggingEvent;
|
||||
import ch.qos.logback.core.read.ListAppender;
|
||||
import dev.caskeleton.application.fileserver.api.FileId;
|
||||
import dev.caskeleton.application.fileserver.cleanup.CleanupBatchResult;
|
||||
import dev.caskeleton.application.fileserver.recovery.FileReconciliationService;
|
||||
import dev.caskeleton.application.fileserver.recovery.ReconciliationResult;
|
||||
import dev.caskeleton.shared.error.OperationalError;
|
||||
import dev.caskeleton.shared.error.PersistenceFailureException;
|
||||
import java.util.ArrayList;
|
||||
import java.util.List;
|
||||
import org.junit.jupiter.api.DisplayName;
|
||||
import org.junit.jupiter.api.Test;
|
||||
import org.slf4j.LoggerFactory;
|
||||
|
||||
class FileserverCleanupWorkerTest {
|
||||
|
||||
@@ -61,4 +70,40 @@ class FileserverCleanupWorkerTest {
|
||||
// then
|
||||
assertThat(reconciled).containsExactly(25);
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("분류된 persistence 실패는 분류만 WARN 으로 남기고 SQL·값을 담은 원인 사슬을 붙이지 않는다")
|
||||
void aClassifiedCleanupFailureIsLoggedWithoutItsCause() {
|
||||
// given
|
||||
FileserverCleanupWorker worker =
|
||||
new FileserverCleanupWorker(
|
||||
(maxItems, maxBytes) -> {
|
||||
throw new PersistenceFailureException(
|
||||
OperationalError.DB_UNAVAILABLE,
|
||||
"SECRET_SQL delete from file_metadata where id=7",
|
||||
new IllegalStateException("SECRET_SQL cause"));
|
||||
},
|
||||
reconciliation,
|
||||
25,
|
||||
1024);
|
||||
Logger logger = (Logger) LoggerFactory.getLogger(FileserverCleanupWorker.class);
|
||||
ListAppender<ILoggingEvent> appender = new ListAppender<>();
|
||||
appender.start();
|
||||
logger.addAppender(appender);
|
||||
|
||||
// when
|
||||
try {
|
||||
worker.runBatch();
|
||||
} finally {
|
||||
logger.detachAppender(appender);
|
||||
}
|
||||
|
||||
// then
|
||||
assertThat(appender.list)
|
||||
.extracting(
|
||||
ILoggingEvent::getLevel,
|
||||
event -> event.getFormattedMessage().contains("SECRET_SQL"),
|
||||
event -> event.getThrowableProxy() == null)
|
||||
.containsExactly(tuple(Level.WARN, false, true));
|
||||
}
|
||||
}
|
||||
|
||||
@@ -19,6 +19,9 @@ dependencies {
|
||||
implementation project(':application-core')
|
||||
// StrictSettingsBinder, the typed startup failures and the runtime warning fields.
|
||||
implementation project(':adapter:outbound:support')
|
||||
// ApiErrorCarrier and ServerFailureLog: a failed relay tick is logged the way every transport
|
||||
// logs a classified failure, without the SQL a persistence failure's cause holds.
|
||||
implementation project(':shared-contract')
|
||||
|
||||
implementation 'org.springframework.boot:spring-boot-autoconfigure'
|
||||
implementation 'org.springframework:spring-context'
|
||||
|
||||
+34
-7
@@ -5,6 +5,11 @@ import static net.logstash.logback.argument.StructuredArguments.kv;
|
||||
import dev.caskeleton.application.outbox.OutboxRelayResult;
|
||||
import dev.caskeleton.application.outbox.PublishPendingOutboxEventsCommand;
|
||||
import dev.caskeleton.application.outbox.PublishPendingOutboxEventsUseCase;
|
||||
import dev.caskeleton.shared.error.ApiErrorCarrier;
|
||||
import dev.caskeleton.shared.error.ApiErrorCode;
|
||||
import dev.caskeleton.shared.error.ServerFailureLog;
|
||||
import java.util.Arrays;
|
||||
import java.util.Optional;
|
||||
import org.slf4j.Logger;
|
||||
import org.slf4j.LoggerFactory;
|
||||
import org.springframework.context.SmartLifecycle;
|
||||
@@ -112,16 +117,38 @@ public class OutboxRelayScheduler implements SmartLifecycle {
|
||||
} while (!stopRequested && result.publishedAny() && cycles < MAX_CYCLES_PER_TICK);
|
||||
|
||||
} catch (Exception ex) {
|
||||
log.error(
|
||||
"outbox relay scheduler: unexpected error in relay cycle — "
|
||||
+ "relay will retry on the next tick",
|
||||
kv("capability", "outbox"),
|
||||
kv("operation", "relay"),
|
||||
kv("retry.disposition", "next-tick"),
|
||||
ex);
|
||||
logRelayFailure(ex);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* One line per failed tick. A classified failure is written as every transport writes it ({@link
|
||||
* ServerFailureLog}): a persistence failure by its classification only, because its cause holds
|
||||
* SQL, constraint names and values; any other carrier, client-side code included, with its stack
|
||||
* ({@link ServerFailureLog#forBackgroundTask}). The whole exception used to be attached whatever
|
||||
* it was (review 2026-11-12). An unclassified failure is a defect and keeps its stack.
|
||||
*/
|
||||
private static void logRelayFailure(Exception failure) {
|
||||
Object[] fields = {
|
||||
kv("capability", "outbox"), kv("operation", "relay"), kv("retry.disposition", "next-tick")
|
||||
};
|
||||
Optional<Throwable> carrier = ApiErrorCarrier.firstIn(failure);
|
||||
if (carrier.isPresent()) {
|
||||
ApiErrorCode code = ((ApiErrorCarrier) carrier.get()).errorCode();
|
||||
ServerFailureLog line = ServerFailureLog.forBackgroundTask(carrier.get(), code);
|
||||
log.error(
|
||||
line.format(" in an outbox relay cycle; the relay retries on the next tick"),
|
||||
line.arguments(fields));
|
||||
return;
|
||||
}
|
||||
Object[] withFailure = Arrays.copyOf(fields, fields.length + 1);
|
||||
withFailure[fields.length] = failure;
|
||||
log.error(
|
||||
"outbox relay scheduler: unexpected error in relay cycle — "
|
||||
+ "relay will retry on the next tick",
|
||||
withFailure);
|
||||
}
|
||||
|
||||
@Override
|
||||
public void start() {
|
||||
synchronized (monitor) {
|
||||
|
||||
+76
@@ -12,8 +12,14 @@ import ch.qos.logback.classic.spi.ILoggingEvent;
|
||||
import ch.qos.logback.core.read.ListAppender;
|
||||
import dev.caskeleton.application.outbox.PublishPendingOutboxEventsCommand;
|
||||
import dev.caskeleton.application.outbox.PublishPendingOutboxEventsUseCase;
|
||||
import dev.caskeleton.shared.error.ApiErrorCarrier;
|
||||
import dev.caskeleton.shared.error.ApiErrorCode;
|
||||
import dev.caskeleton.shared.error.OperationalError;
|
||||
import dev.caskeleton.shared.error.PersistenceFailureException;
|
||||
import java.util.Arrays;
|
||||
import java.util.List;
|
||||
import java.util.stream.Collectors;
|
||||
import org.junit.jupiter.api.DisplayName;
|
||||
import org.junit.jupiter.api.Test;
|
||||
import org.slf4j.LoggerFactory;
|
||||
|
||||
@@ -44,6 +50,63 @@ class OutboxRelaySchedulerLoggingTest {
|
||||
}
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("분류된 persistence 실패는 분류만 남기고 SQL·값을 담은 원인 사슬을 붙이지 않는다")
|
||||
void aPersistenceFailureIsLoggedByItsClassificationWithoutItsCause() {
|
||||
// given
|
||||
PublishPendingOutboxEventsUseCase relay = mock(PublishPendingOutboxEventsUseCase.class);
|
||||
when(relay.handle(any(PublishPendingOutboxEventsCommand.class)))
|
||||
.thenThrow(
|
||||
new PersistenceFailureException(
|
||||
OperationalError.DB_UNAVAILABLE,
|
||||
"SECRET_SQL select * from outbox where tenant='acme'",
|
||||
new IllegalStateException("SECRET_SQL cause")));
|
||||
OutboxRelayScheduler scheduler = new OutboxRelayScheduler(relay, mock(OutboxMetrics.class));
|
||||
scheduler.start();
|
||||
|
||||
// when
|
||||
ILoggingEvent event;
|
||||
try (CapturedLogger captured = capture(OutboxRelayScheduler.class)) {
|
||||
scheduler.relay();
|
||||
event = captured.singleEvent();
|
||||
}
|
||||
|
||||
// then
|
||||
assertThat(
|
||||
List.of(
|
||||
event.getFormattedMessage().contains("SECRET_SQL"),
|
||||
event.getThrowableProxy() == null,
|
||||
event
|
||||
.getFormattedMessage()
|
||||
.startsWith("persistence failure classified as DB_UNAVAILABLE")))
|
||||
.containsExactly(false, true, true);
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("client 쪽 코드를 실은 실패도 스케줄러에서는 결함이라 stack 과 함께 분류해 남긴다")
|
||||
void aClientSideCarrierInARelayCycleKeepsItsStack() {
|
||||
// given
|
||||
PublishPendingOutboxEventsUseCase relay = mock(PublishPendingOutboxEventsUseCase.class);
|
||||
RuntimeException failure = new ClientSideCarrier();
|
||||
when(relay.handle(any(PublishPendingOutboxEventsCommand.class))).thenThrow(failure);
|
||||
OutboxRelayScheduler scheduler = new OutboxRelayScheduler(relay, mock(OutboxMetrics.class));
|
||||
scheduler.start();
|
||||
|
||||
// when
|
||||
ILoggingEvent event;
|
||||
try (CapturedLogger captured = capture(OutboxRelayScheduler.class)) {
|
||||
scheduler.relay();
|
||||
event = captured.singleEvent();
|
||||
}
|
||||
|
||||
// then
|
||||
assertThat(event)
|
||||
.extracting(
|
||||
e -> e.getFormattedMessage().startsWith("failure classified as BAD_PARAMETER"),
|
||||
e -> e.getThrowableProxy() == null ? null : e.getThrowableProxy().getClassName())
|
||||
.containsExactly(true, ClientSideCarrier.class.getName());
|
||||
}
|
||||
|
||||
private static CapturedLogger capture(Class<?> owner) {
|
||||
Logger logger = (Logger) LoggerFactory.getLogger(owner);
|
||||
ListAppender<ILoggingEvent> appender = new ListAppender<>();
|
||||
@@ -61,6 +124,19 @@ class OutboxRelaySchedulerLoggingTest {
|
||||
return Arrays.stream(arguments).map(String::valueOf).collect(Collectors.joining(" | "));
|
||||
}
|
||||
|
||||
private static final class ClientSideCarrier extends RuntimeException implements ApiErrorCarrier {
|
||||
private static final long serialVersionUID = 1L;
|
||||
|
||||
ClientSideCarrier() {
|
||||
super("a client-side code raised by server code");
|
||||
}
|
||||
|
||||
@Override
|
||||
public ApiErrorCode errorCode() {
|
||||
return OperationalError.BAD_PARAMETER;
|
||||
}
|
||||
}
|
||||
|
||||
private record CapturedLogger(Logger logger, ListAppender<ILoggingEvent> appender)
|
||||
implements AutoCloseable {
|
||||
|
||||
|
||||
@@ -210,12 +210,10 @@ runtimeOnly project(':composition:service-runtime')
|
||||
`SimpleMeterRegistry`에 대해 직접 구동할 수 있게 하기 위함이다.
|
||||
|
||||
#### MetricsDistributionMeterFilter
|
||||
- **소유한(owned) 타이머 메트릭 5종에만 SLO 기반 히스토그램·백분위 설정을 적용한다.** 대상:
|
||||
`http.server.requests`, `http.server.requests.latency`, `dependency.client.requests`,
|
||||
`db.query.duration`, `jvm.gc.pause`. 이들은 `metrics.yaml`에서 이 브랜치가 소유하고
|
||||
`histogram_buckets: slo_driven`인 행이다. `resilience4j.circuitbreaker.calls`,
|
||||
`hikaricp.connections.acquire`처럼 소비만 하고 소유하지 않는(consumed-but-not-owned) 행은 다른
|
||||
브랜치 소유라 의도적으로 제외 — 덮어쓰면 안 된다.
|
||||
- **소유한(owned) 타이머 메트릭 둘에만 SLO 기반 히스토그램·백분위 설정을 적용한다.** 대상:
|
||||
`http.server.requests`, `jvm.gc.pause`. `metrics.yaml`에서 `histogram_buckets: slo_driven`인 행은 정확히 이 둘이다
|
||||
(`MetricsAlertingContractTest`가 두 집합을 대조한다). `hikaricp.connections.acquire`처럼 다른 라이브러리가 내는 timer는
|
||||
histogram을 켜지 않고, 그 행은 평균(sum/count)으로 경보를 적는다.
|
||||
- **히스토그램 전략은 두 축이다.**
|
||||
- *인스턴스 간 집계 가능한 진실의 원천*: `percentilesHistogram(true)`(= `publishPercentileHistogram`)가
|
||||
`_bucket` 시계열을 생성하고, Prometheus 에서 `histogram_quantile()`로 인스턴스 간 집계할 수 있다.
|
||||
|
||||
+15
-6
@@ -15,18 +15,27 @@ import java.util.Set;
|
||||
*/
|
||||
public final class MetricsDistributionMeterFilter implements MeterFilter {
|
||||
|
||||
/**
|
||||
* The owned timers some code registers. Three more names stood here — {@code
|
||||
* http.server.requests.latency}, {@code dependency.client.requests}, {@code db.query.duration} —
|
||||
* that nothing registered, so the filter configured meters that never existed (review
|
||||
* 2026-11-12). Latency alerts use {@code http.server.requests}.
|
||||
*/
|
||||
private static final Set<String> SLO_DRIVEN_TIMERS =
|
||||
Set.of(
|
||||
"http.server.requests",
|
||||
"http.server.requests.latency",
|
||||
"dependency.client.requests",
|
||||
"db.query.duration",
|
||||
"jvm.gc.pause");
|
||||
Set.of("http.server.requests", "jvm.gc.pause");
|
||||
|
||||
public MetricsDistributionMeterFilter() {
|
||||
// public no-arg constructor — required by MetricsContractConfig.install()
|
||||
}
|
||||
|
||||
/**
|
||||
* The timers this filter gives an SLO histogram; {@code docs/registries/metrics.yaml} marks
|
||||
* exactly these {@code slo_driven}.
|
||||
*/
|
||||
public static Set<String> sloDrivenTimers() {
|
||||
return SLO_DRIVEN_TIMERS;
|
||||
}
|
||||
|
||||
@Override
|
||||
public DistributionStatisticConfig configure(Meter.Id id, DistributionStatisticConfig config) {
|
||||
if (!SLO_DRIVEN_TIMERS.contains(id.getName())) {
|
||||
|
||||
+3
-3
@@ -113,9 +113,9 @@ class MetricsContractConfigTest {
|
||||
.isNull();
|
||||
|
||||
// Clean metric: registered (D9 applied for timers)
|
||||
registry.timer("db.query.duration", "operation", "select", "outcome", "SUCCESS");
|
||||
assertThat(registry.find("db.query.duration").timer())
|
||||
.as("db.query.duration timer with clean tags must be registered")
|
||||
registry.timer("http.server.requests", "method", "GET", "outcome", "SUCCESS");
|
||||
assertThat(registry.find("http.server.requests").timer())
|
||||
.as("http.server.requests timer with clean tags must be registered")
|
||||
.isNotNull();
|
||||
}
|
||||
}
|
||||
|
||||
+4
-32
@@ -26,14 +26,7 @@ class MetricsDistributionMeterFilterTest {
|
||||
// ----------------------------------------------------------------
|
||||
|
||||
@ParameterizedTest(name = "D9: configure() applies SLO histogram to owned timer ''{0}''")
|
||||
@ValueSource(
|
||||
strings = {
|
||||
"http.server.requests",
|
||||
"http.server.requests.latency",
|
||||
"dependency.client.requests",
|
||||
"db.query.duration",
|
||||
"jvm.gc.pause"
|
||||
})
|
||||
@ValueSource(strings = {"http.server.requests", "jvm.gc.pause"})
|
||||
void configureAppliesSloHistogramToOwnedTimers(String metricName) {
|
||||
Meter.Id id = new Meter.Id(metricName, Tags.empty(), null, null, Meter.Type.TIMER);
|
||||
DistributionStatisticConfig result = filter.configure(id, DistributionStatisticConfig.DEFAULT);
|
||||
@@ -44,14 +37,7 @@ class MetricsDistributionMeterFilterTest {
|
||||
}
|
||||
|
||||
@ParameterizedTest(name = "D9: configure() sets non-empty SLO boundaries for owned timer ''{0}''")
|
||||
@ValueSource(
|
||||
strings = {
|
||||
"http.server.requests",
|
||||
"http.server.requests.latency",
|
||||
"dependency.client.requests",
|
||||
"db.query.duration",
|
||||
"jvm.gc.pause"
|
||||
})
|
||||
@ValueSource(strings = {"http.server.requests", "jvm.gc.pause"})
|
||||
void configureSetsSloBoundariesForOwnedTimers(String metricName) {
|
||||
Meter.Id id = new Meter.Id(metricName, Tags.empty(), null, null, Meter.Type.TIMER);
|
||||
DistributionStatisticConfig result = filter.configure(id, DistributionStatisticConfig.DEFAULT);
|
||||
@@ -66,14 +52,7 @@ class MetricsDistributionMeterFilterTest {
|
||||
}
|
||||
|
||||
@ParameterizedTest(name = "D9: configure() sets client-side percentiles for owned timer ''{0}''")
|
||||
@ValueSource(
|
||||
strings = {
|
||||
"http.server.requests",
|
||||
"http.server.requests.latency",
|
||||
"dependency.client.requests",
|
||||
"db.query.duration",
|
||||
"jvm.gc.pause"
|
||||
})
|
||||
@ValueSource(strings = {"http.server.requests", "jvm.gc.pause"})
|
||||
void configureSetsPercentilesForOwnedTimers(String metricName) {
|
||||
Meter.Id id = new Meter.Id(metricName, Tags.empty(), null, null, Meter.Type.TIMER);
|
||||
DistributionStatisticConfig result = filter.configure(id, DistributionStatisticConfig.DEFAULT);
|
||||
@@ -86,14 +65,7 @@ class MetricsDistributionMeterFilterTest {
|
||||
}
|
||||
|
||||
@ParameterizedTest(name = "D9: configure() sets min/max expected value for owned timer ''{0}''")
|
||||
@ValueSource(
|
||||
strings = {
|
||||
"http.server.requests",
|
||||
"http.server.requests.latency",
|
||||
"dependency.client.requests",
|
||||
"db.query.duration",
|
||||
"jvm.gc.pause"
|
||||
})
|
||||
@ValueSource(strings = {"http.server.requests", "jvm.gc.pause"})
|
||||
void configureSetsMinMaxExpectedValueForOwnedTimers(String metricName) {
|
||||
Meter.Id id = new Meter.Id(metricName, Tags.empty(), null, null, Meter.Type.TIMER);
|
||||
DistributionStatisticConfig result = filter.configure(id, DistributionStatisticConfig.DEFAULT);
|
||||
|
||||
@@ -101,6 +101,9 @@ Spring/Lettuce 타입을 노출하지 않는다.
|
||||
- `DependencyFailureException`: `dependency failure classified as <code> (..., dependency=<이름>)` + 예외.
|
||||
- 그 밖의 5xx carrier: `failure classified as <code> (...)` + 예외. 4xx carrier는 남기지 않는다(응답이지
|
||||
사고가 아니다). `IDEMPOTENCY_RECOVERY_REQUIRED`는 예외 메시지 끝의 scope digest로 runbook이 기록을 찾는다.
|
||||
- 요청 없이 도는 일(스케줄러)은 `forBackgroundTask`를 쓴다. persistence 실패는 위와 같이 분류만, 그 밖의 carrier는
|
||||
4xx 코드여도 `failure classified as <code> (...)` + 예외다. 탓할 client가 없으니 4xx 코드도 결함이다(outbox relay,
|
||||
파일 서버 정리).
|
||||
- 전송은 자기 상관 정보를 뒤에 붙인다: gRPC ` (method=<서비스/메서드>)`, GraphQL ` (executionId=<id>)`.
|
||||
예외는 늘 마지막 인자라 SLF4J가 예외로 받는다.
|
||||
- 로그 줄은 찾은 carrier 의 타입으로 정한다. 감싼 persistence 실패도 감싼 예외나 SQL 원인 없이 분류 한 줄만 남는다.
|
||||
@@ -380,11 +383,12 @@ Spring/Lettuce 타입을 노출하지 않는다.
|
||||
> `ForbiddenMetricTags` 하나다(`MetricsCardinalityMeterFilter` 가 쓴다).
|
||||
|
||||
### MetricNaming
|
||||
- **Micrometer dot.case 메트릭 이름의 작명/단위 접미사 규칙**(D2/D3 + §3).
|
||||
- **Micrometer dot.case 메트릭 이름의 작명·단위 규칙**(D2/D3 + §3).
|
||||
- **이름 규칙(D2):** 소문자 영문+숫자만, 단일 점으로 segment 구분, 각 segment 는 영문자로 시작
|
||||
(예: `http.server.requests`). 정확한 규칙은 `VALID_NAME_PATTERN` 정규식에 있다.
|
||||
- **단위 접미사(D2):** 이름의 마지막 segment 로 `seconds`/`bytes`/`total` 중 하나를 붙인다
|
||||
(timer=seconds, byte 게이지=bytes, counter=total). 이 집합 밖의 접미사는 금지.
|
||||
- **단위(D2):** registry 행의 `unit` 칸은 `seconds`/`bytes`/`total` 중 하나다(`ALLOWED_UNITS`). 이름에 단위를 다시
|
||||
붙이지 않는다. Prometheus로 내보낼 때 Micrometer가 `_seconds`·`_bytes`·`_total`을 붙인다(`docs/registries/metrics.yaml`
|
||||
머리말).
|
||||
- **Prometheus base-name 변환(§3):** dot.case 이름의 `.` 을 `_` 로 바꾼다
|
||||
(`http.server.requests` → `http_server_requests`).
|
||||
- **INFERENCE / 운영 메모:** Spring Boot 3 Prometheus exporter 는 런타임에 추가 접미사
|
||||
@@ -393,23 +397,20 @@ Spring/Lettuce 타입을 노출하지 않는다.
|
||||
|
||||
### CardinalityBounds
|
||||
- **스켈레톤에 등록되는 메트릭의 tag 별 cardinality 상한**(§Cardinality Bounds 표의 Java mirror).
|
||||
`limitFor(key)` 로 magic number 하드코딩 없이 상한을 조회한다(MeterFilter 설정, cardinality
|
||||
계약 테스트).
|
||||
- 상수값(프로젝트 선택): `STATUS_CODE`=7(1xx~5xx + ok/other), `URI_TEMPLATE`=200
|
||||
`limitFor(key)` 로 magic number 하드코딩 없이 상한을 조회한다. 읽는 곳은 registry 계약 테스트
|
||||
(`MetricsAlertingContractTest`)뿐이다. test fixture 라 런타임 `MeterFilter` 는 이것을 쓰지 않는다(런타임 filter 는
|
||||
금지 tag 를 거절할 뿐 개수를 세지 않는다.).
|
||||
- 상수값(프로젝트 선택): `STATUS_CODE`=40(Spring `http.server.requests` 가 다는 숫자 status 코드 수), `URI_TEMPLATE`=200
|
||||
(라우트는 `/users/{id}` 처럼 템플릿 정규화 필수, raw path 는 `ForbiddenMetricTags` 로 금지),
|
||||
`DEPENDENCY_NAME`=50, `ERROR_CODE`=100, `TENANT_ID`=1000, `RESILIENCE4J_OUTCOME`=5
|
||||
(SUCCESS/FAILURE/CIRCUIT_OPEN/TIMEOUT/REJECTED).
|
||||
`DEPENDENCY_NAME`=50, `ERROR_CODE`=100, `TENANT_ID`=1000, `OUTCOME`=6(Spring HTTP outcome 여섯 값).
|
||||
- **`ERROR_CODE`=100 은 `error-codes.yaml` 의 행 수 상한과 동기화한다.** 레지스트리가 100행을 넘으면
|
||||
이 상수와 레지스트리 메모를 함께 갱신해야 한다.
|
||||
- **`TENANT_ID`=1000:** 메트릭 라벨은 bounded mapping-table ID 나 cohort bucket 을 써야 한다 —
|
||||
raw UUID tenant 식별자는 라벨로 금지. 이 상수는 상한 값일 뿐이다: 1000개를 넘는 tenant 값을 접어
|
||||
주는(bucket folding) 코드는 없으므로, 상한을 지키는 매핑은 메트릭을 등록하는 쪽이 만든다.
|
||||
- **tag-key 매핑 quirk 2가지**(`limitFor` 에서 명시 처리): (1) HTTP 메트릭 레지스트리 행의 tag 이름은
|
||||
`status_code` 가 아니라 `status` 다 — 혼동을 막으려 `status`/`status_code` 둘 다 `STATUS_CODE`(7)로
|
||||
매핑. (2) Resilience4j bound 는 `outcome` tag(5값)에 적용 — 상수명은 명료성을 위해
|
||||
`RESILIENCE4J_OUTCOME` 이지만 lookup 키는 레지스트리 tag 이름인 `outcome` 다. 다른 메트릭의
|
||||
`outcome` tag 는 실제 cardinality 가 다를 수 있으나(db 3, outbox 4), lookup 은 보수적 출발점으로
|
||||
Resilience4j bound 를 돌려준다.
|
||||
- **tag-key 매핑**(`limitFor`): `status`/`status_code` 는 `STATUS_CODE`, `uri`/`uri_template` 은 `URI_TEMPLATE`,
|
||||
`outcome` 은 `OUTCOME` 이다. 다른 메트릭의 `outcome` tag 는 실제 값이 더 적을 수 있으나(httpclient 3, outbox 5),
|
||||
lookup 은 가장 넓은 집합을 돌려준다.
|
||||
|
||||
### ForbiddenMetricTags
|
||||
- **스켈레톤 전역에서 금지된 high-cardinality 메트릭 tag 키**(D8): `user_id`, `request_id`,
|
||||
|
||||
+26
-5
@@ -22,11 +22,13 @@ import java.util.Optional;
|
||||
* by ({@code docs/runbooks/idempotency-unavailable.md}).
|
||||
* </ul>
|
||||
*
|
||||
* <p>A client-side carrier is not logged: it is an answer, not an incident. The line is written in
|
||||
* the SLF4J style — {@code {}} placeholders, with an attached exception as the last argument — so a
|
||||
* transport hands {@link #format(String)} and {@link #arguments(Object...)} straight to {@code
|
||||
* Logger.error}. A transport adds its own correlation (a gRPC method, a GraphQL execution id) as a
|
||||
* suffix; the failure stays last.
|
||||
* <p>A client-side carrier is not logged: it is an answer, not an incident. Work no client started
|
||||
* — a scheduled task — uses {@link #forBackgroundTask} instead, which logs a client-side code like
|
||||
* a server-side one, exception attached: with no client to blame, it is a defect. The line is
|
||||
* written in the SLF4J style — {@code {}} placeholders, with an attached exception as the last
|
||||
* argument — so a transport hands {@link #format(String)} and {@link #arguments(Object...)}
|
||||
* straight to {@code Logger.error}. A transport adds its own correlation (a gRPC method, a GraphQL
|
||||
* execution id) as a suffix; the failure stays last.
|
||||
*
|
||||
* <p>One line is not an error: {@link #refusedArgument(IllegalArgumentException)}, which every
|
||||
* transport writes at WARN when it answers an {@link IllegalArgumentException} as {@link
|
||||
@@ -83,6 +85,25 @@ public final class ServerFailureLog {
|
||||
return Optional.empty();
|
||||
}
|
||||
|
||||
/**
|
||||
* The line for a classified failure in work no client started, such as a scheduled task: {@link
|
||||
* #of}'s line, and for a client-side code the same shape as a server-side one, with the failure
|
||||
* attached. A client-side code with no client to blame is a defect, so its stack stays; {@link
|
||||
* #refused} would drop it.
|
||||
*
|
||||
* @param failure the carrier found in the task's failure — not a wrapper around it
|
||||
* @param code the code it carries
|
||||
*/
|
||||
public static ServerFailureLog forBackgroundTask(Throwable failure, ApiErrorCode code) {
|
||||
return of(failure, code)
|
||||
.orElseGet(
|
||||
() ->
|
||||
new ServerFailureLog(
|
||||
"failure classified as {} (category={}, retryable={})",
|
||||
new Object[] {code.code(), code.category(), code.retryable()},
|
||||
failure));
|
||||
}
|
||||
|
||||
/**
|
||||
* The WARN line for an {@link IllegalArgumentException} a transport answers as {@link
|
||||
* OperationalError#BAD_PARAMETER}: the request was wrong, so it is not an error, but the line
|
||||
|
||||
+16
@@ -75,6 +75,22 @@ class ServerFailureLogTest {
|
||||
});
|
||||
}
|
||||
|
||||
@Test
|
||||
void aClientSideCarrierInABackgroundTaskIsLoggedWithTheFailureAttached() {
|
||||
// given
|
||||
CarrierException failure = new CarrierException(OperationalError.BAD_PARAMETER, "bad input");
|
||||
|
||||
// when
|
||||
ServerFailureLog line =
|
||||
ServerFailureLog.forBackgroundTask(failure, OperationalError.BAD_PARAMETER);
|
||||
|
||||
// then
|
||||
assertThat(line.format("")).isEqualTo("failure classified as {} (category={}, retryable={})");
|
||||
assertThat(line.arguments())
|
||||
.containsExactly(
|
||||
"BAD_PARAMETER", OperationalError.BAD_PARAMETER.category(), false, failure);
|
||||
}
|
||||
|
||||
@Test
|
||||
void aClientSideCarrierIsNotLogged() {
|
||||
// when
|
||||
|
||||
+18
-12
@@ -15,8 +15,8 @@ class CardinalityBoundsTest {
|
||||
// ----------------------------------------------------------------
|
||||
|
||||
@Test
|
||||
void statusCodeConstantIs7() {
|
||||
assertThat(CardinalityBounds.STATUS_CODE).isEqualTo(7);
|
||||
void statusCodeConstantIs40() {
|
||||
assertThat(CardinalityBounds.STATUS_CODE).isEqualTo(40);
|
||||
}
|
||||
|
||||
@Test
|
||||
@@ -40,8 +40,8 @@ class CardinalityBoundsTest {
|
||||
}
|
||||
|
||||
@Test
|
||||
void resilience4jOutcomeConstantIs5() {
|
||||
assertThat(CardinalityBounds.RESILIENCE4J_OUTCOME).isEqualTo(5);
|
||||
void outcomeConstantIs6() {
|
||||
assertThat(CardinalityBounds.OUTCOME).isEqualTo(6);
|
||||
}
|
||||
|
||||
// ----------------------------------------------------------------
|
||||
@@ -49,14 +49,14 @@ class CardinalityBoundsTest {
|
||||
// ----------------------------------------------------------------
|
||||
|
||||
@Test
|
||||
void limitForStatusCodeReturns7() {
|
||||
assertThat(CardinalityBounds.limitFor("status_code")).hasValue(7);
|
||||
void limitForStatusCodeReturns40() {
|
||||
assertThat(CardinalityBounds.limitFor("status_code")).hasValue(40);
|
||||
}
|
||||
|
||||
@Test
|
||||
void limitForStatusAlsoReturns7() {
|
||||
// registry HTTP row tag is named "status", not "status_code"; both map to 7
|
||||
assertThat(CardinalityBounds.limitFor("status")).hasValue(7);
|
||||
void limitForStatusAlsoReturns40() {
|
||||
// registry HTTP row tag is named "status", not "status_code"; both map to 40
|
||||
assertThat(CardinalityBounds.limitFor("status")).hasValue(40);
|
||||
}
|
||||
|
||||
@Test
|
||||
@@ -64,6 +64,12 @@ class CardinalityBoundsTest {
|
||||
assertThat(CardinalityBounds.limitFor("uri_template")).hasValue(200);
|
||||
}
|
||||
|
||||
@Test
|
||||
void limitForUriReturnsTheUriTemplateBound() {
|
||||
// Spring's http.server.requests names the route tag "uri"
|
||||
assertThat(CardinalityBounds.limitFor("uri")).hasValue(CardinalityBounds.URI_TEMPLATE);
|
||||
}
|
||||
|
||||
@Test
|
||||
void limitForDependencyNameReturns50() {
|
||||
assertThat(CardinalityBounds.limitFor("dependency_name")).hasValue(50);
|
||||
@@ -80,9 +86,9 @@ class CardinalityBoundsTest {
|
||||
}
|
||||
|
||||
@Test
|
||||
void limitForOutcomeReturns5() {
|
||||
// resilience4j uses tag named "outcome"
|
||||
assertThat(CardinalityBounds.limitFor("outcome")).hasValue(5);
|
||||
void limitForOutcomeReturns6() {
|
||||
// Spring's http.server.requests outcome has six values
|
||||
assertThat(CardinalityBounds.limitFor("outcome")).hasValue(6);
|
||||
}
|
||||
|
||||
// ----------------------------------------------------------------
|
||||
|
||||
+19
-10
@@ -6,19 +6,24 @@ import java.util.OptionalInt;
|
||||
/**
|
||||
* Per-tag cardinality upper bounds for metrics registered in this skeleton — a Java mirror of the
|
||||
* registry's cardinality table. {@link #limitFor(String)} gives the bound for a known tag key
|
||||
* without hard-coding magic numbers (used by {@code MeterFilter} config and cardinality contract
|
||||
* tests). Java stdlib only.
|
||||
* without hard-coding magic numbers. Only the registry contract test reads it (it is a test
|
||||
* fixture); no runtime {@code MeterFilter} does — the runtime filter refuses forbidden tags, it
|
||||
* does not cap counts. This Javadoc used to say a MeterFilter used it (review 2026-11-12). Java
|
||||
* stdlib only.
|
||||
*
|
||||
* <p>The numeric values are operational assumptions, not an external standard. See the module
|
||||
* README for the rationale, the {@code error-codes.yaml} sync rule, and the two tag-key mapping
|
||||
* quirks ({@code status}/{@code status_code} and {@code outcome}).
|
||||
* README for the rationale, the {@code error-codes.yaml} sync rule, and the tag-key mappings
|
||||
* ({@code status}/{@code status_code}, {@code outcome} and {@code uri}).
|
||||
*/
|
||||
public final class CardinalityBounds {
|
||||
|
||||
private CardinalityBounds() {}
|
||||
|
||||
/** HTTP status-class tag bound (1xx–5xx + ok/other). */
|
||||
public static final int STATUS_CODE = 7;
|
||||
/**
|
||||
* HTTP status tag bound: the numeric codes a service answers with ({@code 200}, {@code 404}, …),
|
||||
* which is what Spring's {@code http.server.requests} records — not five status classes.
|
||||
*/
|
||||
public static final int STATUS_CODE = 40;
|
||||
|
||||
/** URI template tag bound — routes must be template-normalised (e.g. {@code /users/{id}}). */
|
||||
public static final int URI_TEMPLATE = 200;
|
||||
@@ -32,8 +37,11 @@ public final class CardinalityBounds {
|
||||
/** Tenant id tag bound — bounded mapping-table id / cohort bucket only, no raw UUID. */
|
||||
public static final int TENANT_ID = 1000;
|
||||
|
||||
/** Resilience4j {@code outcome} tag bound (SUCCESS/FAILURE/CIRCUIT_OPEN/TIMEOUT/REJECTED). */
|
||||
public static final int RESILIENCE4J_OUTCOME = 5;
|
||||
/**
|
||||
* {@code outcome} tag bound: Spring's six HTTP outcomes (INFORMATIONAL … UNKNOWN), the widest set
|
||||
* a registered meter uses.
|
||||
*/
|
||||
public static final int OUTCOME = 6;
|
||||
|
||||
/** Registry tag name → cardinality bound. See the module README for the mapping quirks. */
|
||||
private static final Map<String, Integer> LIMITS =
|
||||
@@ -41,16 +49,17 @@ public final class CardinalityBounds {
|
||||
"status_code", STATUS_CODE,
|
||||
"status", STATUS_CODE,
|
||||
"uri_template", URI_TEMPLATE,
|
||||
"uri", URI_TEMPLATE,
|
||||
"dependency_name", DEPENDENCY_NAME,
|
||||
"error_code", ERROR_CODE,
|
||||
"tenant_id", TENANT_ID,
|
||||
"outcome", RESILIENCE4J_OUTCOME);
|
||||
"outcome", OUTCOME);
|
||||
|
||||
/**
|
||||
* Returns the cardinality upper bound for a known registry tag key, or {@link
|
||||
* OptionalInt#empty()} for unknown or {@code null} keys.
|
||||
*
|
||||
* <p>Known keys: {@code status_code}, {@code status}, {@code uri_template}, {@code
|
||||
* <p>Known keys: {@code status_code}, {@code status}, {@code uri_template}, {@code uri}, {@code
|
||||
* dependency_name}, {@code error_code}, {@code tenant_id}, {@code outcome}.
|
||||
*
|
||||
* @param tagKey the registry tag name; {@code null} returns empty
|
||||
|
||||
+4
-2
@@ -16,8 +16,10 @@ public final class MetricNaming {
|
||||
private MetricNaming() {}
|
||||
|
||||
/**
|
||||
* Allowed Micrometer unit suffixes — every registry metric name must end with one of these:
|
||||
* {@code seconds} (timers), {@code bytes} (byte gauges), {@code total} (counters).
|
||||
* Allowed values of a registry row's {@code unit}: {@code seconds} (timers), {@code bytes} (byte
|
||||
* gauges and summaries), {@code total} (counters and count gauges). The name does not repeat the
|
||||
* unit. Micrometer's Prometheus naming appends {@code _seconds} to a timer and {@code _total} to
|
||||
* a counter; a count gauge gets no suffix.
|
||||
*/
|
||||
public static final Set<String> ALLOWED_UNITS = Set.of("seconds", "bytes", "total");
|
||||
|
||||
|
||||
Reference in New Issue
Block a user