diff --git a/.claude/skills/be-observability/SKILL.md b/.claude/skills/be-observability/SKILL.md index c40037ea..3bffbbb2 100644 --- a/.claude/skills/be-observability/SKILL.md +++ b/.claude/skills/be-observability/SKILL.md @@ -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` 등) diff --git a/.claude/skills/be-security/SKILL.md b/.claude/skills/be-security/SKILL.md index 82513545..1a2fa06b 100644 --- a/.claude/skills/be-security/SKILL.md +++ b/.claude/skills/be-security/SKILL.md @@ -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절 (다) diff --git a/compose.yaml b/compose.yaml index 992355d4..3d355e90 100644 --- a/compose.yaml +++ b/compose.yaml @@ -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 diff --git a/docs/build.md b/docs/build.md index 4ab711c4..2ef377d7 100644 --- a/docs/build.md +++ b/docs/build.md @@ -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 기본). ### 분산 추적 diff --git a/docs/capability-status.md b/docs/capability-status.md index d6a56756..d774e82d 100644 --- a/docs/capability-status.md +++ b/docs/capability-status.md @@ -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` | 운영 코드가 부르지 않았다. 요청 로그는 헤더를 싣지 않는다 | diff --git a/docs/httpclient/operations.md b/docs/httpclient/operations.md index f19f8754..879418f0 100644 --- a/docs/httpclient/operations.md +++ b/docs/httpclient/operations.md @@ -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 diff --git a/docs/registries/headers.yaml b/docs/registries/headers.yaml index 5530af1c..8158b55b 100644 --- a/docs/registries/headers.yaml +++ b/docs/registries/headers.yaml @@ -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" diff --git a/docs/registries/mdc-keys.yaml b/docs/registries/mdc-keys.yaml index fcf391c2..0c866267 100644 --- a/docs/registries/mdc-keys.yaml +++ b/docs/registries/mdc-keys.yaml @@ -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 diff --git a/docs/registries/metrics.yaml b/docs/registries/metrics.yaml index 06f17143..4722c3ba 100644 --- a/docs/registries/metrics.yaml +++ b/docs/registries/metrics.yaml @@ -4,7 +4,17 @@ # Last updated: 2026-05-22 # # 읽는 법 -# - 이름: Micrometer dot.case에 단위 접미사(.seconds | .bytes | .total)를 붙인다. +# - 이름: Micrometer dot.case다. 단위는 `unit` 칸(seconds | bytes | total)이 말하고, 새 이름에는 단위를 다시 쓰지 +# 않는다. Prometheus로 내보낼 때 Micrometer가 timer에 _seconds, counter에 _total을 붙인다(gauge에는 base unit이 +# 있을 때만 붙고, unit이 total인 count gauge에는 붙지 않는다). 단위로 끝나는 옛 이름 +# (outbox.publisher.published.total 같은 .total, redis.lane.acquire.wait.seconds, http.client.request.bytes· +# response.bytes, fileserver.transfer.bytes)은 이름을 바꾸면 대시보드가 깨지므로 그대로 둔다. +# - 행은 코드가 실제로 등록하는 meter다. `source`가 그 출처다: 이름 글자를 가진 main 파일 또는 `framework: …` +# (Spring Boot·Micrometer·HikariCP·Spring for GraphQL이 내는 것). 이름이 상수로만 있으면 `constant`와 그 상수를 쓰는 +# `registered_by` 파일도 적는다. MetricsRegistryCodeAlignmentTest가 행 → 코드(상수면 그 상수를 쓰는 곳까지), +# 그리고 글자·상수 이름으로 등록한 meter → 행의 두 방향을 대조한다. capability를 켠 서비스에서만 나오는 meter도 +# 행이 있다(그 행의 절 제목이 말한다). `emitted_when`이 있는 행은 템플릿 코드가 부르지 않는 공개 메서드를 서비스가 +# 부를 때만 생긴다. # - tag 값 개수(cardinality) 상한의 정본은 feature-metrics-alerting-contract의 "Cardinality Bounds" 표다. # - 값 개수가 많은 tag는 어디서도 쓰지 않는다: user_id, request_id, raw_url, raw_query, # raw_header_value, ip_address. 어떤 행에도 나오면 안 된다. @@ -14,10 +24,9 @@ # 기간(5m, 1h)은 원문 그대로 두고, 테스트는 키(p1·p2·p3)와 값이 비어 있지 않은지만 본다. metrics: - # === HTTP 서버 (inbound) === - # source: feature-metrics-alerting-contract — Metric/Alert Defaults - # "HTTP metric | http.server.requests with method/status/uri-template | raw URL or user id tag" + # Spring MVC가 요청마다 기록하는 timer다. tag는 Spring Framework 기본 observation convention 그대로다. + # 지연(p99) 경보도 이 timer로 건다. - name: http.server.requests type: timer unit: seconds @@ -26,155 +35,82 @@ metrics: cardinality_limit: 8 allowed_values: [GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, OTHER] - name: status - cardinality_limit: 7 - allowed_values: [1xx, 2xx, 3xx, 4xx, 5xx, ok, other] - - name: uri_template + # 숫자 HTTP status(200, 404, …). 서비스가 실제로 답하는 코드 수가 상한이다. + cardinality_limit: 40 + - name: uri + # 맞는 route의 template(/v1/orders/{id}), 없으면 NOT_FOUND·REDIRECTION·UNKNOWN·root. cardinality_limit: 200 validation: must_be_template_not_raw_uri + - name: outcome + cardinality_limit: 6 + allowed_values: [INFORMATIONAL, SUCCESS, REDIRECTION, CLIENT_ERROR, SERVER_ERROR, UNKNOWN] + - name: exception + # 예외 클래스의 단순 이름, 없으면 none. + cardinality_limit: 50 + - name: error + cardinality_limit: 50 percentiles: [0.5, 0.9, 0.95, 0.99] histogram_buckets: slo_driven alert_severity_thresholds: - p1: "error_rate > 5%가 5m 동안, 또는 > 10%가 1m 동안" - p2: "error_rate > 1%가 10m 동안" - p3: "error_rate > 0.1%가 1h 동안" + p1: "error_rate > 5%가 5m 동안(또는 > 10%가 1m), 또는 p99 > 5s가 5m 동안" + p2: "error_rate > 1%가 10m 동안, 또는 p99 > 1s가 10m 동안" + p3: "error_rate > 0.1%가 1h 동안, 또는 p99 > 500ms가 30m 동안" owner_branch: feature-metrics-alerting-contract log_field_mapping: [method, status, uri_template] compatibility_impact: additive required_test: contract-verification:metrics-cardinality - - # source: feature-metrics-alerting-contract — P1/P2/P3 정량 기준 (HTTP latency p99) - # "P1: p99 > 5s 5분 / P2: p99 > 1s 10분 / P3: p99 > 500ms 30분" - - name: http.server.requests.latency - type: timer - unit: seconds - tags: - - name: method - cardinality_limit: 8 - allowed_values: [GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, OTHER] - - name: uri_template - cardinality_limit: 200 - validation: must_be_template_not_raw_uri - percentiles: [0.5, 0.9, 0.95, 0.99] - histogram_buckets: slo_driven - alert_severity_thresholds: - p1: "p99 > 5s가 5m 동안" - p2: "p99 > 1s가 10m 동안" - p3: "p99 > 500ms가 30m 동안" - owner_branch: feature-metrics-alerting-contract - log_field_mapping: [method, uri_template, duration_ms] - compatibility_impact: additive - required_test: contract-verification:metrics-cardinality - - # === HTTP client (outbound 의존 대상) === - # source: feature-metrics-alerting-contract — Metric/Alert Defaults - # "dependency metric | dependency.client.requests with dependency.name/type/outcome | endpoint with secret tag" - # source: feature-outbound-http-client-baseline — "circuit breaker metric은 dependency.name, dependency.type, outcome까지만 tag로 허용" - - name: dependency.client.requests - type: timer - unit: seconds - tags: - - name: dependency_name - cardinality_limit: 50 - - name: dependency_type - cardinality_limit: 10 - allowed_values: [http, grpc, db, cache, queue, broker, other] - - name: outcome - cardinality_limit: 5 - allowed_values: [SUCCESS, FAILURE, CIRCUIT_OPEN, TIMEOUT, REJECTED] - percentiles: [0.5, 0.9, 0.95, 0.99] - histogram_buckets: slo_driven - alert_severity_thresholds: - p1: "필수 의존 대상이 2m 동안 응답하지 않음" - p2: "선택 의존 대상이 5m 동안 저하됨" - p3: "급증 경보(기준선의 10배)" - owner_branch: feature-metrics-alerting-contract - log_field_mapping: [dependency_name, dependency_type, outcome, duration_ms] - compatibility_impact: additive - required_test: contract-verification:metrics-cardinality - - # source: feature-outbound-http-client-baseline — decisions - # "retry/circuit breaker 기본 라이브러리는 Resilience4j" - # source: feature-metrics-alerting-contract — "retry/CB minimum: resilience4j.retry.calls{outcome}" - - name: resilience4j.retry.calls - type: counter - unit: total - tags: - - name: name - cardinality_limit: 50 - - name: outcome - cardinality_limit: 5 - allowed_values: [SUCCESS, FAILURE, CIRCUIT_OPEN, TIMEOUT, REJECTED] - percentiles: null - histogram_buckets: null - alert_severity_thresholds: - p2: "재시도 소진 비율 > 1%가 10m 동안" - owner_branch: feature-outbound-http-client-baseline - log_field_mapping: [dependency_name, outcome, retry_attempt] - compatibility_impact: additive - required_test: contract-verification:metrics-cardinality - - # source: feature-metrics-alerting-contract — "resilience4j.circuitbreaker.state" - - name: resilience4j.circuitbreaker.state - type: gauge - unit: total - tags: - - name: name - cardinality_limit: 50 - - name: state - cardinality_limit: 6 - allowed_values: [CLOSED, OPEN, HALF_OPEN, DISABLED, FORCED_OPEN, METRICS_ONLY] - percentiles: null - histogram_buckets: null - alert_severity_thresholds: - p1: "필수 의존 대상의 state == OPEN이 2m 동안" - p2: "선택 의존 대상의 state == OPEN이 5m 동안" - owner_branch: feature-outbound-http-client-baseline - log_field_mapping: [dependency_name] - compatibility_impact: additive - required_test: contract-verification:metrics-cardinality - - # source: feature-metrics-alerting-contract — "resilience4j.circuitbreaker.calls{outcome}" - - name: resilience4j.circuitbreaker.calls - type: timer - unit: seconds - tags: - - name: name - cardinality_limit: 50 - - name: outcome - cardinality_limit: 5 - allowed_values: [SUCCESS, FAILURE, CIRCUIT_OPEN, TIMEOUT, REJECTED] - percentiles: [0.5, 0.9, 0.95, 0.99] - histogram_buckets: slo_driven - alert_severity_thresholds: - p2: "CIRCUIT_OPEN 비율 > 1%가 10m 동안" - owner_branch: feature-outbound-http-client-baseline - log_field_mapping: [dependency_name, outcome, duration_ms] - compatibility_impact: additive - required_test: contract-verification:metrics-cardinality - - # === DB connection pool === - # source: feature-persistence-failure-baseline — Hikari Alert Threshold - # "pool wait p99 > 100ms 5분 지속 → P2 / pool exhaustion (active = max) > 1분 → P1" - # source: feature-metrics-alerting-contract — "hikaricp.connections.acquire{outcome='timeout'} p99 > 100ms" + source: "framework: Spring MVC 요청 observation(Spring Framework 기본 convention)" + # === DB connection pool (HikariCP, persistence-jpa를 켤 때) === + # HikariCP의 Micrometer tracker가 내는 이름 그대로다. acquire timer에는 pool tag 하나뿐이다. 획득 timeout은 + # 따로 센다(hikaricp.connections.timeout). - name: hikaricp.connections.acquire type: timer unit: seconds tags: - name: pool cardinality_limit: 5 - - name: outcome - cardinality_limit: 3 - allowed_values: [SUCCESS, TIMEOUT, FAILURE] - percentiles: [0.5, 0.9, 0.95, 0.99] - histogram_buckets: slo_driven + # histogram을 켜는 것이 없다(MetricsDistributionMeterFilter 대상이 아니다). 경보는 평균(sum/count)으로 건다. + percentiles: null + histogram_buckets: null alert_severity_thresholds: - p1: "pool 고갈(active == max)이 1m 동안" - p2: "acquire p99 > 100ms가 5m 동안" + p2: "평균 acquire 시간(sum/count) > 100ms가 5m 동안" owner_branch: feature-persistence-failure-baseline - log_field_mapping: [pool, outcome] + log_field_mapping: [pool] compatibility_impact: additive required_test: contract-verification:metrics-cardinality + source: "framework: HikariCP Micrometer tracker(persistence-jpa를 켤 때)" + - name: hikaricp.connections.timeout + type: counter + unit: total + tags: + - name: pool + cardinality_limit: 5 + percentiles: null + histogram_buckets: null + alert_severity_thresholds: + p1: "timeout 증가 > 0이 1m 동안(pool 고갈: active == max)" + owner_branch: feature-persistence-failure-baseline + log_field_mapping: [pool] + compatibility_impact: additive + required_test: contract-verification:metrics-cardinality + source: "framework: HikariCP Micrometer tracker(persistence-jpa를 켤 때)" + + - name: hikaricp.connections.pending + type: gauge + unit: total + tags: + - name: pool + cardinality_limit: 5 + percentiles: null + histogram_buckets: null + alert_severity_thresholds: + p2: "pending > 0이 5m 동안" + owner_branch: feature-persistence-failure-baseline + log_field_mapping: [pool] + compatibility_impact: additive + required_test: contract-verification:metrics-cardinality + source: "framework: HikariCP Micrometer tracker(persistence-jpa를 켤 때)" # source: feature-persistence-failure-baseline — In scope "Hikari metric 노출 기준" + Hikari Alert Threshold - name: hikaricp.connections.usage type: timer @@ -182,14 +118,15 @@ metrics: tags: - name: pool cardinality_limit: 5 - percentiles: [0.5, 0.9, 0.95, 0.99] - histogram_buckets: slo_driven + percentiles: null + histogram_buckets: null alert_severity_thresholds: - p2: "usage p99가 10m 넘게 높음" + p2: "평균 usage 시간(sum/count) > 1s가 10m 동안(connection을 오래 쥔 트랜잭션)" owner_branch: feature-persistence-failure-baseline log_field_mapping: [pool] compatibility_impact: additive required_test: contract-verification:metrics-cardinality + source: "framework: HikariCP Micrometer tracker(persistence-jpa를 켤 때)" # source: feature-persistence-failure-baseline — In scope "Hikari metric 노출 기준" - name: hikaricp.connections.active @@ -206,26 +143,7 @@ metrics: log_field_mapping: [pool] compatibility_impact: additive required_test: contract-verification:metrics-cardinality - - # source: feature-metrics-alerting-contract — Histogram Buckets/Percentile "DB query: same" - - name: db.query.duration - type: timer - unit: seconds - tags: - - name: operation - cardinality_limit: 20 - allowed_values: [select, insert, update, delete, batch, ddl, other] - - name: outcome - cardinality_limit: 3 - allowed_values: [SUCCESS, FAILURE, TIMEOUT] - percentiles: [0.5, 0.9, 0.95, 0.99] - histogram_buckets: slo_driven - alert_severity_thresholds: - p2: "p99 > 1s가 10m 동안" - owner_branch: feature-metrics-alerting-contract - log_field_mapping: [operation, outcome, duration_ms] - compatibility_impact: additive - required_test: contract-verification:metrics-cardinality + source: "framework: HikariCP Micrometer tracker(persistence-jpa를 켤 때)" # === 백그라운드 작업 / 비동기 executor === # source: feature-background-job-async-contract — Decisionized Work Items "saturation policy" @@ -245,6 +163,7 @@ metrics: log_field_mapping: [executor_name] compatibility_impact: additive required_test: contract-verification:metrics-cardinality + source: "src/bootstrap/app/src/main/java/dev/caskeleton/bootstrap/async/BackgroundJobMetrics.java" # source: feature-background-job-async-contract — Decisionized Work Items "saturation | bounded executor + rejection log" - name: executor.rejected.total @@ -264,6 +183,7 @@ metrics: log_field_mapping: [executor_name, policy] compatibility_impact: additive required_test: contract-verification:metrics-cardinality + source: "src/bootstrap/app/src/main/java/dev/caskeleton/bootstrap/async/BackgroundJobMetrics.java" # source: feature-background-job-async-contract — Decisionized Work Items "retry/DLQ | exp backoff jitter, max 3, DLQ exhausted" - name: job.retry.total @@ -283,6 +203,8 @@ metrics: log_field_mapping: [job_name, outcome, retry_attempt] compatibility_impact: additive required_test: contract-verification:metrics-cardinality + source: "src/bootstrap/app/src/main/java/dev/caskeleton/bootstrap/async/BackgroundJobMetrics.java" + emitted_when: "서비스가 BackgroundJobMetrics.recordRetryOutcome을 부를 때. 템플릿 코드는 부르지 않는다" # source: feature-background-job-async-contract — "DLQ after exhausted attempts" - name: job.dlq.total @@ -299,11 +221,14 @@ metrics: log_field_mapping: [job_name] compatibility_impact: additive required_test: contract-verification:metrics-cardinality + source: "src/bootstrap/app/src/main/java/dev/caskeleton/bootstrap/async/BackgroundJobMetrics.java" + emitted_when: "서비스가 BackgroundJobMetrics.recordDeadLetter를 부를 때. 템플릿 코드는 부르지 않는다" # === Distributed lock === # source: feature-distributed-lock-contract D7 — "metric lock.acquisition (tag: outcome = - # acquired/timeout/error) — 신규 제안" / D5 — try-lock + 유한 waitTime + lease(TTL). 분산 - # 상호배제(distributedLockProvider) 획득 시도 결과를 센다. key 는 tag 로 넣지 않는다 + # acquired/timeout/error) — 신규 제안" / D5 — try-lock + 유한 waitTime + lease(TTL). lock 획득 + # 시도 결과를 센다: 분산 상호배제(distributedLockProvider)와 단일 인스턴스 in-process lock 모두 + # MeteredDistributedLock으로 감싼다. key 는 tag 로 넣지 않는다 # (무한 cardinality — 위 전역 금지 규칙). timeout outcome 은 LOCK_ACQUISITION_TIMEOUT 발생과 1:1. - name: lock.acquisition type: counter @@ -320,6 +245,7 @@ metrics: log_field_mapping: [outcome] compatibility_impact: additive required_test: contract-verification:metrics-cardinality + source: "src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/lock/MeteredDistributedLock.java" # source: feature-distributed-lock-contract §Edge / D5 (SI-LOCK-C5) — "lease 만료 후 unlock → # ConcurrentModificationException — 삼킴 금지, 로그+metric 후 정상 흐름 복귀". lease가 이미 만료된 뒤의 @@ -338,6 +264,7 @@ metrics: log_field_mapping: [] compatibility_impact: additive required_test: contract-verification:metrics-cardinality + source: "src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/lock/MeteredDistributedLock.java" # === Outbox 발행기 === # source: feature-domain-event-outbox-contract — Outbox Defaults @@ -362,6 +289,7 @@ metrics: log_field_mapping: [event_type, outcome, event_id] compatibility_impact: additive required_test: contract-verification:metrics-cardinality + source: "src/bootstrap/outbox-relay/src/main/java/dev/caskeleton/composition/outbox/OutboxMetrics.java" # source: feature-domain-event-outbox-contract — 행 상태 enum PENDING/IN_FLIGHT/PUBLISHED/FAILED/DEAD - name: outbox.publisher.lag @@ -379,6 +307,7 @@ metrics: log_field_mapping: [event_type] compatibility_impact: additive required_test: contract-verification:metrics-cardinality + source: "src/bootstrap/outbox-relay/src/main/java/dev/caskeleton/composition/outbox/OutboxMetrics.java" # source: feature-domain-event-outbox-contract — row status enum + Outbox Defaults attemptCount # PARKED: 끝없이 재시도되던 행을 운영자가 붙잡아 둠 (re-review 2026-11-03 RR-05-03). @@ -400,6 +329,7 @@ metrics: log_field_mapping: [status] compatibility_impact: additive required_test: contract-verification:metrics-cardinality + source: "src/bootstrap/outbox-relay/src/main/java/dev/caskeleton/composition/outbox/OutboxMetrics.java" # source: re-review 2026-11-03 RR-05-03 — 지금의 거절과 답이 없는 발행은 끝없이 재시도된다. 이 둘은 # 10번 이상 미뤄진 FAILED 행을 세고(OutboxMetrics LONG_RETRY_DEFERRED_CLAIMS, publish-failed runbook §4.1 @@ -416,6 +346,7 @@ metrics: log_field_mapping: [] compatibility_impact: additive required_test: contract-verification:metrics-cardinality + source: "src/bootstrap/outbox-relay/src/main/java/dev/caskeleton/composition/outbox/OutboxMetrics.java" - name: outbox.retry.long.age type: gauge @@ -429,113 +360,7 @@ metrics: log_field_mapping: [] compatibility_impact: additive required_test: contract-verification:metrics-cardinality - - # === 캐시 === - # source: feature-cache-consistency-contract — Decisionized Work Items "cache pattern | cache-aside default" - - name: cache.gets.total - type: counter - unit: total - tags: - - name: cache_name - cardinality_limit: 50 - - name: result - cardinality_limit: 3 - allowed_values: [hit, miss, error] - percentiles: null - histogram_buckets: null - alert_severity_thresholds: - p3: "hit_ratio < 기준선의 0.5배가 1h 동안" - owner_branch: feature-cache-consistency-contract - log_field_mapping: [cache_name, result] - compatibility_impact: additive - required_test: contract-verification:metrics-cardinality - - # source: feature-cache-consistency-contract — "invalidation = after-commit only", "invalidation 실패가 조용히 무시되면 실패" - - name: cache.invalidations.total - type: counter - unit: total - tags: - - name: cache_name - cardinality_limit: 50 - - name: outcome - cardinality_limit: 3 - allowed_values: [SUCCESS, FAILURE, SKIPPED] - percentiles: null - histogram_buckets: null - alert_severity_thresholds: - p2: "FAILURE 비율 > 0이 5m 동안" - owner_branch: feature-cache-consistency-contract - log_field_mapping: [cache_name, outcome] - compatibility_impact: additive - required_test: contract-verification:metrics-cardinality - - # source: redis-production-capability — 크기가 정해진 캐시 전용 L1 (선택) - - name: cache.local.requests.total - type: counter - unit: total - tags: - - name: cache_name - cardinality_limit: 50 - - name: result - cardinality_limit: 4 - allowed_values: [hit, miss, error, bypass] - percentiles: null - histogram_buckets: null - alert_severity_thresholds: - p3: "bypass 또는 error 비율이 기준선보다 높은 상태가 15m 동안" - owner_branch: redis-production-capability - log_field_mapping: [cache_name, result] - compatibility_impact: additive - required_test: contract-verification:metrics-cardinality - - # source: redis-production-capability — 로컬 stale 나이 상한 - - name: cache.local.entry.age.seconds - type: timer - unit: seconds - tags: - - name: cache_name - cardinality_limit: 50 - percentiles: [0.5, 0.9, 0.95, 0.99] - histogram_buckets: slo_driven - alert_severity_thresholds: - p3: "p99가 설정한 로컬 TTL에 가까운 상태가 30m 동안" - owner_branch: redis-production-capability - log_field_mapping: [cache_name] - compatibility_impact: additive - required_test: contract-verification:metrics-cardinality - - # source: redis-production-capability — 크기가 정해진 무효화와 세대 대조(reconciliation) - - name: cache.local.maintenance.total - type: counter - unit: total - tags: - - name: cache_name - cardinality_limit: 50 - - name: event - cardinality_limit: 14 - allowed_values: - - evict_cardinality - - evict_weight - - evict_ttl - - evict_invalidation - - flush_invalidation - - reconcile_generation_changed - - reconcile_unchanged - - reconcile_error - - subscriber_disconnected - - subscriber_overflow - - subscriber_malformed - - subscriber_publish_success - - subscriber_publish_error - - other - percentiles: null - histogram_buckets: null - alert_severity_thresholds: - p2: "reconcile_error, subscriber_overflow, 또는 끊김이 5m 동안 계속" - owner_branch: redis-production-capability - log_field_mapping: [cache_name, event] - compatibility_impact: additive - required_test: contract-verification:metrics-cardinality + source: "src/bootstrap/outbox-relay/src/main/java/dev/caskeleton/composition/outbox/OutboxMetrics.java" # === Redis 연결 lane === # source: review 2026-11-03 RR-04-02 — 캐시의 조건부 쓰기는 자기 lane(CACHE_SCRIPT)을 받았다. 캐시 채우기가 @@ -565,6 +390,7 @@ metrics: log_field_mapping: [lane, outcome] compatibility_impact: additive required_test: contract-verification:metrics-cardinality + source: "src/adapter/outbound/redis-runtime/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/runtime/config/RedisLaneMetrics.java" - name: redis.lane.acquire.refused.total type: counter @@ -586,6 +412,7 @@ metrics: log_field_mapping: [lane, reason] compatibility_impact: additive required_test: contract-verification:metrics-cardinality + source: "src/adapter/outbound/redis-runtime/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/runtime/config/RedisLaneMetrics.java" - name: redis.lane.connections.opened.total type: counter @@ -603,6 +430,7 @@ metrics: log_field_mapping: [lane] compatibility_impact: additive required_test: contract-verification:metrics-cardinality + source: "src/adapter/outbound/redis-runtime/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/runtime/config/RedisLaneMetrics.java" - name: redis.lane.connections.discarded.total type: counter @@ -623,6 +451,7 @@ metrics: log_field_mapping: [lane, reason] compatibility_impact: additive required_test: contract-verification:metrics-cardinality + source: "src/adapter/outbound/redis-runtime/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/runtime/config/RedisLaneMetrics.java" - name: redis.lane.connections.active type: gauge @@ -640,6 +469,7 @@ metrics: log_field_mapping: [lane] compatibility_impact: additive required_test: contract-verification:metrics-cardinality + source: "src/adapter/outbound/redis-runtime/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/runtime/config/RedisLaneMetrics.java" - name: redis.lane.connections.pending type: gauge @@ -657,6 +487,7 @@ metrics: log_field_mapping: [lane] compatibility_impact: additive required_test: contract-verification:metrics-cardinality + source: "src/adapter/outbound/redis-runtime/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/runtime/config/RedisLaneMetrics.java" # === 로그 appender === # source: feature-log-management-contract — Sampling Policy (final) @@ -678,6 +509,7 @@ metrics: log_field_mapping: [appender, level] compatibility_impact: additive required_test: contract-verification:metrics-cardinality + source: "src/bootstrap/app/src/main/java/dev/caskeleton/bootstrap/logging/MetricsAsyncAppender.java" # === 분산 추적 === # source: feature-distributed-tracing-contract — decisions @@ -697,6 +529,7 @@ metrics: log_field_mapping: [profile] compatibility_impact: additive required_test: contract-verification:metrics-cardinality + source: "src/bootstrap/service-runtime/src/main/java/dev/caskeleton/composition/runtime/tracing/TracingSamplingRateGauge.java" # === JVM 기본 === # source: feature-metrics-alerting-contract — In scope "JVM/process metric" @@ -717,6 +550,7 @@ metrics: log_field_mapping: [area, id] compatibility_impact: additive required_test: contract-verification:metrics-cardinality + source: "framework: Micrometer JVM binder(Spring Boot)" # source: feature-metrics-alerting-contract — In scope "JVM/process metric" - name: jvm.gc.pause @@ -735,6 +569,7 @@ metrics: log_field_mapping: [action, cause] compatibility_impact: additive required_test: contract-verification:metrics-cardinality + source: "framework: Micrometer JVM binder(Spring Boot)" # source: feature-metrics-alerting-contract — In scope "JVM/process metric" - name: jvm.threads.live @@ -749,6 +584,7 @@ metrics: log_field_mapping: [] compatibility_impact: additive required_test: contract-verification:metrics-cardinality + source: "framework: Micrometer JVM binder(Spring Boot)" # source: feature-metrics-alerting-contract — In scope "JVM/process metric" (process uptime) - name: process.uptime @@ -763,3 +599,1052 @@ metrics: log_field_mapping: [] compatibility_impact: additive required_test: contract-verification:metrics-cardinality + source: "framework: Micrometer process binder(Spring Boot)" + + # === GraphQL (adapter:inbound:graphql를 켤 때) === + # observation 이름이다. timer 하나와 long-task timer(<이름>.active) 하나가 된다. + + # operation 이름은 observed-operation-names 허용 목록 밖이면 하나로 묶인다(GraphQlOperationNameCardinality). + - name: graphql.request + type: timer + unit: seconds + tags: + - name: graphql.operation.name + cardinality_limit: 50 + - name: graphql.operation.type + cardinality_limit: 3 + allowed_values: [QUERY, MUTATION, SUBSCRIPTION] + - name: graphql.client.profile + cardinality_limit: 10 + - name: graphql.persisted + cardinality_limit: 2 + allowed_values: [true, false] + - name: graphql.outcome + cardinality_limit: 5 + - name: error.type + # 오류가 있을 때만 붙는다. + cardinality_limit: 10 + - name: graphql.complexity.bucket + # 복잡도를 셌을 때만 붙는다. + cardinality_limit: 6 + - name: graphql.depth.bucket + cardinality_limit: 6 + percentiles: null + histogram_buckets: null + alert_severity_thresholds: {} + owner_branch: graphql-platform + log_field_mapping: [] + compatibility_impact: additive + required_test: contract-verification:metrics-cardinality + source: "src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/observation/GraphQlObservationNames.java" + constant: GraphQlObservationNames.REQUEST + registered_by: "src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/observation/GraphQlRequestObservationConvention.java" + + # Spring for GraphQL 기본 observation. tag는 Spring 기본 convention(DefaultDataFetcherObservationConvention) + # 그대로다. 이 저장소의 convention bean은 이 두 observation에 붙지 않는다. + - name: graphql.datafetcher + type: timer + unit: seconds + tags: + - name: graphql.outcome + cardinality_limit: 2 + allowed_values: [SUCCESS, ERROR] + - name: graphql.field.name + # schema의 field 이름. schema의 field 수가 상한이다. + cardinality_limit: 500 + - name: graphql.error.type + # 예외 클래스의 단순 이름, 없으면 NONE. + cardinality_limit: 20 + percentiles: null + histogram_buckets: null + alert_severity_thresholds: {} + owner_branch: graphql-platform + log_field_mapping: [] + compatibility_impact: additive + required_test: contract-verification:metrics-cardinality + source: "framework: Spring for GraphQL observation(이름은 GraphQlObservationNames와 같다)" + + - name: graphql.dataloader + type: timer + unit: seconds + tags: + - name: graphql.outcome + cardinality_limit: 2 + allowed_values: [SUCCESS, ERROR] + - name: graphql.loader.name + # 등록한 DataLoader 이름, 모르면 unknown. + cardinality_limit: 50 + - name: graphql.error.type + # 예외 클래스의 단순 이름, 없으면 NONE. + cardinality_limit: 20 + percentiles: null + histogram_buckets: null + alert_severity_thresholds: {} + owner_branch: graphql-platform + log_field_mapping: [] + compatibility_impact: additive + required_test: contract-verification:metrics-cardinality + source: "framework: Spring for GraphQL observation(이름은 GraphQlObservationNames와 같다)" + + # DataLoader 없이 부모마다 풀린 field. 임계를 넘은 요청에 한 번 기록한다(GraphQlPerParentFetchInstrumentation). + - name: graphql.per.parent.fetch + type: timer + unit: seconds + tags: + - name: graphql.schema.coordinate + cardinality_limit: 200 + percentiles: null + histogram_buckets: null + alert_severity_thresholds: {} + owner_branch: graphql-platform + log_field_mapping: [] + compatibility_impact: additive + required_test: contract-verification:metrics-cardinality + source: "src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/observation/GraphQlObservationNames.java" + constant: GraphQlObservationNames.PER_PARENT_FETCH + registered_by: "src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/runtime/GraphQlPerParentFetchInstrumentation.java" + + # === 알림 platform (composition:notification-platform을 켤 때) === + + - name: notification.requested + type: counter + unit: total + tags: + - name: notificationCategory + cardinality_limit: 20 + - name: strategy + cardinality_limit: 5 + percentiles: null + histogram_buckets: null + alert_severity_thresholds: {} + owner_branch: notification-platform + log_field_mapping: [] + compatibility_impact: additive + required_test: contract-verification:metrics-cardinality + source: "src/application/notification/src/main/java/dev/caskeleton/application/notification/platform/observation/NotificationMetricName.java" + constant: NotificationMetricName.REQUESTED + registered_by: "src/application/notification/src/main/java/dev/caskeleton/application/notification/platform/dispatch/NotificationSubmissionService.java" + + - name: notification.suppressed + type: counter + unit: total + tags: + - name: channel + cardinality_limit: 5 + - name: reason + cardinality_limit: 10 + percentiles: null + histogram_buckets: null + alert_severity_thresholds: {} + owner_branch: notification-platform + log_field_mapping: [] + compatibility_impact: additive + required_test: contract-verification:metrics-cardinality + source: "src/application/notification/src/main/java/dev/caskeleton/application/notification/platform/observation/NotificationMetricName.java" + constant: NotificationMetricName.SUPPRESSED + registered_by: "src/application/notification/src/main/java/dev/caskeleton/application/notification/platform/dispatch/DispatchPipeline.java" + + - name: notification.dispatch + type: counter + unit: total + tags: + - name: channel + cardinality_limit: 5 + - name: provider + cardinality_limit: 20 + - name: result + cardinality_limit: 8 + percentiles: null + histogram_buckets: null + alert_severity_thresholds: {} + owner_branch: notification-platform + log_field_mapping: [] + compatibility_impact: additive + required_test: contract-verification:metrics-cardinality + source: "src/application/notification/src/main/java/dev/caskeleton/application/notification/platform/observation/NotificationMetricName.java" + constant: NotificationMetricName.DISPATCH + registered_by: "src/application/notification/src/main/java/dev/caskeleton/application/notification/platform/dispatch/DispatchOutcomeRecorder.java" + + - name: notification.provider.accepted + type: counter + unit: total + tags: + - name: channel + cardinality_limit: 5 + - name: provider + cardinality_limit: 20 + percentiles: null + histogram_buckets: null + alert_severity_thresholds: {} + owner_branch: notification-platform + log_field_mapping: [] + compatibility_impact: additive + required_test: contract-verification:metrics-cardinality + source: "src/application/notification/src/main/java/dev/caskeleton/application/notification/platform/observation/NotificationMetricName.java" + constant: NotificationMetricName.PROVIDER_ACCEPTED + registered_by: "src/application/notification/src/main/java/dev/caskeleton/application/notification/platform/dispatch/DispatchOutcomeRecorder.java" + + - name: notification.ambiguous + type: counter + unit: total + tags: + - name: channel + cardinality_limit: 5 + - name: provider + cardinality_limit: 20 + percentiles: null + histogram_buckets: null + alert_severity_thresholds: {} + owner_branch: notification-platform + log_field_mapping: [] + compatibility_impact: additive + required_test: contract-verification:metrics-cardinality + source: "src/application/notification/src/main/java/dev/caskeleton/application/notification/platform/observation/NotificationMetricName.java" + constant: NotificationMetricName.AMBIGUOUS + registered_by: "src/application/notification/src/main/java/dev/caskeleton/application/notification/platform/dispatch/DispatchOutcomeRecorder.java" + + - name: notification.delivery + type: counter + unit: total + tags: + - name: channel + cardinality_limit: 5 + - name: provider + cardinality_limit: 20 + - name: outcome + cardinality_limit: 6 + percentiles: null + histogram_buckets: null + alert_severity_thresholds: {} + owner_branch: notification-platform + log_field_mapping: [] + compatibility_impact: additive + required_test: contract-verification:metrics-cardinality + source: "src/application/notification/src/main/java/dev/caskeleton/application/notification/platform/observation/NotificationMetricName.java" + constant: NotificationMetricName.DELIVERY + registered_by: "src/application/notification/src/main/java/dev/caskeleton/application/notification/platform/callback/ProviderEventProjectionService.java" + + - name: notification.callback + type: counter + unit: total + tags: + - name: provider + cardinality_limit: 20 + - name: result + cardinality_limit: 8 + percentiles: null + histogram_buckets: null + alert_severity_thresholds: {} + owner_branch: notification-platform + log_field_mapping: [] + compatibility_impact: additive + required_test: contract-verification:metrics-cardinality + source: "src/application/notification/src/main/java/dev/caskeleton/application/notification/platform/observation/NotificationMetricName.java" + constant: NotificationMetricName.CALLBACK + registered_by: "src/application/notification/src/main/java/dev/caskeleton/application/notification/platform/callback/IngestProviderCallbackApplicationUseCase.java" + + - name: notification.reconciliation + type: counter + unit: total + tags: + - name: provider + cardinality_limit: 20 + - name: correction + cardinality_limit: 5 + percentiles: null + histogram_buckets: null + alert_severity_thresholds: {} + owner_branch: notification-platform + log_field_mapping: [] + compatibility_impact: additive + required_test: contract-verification:metrics-cardinality + source: "src/application/notification/src/main/java/dev/caskeleton/application/notification/platform/observation/NotificationMetricName.java" + constant: NotificationMetricName.RECONCILIATION + registered_by: "src/application/notification/src/main/java/dev/caskeleton/application/notification/platform/dispatch/ReconciliationService.java" + + - name: notification.queue.depth + type: gauge + unit: total + tags: [] + percentiles: null + histogram_buckets: null + alert_severity_thresholds: {} + owner_branch: notification-platform + log_field_mapping: [] + compatibility_impact: additive + required_test: contract-verification:metrics-cardinality + source: "src/application/notification/src/main/java/dev/caskeleton/application/notification/platform/observation/NotificationMetricName.java" + constant: NotificationMetricName.QUEUE_DEPTH + registered_by: "src/adapter/outbound/notification/src/main/java/dev/caskeleton/adapter/outbound/notification/platform/dispatch/NotificationSchedulerWorker.java" + + # === outbound HTTP client (adapter:outbound:httpclient를 켤 때) === + # Spring의 RestClient observation은 끄고 이 이름으로 기록한다(tag 이름도 이 leaf 것이다). attempt의 outcome은 + # success|failure, 논리 호출은 ambiguous도 있다. + + - name: http.client.attempts + type: counter + unit: total + tags: + - name: clientName + cardinality_limit: 50 + - name: operationName + cardinality_limit: 100 + - name: method + cardinality_limit: 8 + - name: uriTemplate + cardinality_limit: 200 + - name: transport + cardinality_limit: 3 + - name: protocol + cardinality_limit: 3 + percentiles: null + histogram_buckets: null + alert_severity_thresholds: {} + owner_branch: httpclient + log_field_mapping: [] + compatibility_impact: additive + required_test: contract-verification:metrics-cardinality + source: "src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/observation/HttpClientObservationNames.java" + constant: HttpClientObservationNames.ATTEMPT_COUNTER + registered_by: "src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/observation/AttemptObservation.java" + + - name: http.client.requests + type: timer + unit: seconds + tags: + - name: clientName + cardinality_limit: 50 + - name: operationName + cardinality_limit: 100 + - name: method + cardinality_limit: 8 + - name: uriTemplate + cardinality_limit: 200 + - name: transport + cardinality_limit: 3 + - name: protocol + cardinality_limit: 3 + - name: status + cardinality_limit: 40 + - name: evidence + cardinality_limit: 5 + - name: outcome + cardinality_limit: 2 + allowed_values: [success, failure] + percentiles: null + histogram_buckets: null + alert_severity_thresholds: {} + owner_branch: httpclient + log_field_mapping: [] + compatibility_impact: additive + required_test: contract-verification:metrics-cardinality + source: "src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/observation/HttpClientObservationNames.java" + constant: HttpClientObservationNames.ATTEMPT_TIMER + registered_by: "src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/observation/AttemptObservation.java" + + - name: http.client.timeout + type: counter + unit: total + tags: + - name: clientName + cardinality_limit: 50 + - name: operationName + cardinality_limit: 100 + - name: method + cardinality_limit: 8 + - name: uriTemplate + cardinality_limit: 200 + - name: transport + cardinality_limit: 3 + - name: protocol + cardinality_limit: 3 + - name: timeoutType + cardinality_limit: 5 + percentiles: null + histogram_buckets: null + alert_severity_thresholds: {} + owner_branch: httpclient + log_field_mapping: [] + compatibility_impact: additive + required_test: contract-verification:metrics-cardinality + source: "src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/observation/HttpClientObservationNames.java" + constant: HttpClientObservationNames.TIMEOUT + registered_by: "src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/observation/AttemptObservation.java" + + - name: http.client.request.bytes + type: distribution_summary + unit: bytes + tags: + - name: clientName + cardinality_limit: 50 + - name: operationName + cardinality_limit: 100 + - name: method + cardinality_limit: 8 + - name: uriTemplate + cardinality_limit: 200 + - name: transport + cardinality_limit: 3 + - name: protocol + cardinality_limit: 3 + percentiles: null + histogram_buckets: null + alert_severity_thresholds: {} + owner_branch: httpclient + log_field_mapping: [] + compatibility_impact: additive + required_test: contract-verification:metrics-cardinality + source: "src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/observation/HttpClientObservationNames.java" + constant: HttpClientObservationNames.REQUEST_BYTES + registered_by: "src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/observation/AttemptObservation.java" + + - name: http.client.response.bytes + type: distribution_summary + unit: bytes + tags: + - name: clientName + cardinality_limit: 50 + - name: operationName + cardinality_limit: 100 + - name: method + cardinality_limit: 8 + - name: uriTemplate + cardinality_limit: 200 + - name: transport + cardinality_limit: 3 + - name: protocol + cardinality_limit: 3 + percentiles: null + histogram_buckets: null + alert_severity_thresholds: {} + owner_branch: httpclient + log_field_mapping: [] + compatibility_impact: additive + required_test: contract-verification:metrics-cardinality + source: "src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/observation/HttpClientObservationNames.java" + constant: HttpClientObservationNames.RESPONSE_BYTES + registered_by: "src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/observation/AttemptObservation.java" + + - name: http.client.logical.calls + type: timer + unit: seconds + tags: + - name: clientName + cardinality_limit: 50 + - name: operationName + cardinality_limit: 100 + - name: method + cardinality_limit: 8 + - name: uriTemplate + cardinality_limit: 200 + - name: status + cardinality_limit: 40 + - name: evidence + cardinality_limit: 5 + - name: outcome + cardinality_limit: 3 + allowed_values: [success, failure, ambiguous] + percentiles: null + histogram_buckets: null + alert_severity_thresholds: {} + owner_branch: httpclient + log_field_mapping: [] + compatibility_impact: additive + required_test: contract-verification:metrics-cardinality + source: "src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/observation/HttpClientObservationNames.java" + constant: HttpClientObservationNames.LOGICAL_CALL_TIMER + registered_by: "src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/observation/LogicalCallObservation.java" + + - name: http.client.retry.count + type: counter + unit: total + tags: + - name: clientName + cardinality_limit: 50 + - name: operationName + cardinality_limit: 100 + - name: method + cardinality_limit: 8 + - name: uriTemplate + cardinality_limit: 200 + - name: retryReason + cardinality_limit: 10 + percentiles: null + histogram_buckets: null + alert_severity_thresholds: {} + owner_branch: httpclient + log_field_mapping: [] + compatibility_impact: additive + required_test: contract-verification:metrics-cardinality + source: "src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/observation/HttpClientObservationNames.java" + constant: HttpClientObservationNames.RETRY_COUNT + registered_by: "src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/observation/LogicalCallObservation.java" + + - name: http.client.retry.exhausted + type: counter + unit: total + tags: + - name: clientName + cardinality_limit: 50 + - name: operationName + cardinality_limit: 100 + - name: method + cardinality_limit: 8 + - name: uriTemplate + cardinality_limit: 200 + percentiles: null + histogram_buckets: null + alert_severity_thresholds: {} + owner_branch: httpclient + log_field_mapping: [] + compatibility_impact: additive + required_test: contract-verification:metrics-cardinality + source: "src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/observation/HttpClientObservationNames.java" + constant: HttpClientObservationNames.RETRY_EXHAUSTED + registered_by: "src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/observation/LogicalCallObservation.java" + + - name: http.client.ambiguous + type: counter + unit: total + tags: + - name: clientName + cardinality_limit: 50 + - name: operationName + cardinality_limit: 100 + - name: method + cardinality_limit: 8 + - name: uriTemplate + cardinality_limit: 200 + percentiles: null + histogram_buckets: null + alert_severity_thresholds: {} + owner_branch: httpclient + log_field_mapping: [] + compatibility_impact: additive + required_test: contract-verification:metrics-cardinality + source: "src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/observation/HttpClientObservationNames.java" + constant: HttpClientObservationNames.AMBIGUOUS + registered_by: "src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/observation/LogicalCallObservation.java" + + # 값 1 = open, 0 = 그 밖. + - name: http.client.circuit.state + type: gauge + unit: total + tags: + - name: clientName + cardinality_limit: 50 + percentiles: null + histogram_buckets: null + alert_severity_thresholds: {} + owner_branch: httpclient + log_field_mapping: [] + compatibility_impact: additive + required_test: contract-verification:metrics-cardinality + source: "src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/observation/HttpClientObservationNames.java" + constant: HttpClientObservationNames.CIRCUIT_STATE + registered_by: "src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/resilience/ResilienceRejectionRecorder.java" + + - name: http.client.circuit.state.rejected + type: counter + unit: total + tags: + - name: clientName + cardinality_limit: 50 + percentiles: null + histogram_buckets: null + alert_severity_thresholds: {} + owner_branch: httpclient + log_field_mapping: [] + compatibility_impact: additive + required_test: contract-verification:metrics-cardinality + source: "src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/observation/HttpClientObservationNames.java" + constant: HttpClientObservationNames.CIRCUIT_REJECTED + registered_by: "src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/resilience/ResilienceRejectionRecorder.java" + + - name: http.client.ratelimit.rejected + type: counter + unit: total + tags: + - name: clientName + cardinality_limit: 50 + percentiles: null + histogram_buckets: null + alert_severity_thresholds: {} + owner_branch: httpclient + log_field_mapping: [] + compatibility_impact: additive + required_test: contract-verification:metrics-cardinality + source: "src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/observation/HttpClientObservationNames.java" + constant: HttpClientObservationNames.RATE_LIMIT_REJECTED + registered_by: "src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/resilience/ResilienceRejectionRecorder.java" + + - name: http.client.bulkhead.rejected + type: counter + unit: total + tags: + - name: clientName + cardinality_limit: 50 + percentiles: null + histogram_buckets: null + alert_severity_thresholds: {} + owner_branch: httpclient + log_field_mapping: [] + compatibility_impact: additive + required_test: contract-verification:metrics-cardinality + source: "src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/observation/HttpClientObservationNames.java" + constant: HttpClientObservationNames.BULKHEAD_REJECTED + registered_by: "src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/resilience/ResilienceRejectionRecorder.java" + + - name: http.client.ssrf.rejected + type: counter + unit: total + tags: + - name: clientName + cardinality_limit: 50 + - name: outcome + cardinality_limit: 5 + percentiles: null + histogram_buckets: null + alert_severity_thresholds: {} + owner_branch: httpclient + log_field_mapping: [] + compatibility_impact: additive + required_test: contract-verification:metrics-cardinality + source: "src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/observation/HttpClientObservationNames.java" + constant: HttpClientObservationNames.SSRF_REJECTED + registered_by: "src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/dynamic/DefaultDynamicTargetGateway.java" + + - name: http.client.pool.connections + type: gauge + unit: total + tags: + - name: clientName + cardinality_limit: 50 + - name: transport + cardinality_limit: 3 + - name: state + cardinality_limit: 3 + percentiles: null + histogram_buckets: null + alert_severity_thresholds: {} + owner_branch: httpclient + log_field_mapping: [] + compatibility_impact: additive + required_test: contract-verification:metrics-cardinality + source: "src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/observation/HttpClientObservationNames.java" + constant: HttpClientObservationNames.POOL_CONNECTIONS + registered_by: "src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/apache/ApachePoolMetricsBinder.java" + + - name: http.client.pool.pending + type: gauge + unit: total + tags: + - name: clientName + cardinality_limit: 50 + - name: transport + cardinality_limit: 3 + percentiles: null + histogram_buckets: null + alert_severity_thresholds: {} + owner_branch: httpclient + log_field_mapping: [] + compatibility_impact: additive + required_test: contract-verification:metrics-cardinality + source: "src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/observation/HttpClientObservationNames.java" + constant: HttpClientObservationNames.POOL_PENDING + registered_by: "src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/apache/ApachePoolMetricsBinder.java" + + # === 파일 서버 (composition:fileserver-platform을 켤 때) === + + - name: fileserver.upload.duration + type: timer + unit: seconds + tags: + - name: mode + cardinality_limit: 5 + - name: storage + cardinality_limit: 5 + - name: result + cardinality_limit: 6 + - name: size_bucket + cardinality_limit: 6 + percentiles: null + histogram_buckets: null + alert_severity_thresholds: {} + owner_branch: fileserver-platform + log_field_mapping: [] + compatibility_impact: additive + required_test: contract-verification:metrics-cardinality + source: "src/adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/platform/observability/MicrometerFileserverMetrics.java" + + - name: fileserver.download.duration + type: timer + unit: seconds + tags: + - name: transfer_mode + cardinality_limit: 5 + - name: range_type + cardinality_limit: 4 + - name: result + cardinality_limit: 6 + - name: size_bucket + cardinality_limit: 6 + percentiles: null + histogram_buckets: null + alert_severity_thresholds: {} + owner_branch: fileserver-platform + log_field_mapping: [] + compatibility_impact: additive + required_test: contract-verification:metrics-cardinality + source: "src/adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/platform/observability/MicrometerFileserverMetrics.java" + + - name: fileserver.transfer.bytes + type: counter + unit: bytes + tags: + - name: direction + cardinality_limit: 2 + allowed_values: [upload, download] + - name: storage + cardinality_limit: 5 + percentiles: null + histogram_buckets: null + alert_severity_thresholds: {} + owner_branch: fileserver-platform + log_field_mapping: [] + compatibility_impact: additive + required_test: contract-verification:metrics-cardinality + source: "src/adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/platform/observability/MicrometerFileserverMetrics.java" + + - name: fileserver.transfer.active + type: gauge + unit: total + tags: + - name: direction + cardinality_limit: 2 + allowed_values: [upload, download] + - name: instance + cardinality_limit: 50 + percentiles: null + histogram_buckets: null + alert_severity_thresholds: {} + owner_branch: fileserver-platform + log_field_mapping: [] + compatibility_impact: additive + required_test: contract-verification:metrics-cardinality + source: "src/adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/platform/observability/MicrometerFileserverMetrics.java" + + - name: fileserver.transfer.interruption + type: counter + unit: total + tags: + - name: direction + cardinality_limit: 2 + allowed_values: [upload, download] + - name: reason + cardinality_limit: 10 + percentiles: null + histogram_buckets: null + alert_severity_thresholds: {} + owner_branch: fileserver-platform + log_field_mapping: [] + compatibility_impact: additive + required_test: contract-verification:metrics-cardinality + source: "src/adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/platform/observability/MicrometerFileserverMetrics.java" + + - name: fileserver.upload.offset.mismatch + type: counter + unit: total + tags: + - name: mode + cardinality_limit: 5 + - name: client_type + cardinality_limit: 5 + percentiles: null + histogram_buckets: null + alert_severity_thresholds: {} + owner_branch: fileserver-platform + log_field_mapping: [] + compatibility_impact: additive + required_test: contract-verification:metrics-cardinality + source: "src/adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/platform/observability/MicrometerFileserverMetrics.java" + + - name: fileserver.checksum.failure + type: counter + unit: total + tags: + - name: algorithm + cardinality_limit: 5 + - name: stage + cardinality_limit: 5 + percentiles: null + histogram_buckets: null + alert_severity_thresholds: {} + owner_branch: fileserver-platform + log_field_mapping: [] + compatibility_impact: additive + required_test: contract-verification:metrics-cardinality + source: "src/adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/platform/observability/MicrometerFileserverMetrics.java" + + - name: fileserver.verification.queue + type: counter + unit: total + tags: + - name: verifier + cardinality_limit: 5 + - name: verdict + cardinality_limit: 5 + - name: age_bucket + cardinality_limit: 6 + percentiles: null + histogram_buckets: null + alert_severity_thresholds: {} + owner_branch: fileserver-platform + log_field_mapping: [] + compatibility_impact: additive + required_test: contract-verification:metrics-cardinality + source: "src/adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/platform/observability/MicrometerFileserverMetrics.java" + + - name: fileserver.quota + type: counter + unit: total + tags: + - name: scope_type + cardinality_limit: 5 + - name: result + cardinality_limit: 5 + percentiles: null + histogram_buckets: null + alert_severity_thresholds: {} + owner_branch: fileserver-platform + log_field_mapping: [] + compatibility_impact: additive + required_test: contract-verification:metrics-cardinality + source: "src/adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/platform/observability/MicrometerFileserverMetrics.java" + + - name: fileserver.cleanup + type: counter + unit: total + tags: + - name: type + cardinality_limit: 5 + - name: result + cardinality_limit: 5 + percentiles: null + histogram_buckets: null + alert_severity_thresholds: {} + owner_branch: fileserver-platform + log_field_mapping: [] + compatibility_impact: additive + required_test: contract-verification:metrics-cardinality + source: "src/adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/platform/observability/MicrometerFileserverMetrics.java" + + - name: fileserver.download.delegation + type: counter + unit: total + tags: + - name: size_bucket + cardinality_limit: 6 + - name: delegated + cardinality_limit: 2 + allowed_values: [true, false] + percentiles: null + histogram_buckets: null + alert_severity_thresholds: {} + owner_branch: fileserver-platform + log_field_mapping: [] + compatibility_impact: additive + required_test: contract-verification:metrics-cardinality + source: "src/adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/platform/observability/MicrometerFileserverMetrics.java" + + - name: fileserver.access.denial + type: counter + unit: total + tags: + - name: operation + cardinality_limit: 10 + - name: policy_code + cardinality_limit: 20 + percentiles: null + histogram_buckets: null + alert_severity_thresholds: {} + owner_branch: fileserver-platform + log_field_mapping: [] + compatibility_impact: additive + required_test: contract-verification:metrics-cardinality + source: "src/adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/platform/observability/MicrometerFileserverMetrics.java" + + # === MongoDB (adapter:outbound:persistence-mongo를 켤 때) === + + - name: mongodb.driver.command + type: timer + unit: seconds + tags: + - name: mongoProfile + cardinality_limit: 10 + - name: operationType + cardinality_limit: 20 + - name: result + cardinality_limit: 3 + percentiles: null + histogram_buckets: null + alert_severity_thresholds: {} + owner_branch: persistence-mongo + log_field_mapping: [] + compatibility_impact: additive + required_test: contract-verification:metrics-cardinality + source: "src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/observation/MongoCommandObservationListener.java" + + - name: mongodb.driver.pool.checkedout + type: gauge + unit: total + tags: + - name: mongoProfile + cardinality_limit: 10 + percentiles: null + histogram_buckets: null + alert_severity_thresholds: {} + owner_branch: persistence-mongo + log_field_mapping: [] + compatibility_impact: additive + required_test: contract-verification:metrics-cardinality + source: "src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/observation/MongoPoolObservationListener.java" + + - name: mongodb.driver.pool.checkout.waiting + type: gauge + unit: total + tags: + - name: mongoProfile + cardinality_limit: 10 + percentiles: null + histogram_buckets: null + alert_severity_thresholds: {} + owner_branch: persistence-mongo + log_field_mapping: [] + compatibility_impact: additive + required_test: contract-verification:metrics-cardinality + source: "src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/observation/MongoPoolObservationListener.java" + + - name: mongodb.driver.pool.checkout.failed + type: counter + unit: total + tags: + - name: mongoProfile + cardinality_limit: 10 + - name: failureCategory + cardinality_limit: 10 + percentiles: null + histogram_buckets: null + alert_severity_thresholds: {} + owner_branch: persistence-mongo + log_field_mapping: [] + compatibility_impact: additive + required_test: contract-verification:metrics-cardinality + source: "src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/observation/MongoPoolObservationListener.java" + + - name: mongodb.driver.topology.changed + type: counter + unit: total + tags: + - name: mongoProfile + cardinality_limit: 10 + percentiles: null + histogram_buckets: null + alert_severity_thresholds: {} + owner_branch: persistence-mongo + log_field_mapping: [] + compatibility_impact: additive + required_test: contract-verification:metrics-cardinality + source: "src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/observation/MongoSdamObservationListener.java" + + - name: mongodb.driver.primary.changed + type: counter + unit: total + tags: + - name: mongoProfile + cardinality_limit: 10 + percentiles: null + histogram_buckets: null + alert_severity_thresholds: {} + owner_branch: persistence-mongo + log_field_mapping: [] + compatibility_impact: additive + required_test: contract-verification:metrics-cardinality + source: "src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/observation/MongoSdamObservationListener.java" + + - name: mongodb.operation + type: timer + unit: seconds + tags: + - name: mongoProfile + cardinality_limit: 10 + - name: databaseProfile + cardinality_limit: 10 + - name: collectionProfile + cardinality_limit: 50 + - name: operationName + cardinality_limit: 50 + - name: operationType + cardinality_limit: 20 + - name: consistencyProfile + cardinality_limit: 5 + - name: result + cardinality_limit: 8 + - name: failureCategory + cardinality_limit: 21 + percentiles: null + histogram_buckets: null + alert_severity_thresholds: {} + owner_branch: persistence-mongo + log_field_mapping: [] + compatibility_impact: additive + required_test: contract-verification:metrics-cardinality + source: "src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/observation/MicrometerMongoOperationObserver.java" + + # === JPA query 관측 (adapter:outbound:persistence-jpa, 실행기가 MicrometerQueryObservation을 쓸 때) === + - name: jpa.query.duration + type: timer + unit: seconds + tags: + - name: persistence.unit + cardinality_limit: 5 + - name: persistence.operation + cardinality_limit: 10 + - name: persistence.query + # 등록한 QueryName이다(SQL 원문이 아니다). + cardinality_limit: 200 + - name: outcome + cardinality_limit: 6 + - name: failure.category + cardinality_limit: 20 + percentiles: null + histogram_buckets: null + alert_severity_thresholds: {} + owner_branch: persistence-jpa + log_field_mapping: [] + compatibility_impact: additive + required_test: contract-verification:metrics-cardinality + source: "src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/observation/MicrometerQueryObservation.java" + + - name: jpa.query.rows + type: distribution_summary + unit: total + tags: + - name: persistence.unit + cardinality_limit: 5 + - name: persistence.operation + cardinality_limit: 10 + - name: persistence.query + cardinality_limit: 200 + - name: outcome + cardinality_limit: 6 + - name: failure.category + cardinality_limit: 20 + percentiles: null + histogram_buckets: null + alert_severity_thresholds: {} + owner_branch: persistence-jpa + log_field_mapping: [] + compatibility_impact: additive + required_test: contract-verification:metrics-cardinality + source: "src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/observation/MicrometerQueryObservation.java" diff --git a/docs/registries/secrets-classification.yaml b/docs/registries/secrets-classification.yaml index af342bc9..354b4328 100644 --- a/docs/registries/secrets-classification.yaml +++ b/docs/registries/secrets-classification.yaml @@ -15,9 +15,14 @@ # RR-07-04). 비밀값만 본다: 이 파일의 `secret` 행(SecretSourceValidator.CLASSIFIED_SECRETS, # SecretsClassificationRegistryTest가 1:1로 묶음), 모듈이 기여한 비밀, `secret://…/` 참조가 # 가리키는 변수. 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 diff --git a/docs/runbooks/lock-acquisition-timeout.md b/docs/runbooks/lock-acquisition-timeout.md index 4230ae9c..374faa65 100644 --- a/docs/runbooks/lock-acquisition-timeout.md +++ b/docs/runbooks/lock-acquisition-timeout.md @@ -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다. 그 키를 다음에 잡는 쪽이 넘겨받는다. 가장 오래된 살아 있는 행이 오래 쥔 쪽이다. diff --git a/docs/security/rate-limiting.md b/docs/security/rate-limiting.md index 1c810ba5..26c64d5c 100644 --- a/docs/security/rate-limiting.md +++ b/docs/security/rate-limiting.md @@ -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`. diff --git a/docs/upgrade/2026-11-round9-observability.md b/docs/upgrade/2026-11-round9-observability.md new file mode 100644 index 00000000..8de169ca --- /dev/null +++ b/docs/upgrade/2026-11-round9-observability.md @@ -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번 둘 말고 그대로다. 응답 모양도 그대로다. diff --git a/gradle/modules.json b/gradle/modules.json index e12681bf..a8fd44ae 100644 --- a/gradle/modules.json +++ b/gradle/modules.json @@ -329,7 +329,8 @@ "source_path": "src/bootstrap/outbox-relay", "allowed_dependencies": [ "application-core", - "adapter-outbound-support" + "adapter-outbound-support", + "shared-contract" ] }, { diff --git a/scripts/run-compose-runtime-smoke.sh b/scripts/run-compose-runtime-smoke.sh index 12d783e5..1092bc9a 100755 --- a/scripts/run-compose-runtime-smoke.sh +++ b/scripts/run-compose-runtime-smoke.sh @@ -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. diff --git a/src/adapter/inbound/grpc/src/main/java/dev/caskeleton/adapter/inbound/grpc/GrpcCorrelationInterceptor.java b/src/adapter/inbound/grpc/src/main/java/dev/caskeleton/adapter/inbound/grpc/GrpcCorrelationInterceptor.java index 2100cdde..c95b49a5 100644 --- a/src/adapter/inbound/grpc/src/main/java/dev/caskeleton/adapter/inbound/grpc/GrpcCorrelationInterceptor.java +++ b/src/adapter/inbound/grpc/src/main/java/dev/caskeleton/adapter/inbound/grpc/GrpcCorrelationInterceptor.java @@ -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). * *

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 diff --git a/src/adapter/inbound/web/README.md b/src/adapter/inbound/web/README.md index 57ccb72b..4c22ff95 100644 --- a/src/adapter/inbound/web/README.md +++ b/src/adapter/inbound/web/README.md @@ -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 를 읽으면 안 된다. diff --git a/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/auth/AuthErrorResponseWriter.java b/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/auth/AuthErrorResponseWriter.java index 7893d1ba..0d407ae9 100644 --- a/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/auth/AuthErrorResponseWriter.java +++ b/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/auth/AuthErrorResponseWriter.java @@ -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) { diff --git a/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/error/GlobalExceptionHandler.java b/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/error/GlobalExceptionHandler.java index ea56e6ee..4b65bff4 100644 --- a/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/error/GlobalExceptionHandler.java +++ b/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/error/GlobalExceptionHandler.java @@ -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 handleMethodArgumentNotValid( MethodArgumentNotValidException ex, diff --git a/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/filter/RequestLoggingFilter.java b/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/filter/RequestLoggingFilter.java index 23902fdd..3271da41 100644 --- a/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/filter/RequestLoggingFilter.java +++ b/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/filter/RequestLoggingFilter.java @@ -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); } /** diff --git a/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/observability/HeaderSanitizer.java b/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/observability/HeaderSanitizer.java deleted file mode 100644 index dd75b418..00000000 --- a/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/observability/HeaderSanitizer.java +++ /dev/null @@ -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(); - } -} diff --git a/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/observability/LoggedPath.java b/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/observability/LoggedPath.java new file mode 100644 index 00000000..18315541 --- /dev/null +++ b/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/observability/LoggedPath.java @@ -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. + * + *

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. + * + *

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(); + } +} diff --git a/src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/auth/EnvelopeAuthenticationEntryPointTest.java b/src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/auth/EnvelopeAuthenticationEntryPointTest.java index d580043b..d254f963 100644 --- a/src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/auth/EnvelopeAuthenticationEntryPointTest.java +++ b/src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/auth/EnvelopeAuthenticationEntryPointTest.java @@ -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 writerLinesFor(AuthenticationException failure) throws Exception { + return writerLinesFor(failure, "/v1/things"); + } + + private List writerLinesFor(AuthenticationException failure, String path) + throws Exception { Logger logger = (Logger) LoggerFactory.getLogger(AuthErrorResponseWriter.class); ListAppender 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 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. diff --git a/src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/error/GlobalExceptionHandlerTest.java b/src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/error/GlobalExceptionHandlerTest.java index 7b3300d4..635b17e0 100644 --- a/src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/error/GlobalExceptionHandlerTest.java +++ b/src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/error/GlobalExceptionHandlerTest.java @@ -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 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> response = diff --git a/src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/filter/RequestLoggingFilterTest.java b/src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/filter/RequestLoggingFilterTest.java index 1ddfd48d..8eb7320e 100644 --- a/src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/filter/RequestLoggingFilterTest.java +++ b/src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/filter/RequestLoggingFilterTest.java @@ -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 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 { diff --git a/src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/observability/HeaderSanitizerTest.java b/src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/observability/HeaderSanitizerTest.java deleted file mode 100644 index 793dbbbb..00000000 --- a/src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/observability/HeaderSanitizerTest.java +++ /dev/null @@ -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"); - } -} diff --git a/src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/observability/LoggedPathTest.java b/src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/observability/LoggedPathTest.java new file mode 100644 index 00000000..8060f986 --- /dev/null +++ b/src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/observability/LoggedPathTest.java @@ -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}"); + } +} diff --git a/src/adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/platform/observability/MicrometerFileserverMetrics.java b/src/adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/platform/observability/MicrometerFileserverMetrics.java index 19f38bc9..0c71f03b 100644 --- a/src/adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/platform/observability/MicrometerFileserverMetrics.java +++ b/src/adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/platform/observability/MicrometerFileserverMetrics.java @@ -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))); } diff --git a/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/observation/HttpClientObservationNames.java b/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/observation/HttpClientObservationNames.java index 07b76d79..96a687c9 100644 --- a/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/observation/HttpClientObservationNames.java +++ b/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/observation/HttpClientObservationNames.java @@ -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"; diff --git a/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/resilience/ResilienceRejectionRecorder.java b/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/resilience/ResilienceRejectionRecorder.java index a7738acb..5938ff86 100644 --- a/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/resilience/ResilienceRejectionRecorder.java +++ b/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/resilience/ResilienceRejectionRecorder.java @@ -11,7 +11,7 @@ import java.util.function.Supplier; /** * Publishes the local back-pressure signals the platform already produced but never recorded. * - *

{@code http.client.rate_limit.rejected}, {@code http.client.bulkhead.rejected} and {@code + *

{@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 diff --git a/src/adapter/outbound/persistence-jpa/README.md b/src/adapter/outbound/persistence-jpa/README.md index 403e60e6..a22a79a2 100644 --- a/src/adapter/outbound/persistence-jpa/README.md +++ b/src/adapter/outbound/persistence-jpa/README.md @@ -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 마이그레이션 전략 @@ -540,7 +540,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 을 diff --git a/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/lock/DistributedLockPersistenceConfig.java b/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/lock/DistributedLockPersistenceConfig.java index dd242484..c730b058 100644 --- a/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/lock/DistributedLockPersistenceConfig.java +++ b/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/lock/DistributedLockPersistenceConfig.java @@ -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. + * + *

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) { + return new MeteredDistributedLock( + new LockRegistryDistributedLock(new DefaultLockRegistry(), settings.leaseTtl()), + meterRegistry); } /** diff --git a/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/lock/DistributedLockPersistenceConfigTest.java b/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/lock/DistributedLockPersistenceConfigTest.java index 72fe3def..0d647c57 100644 --- a/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/lock/DistributedLockPersistenceConfigTest.java +++ b/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/lock/DistributedLockPersistenceConfigTest.java @@ -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() { diff --git a/src/bootstrap/app/README.md b/src/bootstrap/app/README.md index 0acfa9f7..4116745f 100644 --- a/src/bootstrap/app/README.md +++ b/src/bootstrap/app/README.md @@ -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 위에 마커 기반 확장으로 문서화만 되어 diff --git a/src/bootstrap/app/compose-lanes/lane-services.yaml b/src/bootstrap/app/compose-lanes/lane-services.yaml index 46e65690..401c0c09 100644 --- a/src/bootstrap/app/compose-lanes/lane-services.yaml +++ b/src/bootstrap/app/compose-lanes/lane-services.yaml @@ -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 diff --git a/src/bootstrap/app/src/main/java/dev/caskeleton/bootstrap/logging/LogMaskingPatterns.java b/src/bootstrap/app/src/main/java/dev/caskeleton/bootstrap/logging/LogMaskingPatterns.java index 4fa092d9..8882c90a 100644 --- a/src/bootstrap/app/src/main/java/dev/caskeleton/bootstrap/logging/LogMaskingPatterns.java +++ b/src/bootstrap/app/src/main/java/dev/caskeleton/bootstrap/logging/LogMaskingPatterns.java @@ -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 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)(?{@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 { + + /** 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); + } +} diff --git a/src/bootstrap/app/src/main/java/dev/caskeleton/bootstrap/logging/ResolvedProfileLoggingContextListener.java b/src/bootstrap/app/src/main/java/dev/caskeleton/bootstrap/logging/ResolvedProfileLoggingContextListener.java index dbb3b830..a805ba91 100644 --- a/src/bootstrap/app/src/main/java/dev/caskeleton/bootstrap/logging/ResolvedProfileLoggingContextListener.java +++ b/src/bootstrap/app/src/main/java/dev/caskeleton/bootstrap/logging/ResolvedProfileLoggingContextListener.java @@ -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. * + *

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). + * *

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. */ diff --git a/src/bootstrap/app/src/main/java/dev/caskeleton/bootstrap/logging/SamplingTurboFilter.java b/src/bootstrap/app/src/main/java/dev/caskeleton/bootstrap/logging/SamplingTurboFilter.java index 4240b0cb..703145d9 100644 --- a/src/bootstrap/app/src/main/java/dev/caskeleton/bootstrap/logging/SamplingTurboFilter.java +++ b/src/bootstrap/app/src/main/java/dev/caskeleton/bootstrap/logging/SamplingTurboFilter.java @@ -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. + * + *

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 NEVER_SAMPLED_SEGMENTS = Set.of("audit", "security"); + + private final Map auditLoggers = new ConcurrentHashMap<>(); + private volatile double rate = KEEP_ALL; /** Logback Joran setter — {@code ${LOG_SAMPLING_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)); + } } diff --git a/src/bootstrap/app/src/main/resources/application-local.yml b/src/bootstrap/app/src/main/resources/application-local.yml index e55cd583..f31ad514 100644 --- a/src/bootstrap/app/src/main/resources/application-local.yml +++ b/src/bootstrap/app/src/main/resources/application-local.yml @@ -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: diff --git a/src/bootstrap/app/src/main/resources/logback-spring.xml b/src/bootstrap/app/src/main/resources/logback-spring.xml index f3a8a793..4a564a4b 100644 --- a/src/bootstrap/app/src/main/resources/logback-spring.xml +++ b/src/bootstrap/app/src/main/resources/logback-spring.xml @@ -55,7 +55,8 @@ - + @@ -64,7 +65,8 @@ - + ${LOG_SAMPLING_RATE} @@ -86,7 +88,10 @@ false - {"app":"${APP_NAME}","profile":"${APP_PROFILE}"} + {"app":"${APP_NAME}"} + + trace_id span_id request_id @@ -119,7 +124,10 @@ false - {"app":"${APP_NAME}","profile":"${APP_PROFILE}"} + {"app":"${APP_NAME}"} + + trace_id span_id request_id diff --git a/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/DistributedTracingContractTest.java b/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/DistributedTracingContractTest.java index e2c594d3..dd5d3012 100644 --- a/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/DistributedTracingContractTest.java +++ b/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/DistributedTracingContractTest.java @@ -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 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) diff --git a/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/HeaderRegistryRuntimeAlignmentTest.java b/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/HeaderRegistryRuntimeAlignmentTest.java index 02a0a03b..5f03e8cc 100644 --- a/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/HeaderRegistryRuntimeAlignmentTest.java +++ b/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/HeaderRegistryRuntimeAlignmentTest.java @@ -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 FOR_SERVICE_CONTROLLERS = + Set.of("Idempotency-Key", "If-Match", "If-None-Match"); + private static List> 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 unbacked = new ArrayList<>(); + for (Map 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")) { diff --git a/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/MetricsAlertingContractTest.java b/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/MetricsAlertingContractTest.java index 304d293a..571023d9 100644 --- a/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/MetricsAlertingContractTest.java +++ b/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/MetricsAlertingContractTest.java @@ -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 row = findRow("http.server.requests"); + + // then assertThat(row).as("metrics.yaml must contain an 'http.server.requests' row").isNotNull(); - - List 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 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 row = findRow("dependency.client.requests"); - assertThat(row).as("metrics.yaml must contain a 'dependency.client.requests' row").isNotNull(); - List tagNames = tagNames(row); - assertThat(tagNames) - .as("dependency.client.requests must have tags: dependency_name, dependency_type") - .contains("dependency_name", "dependency_type"); - - //noinspection unchecked - Map thresholds = (Map) 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 row = findRow("hikaricp.connections.acquire"); + + // when + Map 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> tags = (List>) row.get("tags"); - Map 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 allowedValues = (List) outcomeTag.get("allowed_values"); - assertThat(allowedValues) - .as("hikaricp.connections.acquire outcome tag must contain 'TIMEOUT'") - .contains("TIMEOUT"); - - //noinspection unchecked - Map thresholds = (Map) row.get("alert_severity_thresholds"); - assertThat(thresholds) - .as("hikaricp.connections.acquire must have non-empty alert_severity_thresholds") - .isNotNull() - .isNotEmpty(); + assertThat((Map) 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 sloDrivenRows = new TreeSet<>(); + for (Map 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( diff --git a/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/MetricsRegistryCodeAlignmentTest.java b/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/MetricsRegistryCodeAlignmentTest.java new file mode 100644 index 00000000..ffe42a4e --- /dev/null +++ b/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/MetricsRegistryCodeAlignmentTest.java @@ -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. + * + *

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> rows = rows(repository); + MainSources main = MainSources.under(repository.repositoryRoot()); + + // when + List unbacked = new ArrayList<>(); + for (Map 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 rows = new TreeSet<>(); + rows(repository).forEach(row -> rows.add(String.valueOf(row.get("name")))); + + // when + Set registered = registeredMeters(repository); + + // then + assertThat(rows).containsAll(registered); + } + + @Test + @DisplayName("등록 형태마다 meter 하나씩을 찾는다 — 아무것도 못 찾는 scan 은 위 시험을 거짓으로 통과시킨다") + void theScanResolvesOneMeterOfEachRegistrationForm() throws IOException { + // given + RepositoryContractResources repository = RepositoryContractResources.fromSystemProperty(); + + // when + Set 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 registeredMeters(RepositoryContractResources repository) { + Map sources = MainSources.under(repository.repositoryRoot()).all(); + Map qualifiedConstants = new HashMap<>(); + sources.forEach( + (file, text) -> + constants(text) + .forEach( + (constant, value) -> + qualifiedConstants.put( + MainSources.simpleName(file) + "." + constant, value))); + Set registered = new TreeSet<>(); + sources.forEach( + (file, text) -> { + Map 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 constants(String text) { + Map 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> rows(RepositoryContractResources repository) + throws IOException { + Path registry = repository.requireTrackedFile("docs/registries/metrics.yaml"); + try (InputStream in = Files.newInputStream(registry)) { + Map root = new Yaml().load(in); + return (List>) root.get("metrics"); + } + } +} diff --git a/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/SecretsClassificationRegistryTest.java b/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/SecretsClassificationRegistryTest.java index 6dd3794f..6822dd8b 100644 --- a/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/SecretsClassificationRegistryTest.java +++ b/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/SecretsClassificationRegistryTest.java @@ -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 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 classNames = new LinkedHashSet<>(); + try (Stream 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 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 leaked = new java.util.ArrayList<>(); + for (Map 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(); + } } diff --git a/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/StructuredLogFieldContractTest.java b/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/StructuredLogFieldContractTest.java index 799bfeb5..ed488c17 100644 --- a/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/StructuredLogFieldContractTest.java +++ b/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/StructuredLogFieldContractTest.java @@ -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 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 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 } values from the structured JSON appenders. */ private static Set includeMdcKeyNames() throws IOException { String logback = logbackText(); diff --git a/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/support/MainSources.java b/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/support/MainSources.java new file mode 100644 index 00000000..d243c679 --- /dev/null +++ b/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/support/MainSources.java @@ -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. + * + *

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 sources; + + private MainSources(Map 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 sources = new LinkedHashMap<>(); + try (Stream 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 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; + } +} diff --git a/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/support/MainSourcesTest.java b/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/support/MainSourcesTest.java new file mode 100644 index 00000000..c81aba22 --- /dev/null +++ b/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/support/MainSourcesTest.java @@ -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 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); + } +} diff --git a/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/logging/LogMaskingPatternsTest.java b/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/logging/LogMaskingPatternsTest.java index bec38a2c..2db313f6 100644 --- a/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/logging/LogMaskingPatternsTest.java +++ b/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/logging/LogMaskingPatternsTest.java @@ -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); + } } diff --git a/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/logging/ResolvedProfileJsonProviderTest.java b/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/logging/ResolvedProfileJsonProviderTest.java new file mode 100644 index 00000000..b0c99fbd --- /dev/null +++ b/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/logging/ResolvedProfileJsonProviderTest.java @@ -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(); + } +} diff --git a/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/logging/SamplingTurboFilterTest.java b/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/logging/SamplingTurboFilterTest.java index 566ade8e..72028e3f 100644 --- a/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/logging/SamplingTurboFilterTest.java +++ b/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/logging/SamplingTurboFilterTest.java @@ -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); + } } diff --git a/src/bootstrap/fileserver-platform/src/main/java/dev/caskeleton/composition/fileserver/FileserverCleanupWorker.java b/src/bootstrap/fileserver-platform/src/main/java/dev/caskeleton/composition/fileserver/FileserverCleanupWorker.java index fd0a7aae..7098d385 100644 --- a/src/bootstrap/fileserver-platform/src/main/java/dev/caskeleton/composition/fileserver/FileserverCleanupWorker.java +++ b/src/bootstrap/fileserver-platform/src/main/java/dev/caskeleton/composition/fileserver/FileserverCleanupWorker.java @@ -6,7 +6,12 @@ import dev.caskeleton.application.fileserver.cleanup.CleanupBatchResult; import dev.caskeleton.application.fileserver.cleanup.CleanupService; import dev.caskeleton.application.fileserver.recovery.FileReconciliationService; 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; @@ -76,13 +81,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); } } @@ -107,13 +107,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 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); + } } diff --git a/src/bootstrap/fileserver-platform/src/test/java/dev/caskeleton/composition/fileserver/FileserverCleanupWorkerTest.java b/src/bootstrap/fileserver-platform/src/test/java/dev/caskeleton/composition/fileserver/FileserverCleanupWorkerTest.java index bfa8c7b4..9f07c398 100644 --- a/src/bootstrap/fileserver-platform/src/test/java/dev/caskeleton/composition/fileserver/FileserverCleanupWorkerTest.java +++ b/src/bootstrap/fileserver-platform/src/test/java/dev/caskeleton/composition/fileserver/FileserverCleanupWorkerTest.java @@ -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 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)); + } } diff --git a/src/bootstrap/outbox-relay/build.gradle b/src/bootstrap/outbox-relay/build.gradle index fd57af6e..12c4b451 100644 --- a/src/bootstrap/outbox-relay/build.gradle +++ b/src/bootstrap/outbox-relay/build.gradle @@ -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' diff --git a/src/bootstrap/outbox-relay/src/main/java/dev/caskeleton/composition/outbox/OutboxRelayScheduler.java b/src/bootstrap/outbox-relay/src/main/java/dev/caskeleton/composition/outbox/OutboxRelayScheduler.java index 3e63351d..24762db8 100644 --- a/src/bootstrap/outbox-relay/src/main/java/dev/caskeleton/composition/outbox/OutboxRelayScheduler.java +++ b/src/bootstrap/outbox-relay/src/main/java/dev/caskeleton/composition/outbox/OutboxRelayScheduler.java @@ -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 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) { diff --git a/src/bootstrap/outbox-relay/src/test/java/dev/caskeleton/composition/outbox/OutboxRelaySchedulerLoggingTest.java b/src/bootstrap/outbox-relay/src/test/java/dev/caskeleton/composition/outbox/OutboxRelaySchedulerLoggingTest.java index 3e51efe5..394775a3 100644 --- a/src/bootstrap/outbox-relay/src/test/java/dev/caskeleton/composition/outbox/OutboxRelaySchedulerLoggingTest.java +++ b/src/bootstrap/outbox-relay/src/test/java/dev/caskeleton/composition/outbox/OutboxRelaySchedulerLoggingTest.java @@ -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 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 appender) implements AutoCloseable { diff --git a/src/bootstrap/service-runtime/README.md b/src/bootstrap/service-runtime/README.md index d7081f94..ac63d6af 100644 --- a/src/bootstrap/service-runtime/README.md +++ b/src/bootstrap/service-runtime/README.md @@ -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()`로 인스턴스 간 집계할 수 있다. diff --git a/src/bootstrap/service-runtime/src/main/java/dev/caskeleton/composition/runtime/metrics/MetricsDistributionMeterFilter.java b/src/bootstrap/service-runtime/src/main/java/dev/caskeleton/composition/runtime/metrics/MetricsDistributionMeterFilter.java index a8c64772..159c22ea 100644 --- a/src/bootstrap/service-runtime/src/main/java/dev/caskeleton/composition/runtime/metrics/MetricsDistributionMeterFilter.java +++ b/src/bootstrap/service-runtime/src/main/java/dev/caskeleton/composition/runtime/metrics/MetricsDistributionMeterFilter.java @@ -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 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 sloDrivenTimers() { + return SLO_DRIVEN_TIMERS; + } + @Override public DistributionStatisticConfig configure(Meter.Id id, DistributionStatisticConfig config) { if (!SLO_DRIVEN_TIMERS.contains(id.getName())) { diff --git a/src/bootstrap/service-runtime/src/test/java/dev/caskeleton/composition/runtime/metrics/MetricsContractConfigTest.java b/src/bootstrap/service-runtime/src/test/java/dev/caskeleton/composition/runtime/metrics/MetricsContractConfigTest.java index f334e952..3474fb35 100644 --- a/src/bootstrap/service-runtime/src/test/java/dev/caskeleton/composition/runtime/metrics/MetricsContractConfigTest.java +++ b/src/bootstrap/service-runtime/src/test/java/dev/caskeleton/composition/runtime/metrics/MetricsContractConfigTest.java @@ -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(); } } diff --git a/src/bootstrap/service-runtime/src/test/java/dev/caskeleton/composition/runtime/metrics/MetricsDistributionMeterFilterTest.java b/src/bootstrap/service-runtime/src/test/java/dev/caskeleton/composition/runtime/metrics/MetricsDistributionMeterFilterTest.java index 071b57e9..674d7753 100644 --- a/src/bootstrap/service-runtime/src/test/java/dev/caskeleton/composition/runtime/metrics/MetricsDistributionMeterFilterTest.java +++ b/src/bootstrap/service-runtime/src/test/java/dev/caskeleton/composition/runtime/metrics/MetricsDistributionMeterFilterTest.java @@ -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); diff --git a/src/shared-contract/README.md b/src/shared-contract/README.md index dfe9afb5..304cb9a3 100644 --- a/src/shared-contract/README.md +++ b/src/shared-contract/README.md @@ -101,6 +101,9 @@ Spring/Lettuce 타입을 노출하지 않는다. - `DependencyFailureException`: `dependency failure classified as (..., dependency=<이름>)` + 예외. - 그 밖의 5xx carrier: `failure classified as (...)` + 예외. 4xx carrier는 남기지 않는다(응답이지 사고가 아니다). `IDEMPOTENCY_RECOVERY_REQUIRED`는 예외 메시지 끝의 scope digest로 runbook이 기록을 찾는다. +- 요청 없이 도는 일(스케줄러)은 `forBackgroundTask`를 쓴다. persistence 실패는 위와 같이 분류만, 그 밖의 carrier는 + 4xx 코드여도 `failure classified as (...)` + 예외다. 탓할 client가 없으니 4xx 코드도 결함이다(outbox relay, + 파일 서버 정리). - 전송은 자기 상관 정보를 뒤에 붙인다: gRPC ` (method=<서비스/메서드>)`, GraphQL ` (executionId=)`. 예외는 늘 마지막 인자라 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`, diff --git a/src/shared-contract/src/main/java/dev/caskeleton/shared/error/ServerFailureLog.java b/src/shared-contract/src/main/java/dev/caskeleton/shared/error/ServerFailureLog.java index b060ddb4..6d1aebef 100644 --- a/src/shared-contract/src/main/java/dev/caskeleton/shared/error/ServerFailureLog.java +++ b/src/shared-contract/src/main/java/dev/caskeleton/shared/error/ServerFailureLog.java @@ -22,11 +22,13 @@ import java.util.Optional; * by ({@code docs/runbooks/idempotency-unavailable.md}). * * - *

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. + *

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. * *

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 diff --git a/src/shared-contract/src/test/java/dev/caskeleton/shared/error/ServerFailureLogTest.java b/src/shared-contract/src/test/java/dev/caskeleton/shared/error/ServerFailureLogTest.java index f526d674..736a4a08 100644 --- a/src/shared-contract/src/test/java/dev/caskeleton/shared/error/ServerFailureLogTest.java +++ b/src/shared-contract/src/test/java/dev/caskeleton/shared/error/ServerFailureLogTest.java @@ -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 diff --git a/src/shared-contract/src/test/java/dev/caskeleton/shared/metrics/CardinalityBoundsTest.java b/src/shared-contract/src/test/java/dev/caskeleton/shared/metrics/CardinalityBoundsTest.java index c1151a47..a241e846 100644 --- a/src/shared-contract/src/test/java/dev/caskeleton/shared/metrics/CardinalityBoundsTest.java +++ b/src/shared-contract/src/test/java/dev/caskeleton/shared/metrics/CardinalityBoundsTest.java @@ -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); } // ---------------------------------------------------------------- diff --git a/src/shared-contract/src/testFixtures/java/dev/caskeleton/shared/metrics/CardinalityBounds.java b/src/shared-contract/src/testFixtures/java/dev/caskeleton/shared/metrics/CardinalityBounds.java index 66fbec8f..02ce8957 100644 --- a/src/shared-contract/src/testFixtures/java/dev/caskeleton/shared/metrics/CardinalityBounds.java +++ b/src/shared-contract/src/testFixtures/java/dev/caskeleton/shared/metrics/CardinalityBounds.java @@ -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. * *

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 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. * - *

Known keys: {@code status_code}, {@code status}, {@code uri_template}, {@code + *

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 diff --git a/src/shared-contract/src/testFixtures/java/dev/caskeleton/shared/metrics/MetricNaming.java b/src/shared-contract/src/testFixtures/java/dev/caskeleton/shared/metrics/MetricNaming.java index dd8938cf..9ce6f764 100644 --- a/src/shared-contract/src/testFixtures/java/dev/caskeleton/shared/metrics/MetricNaming.java +++ b/src/shared-contract/src/testFixtures/java/dev/caskeleton/shared/metrics/MetricNaming.java @@ -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 ALLOWED_UNITS = Set.of("seconds", "bytes", "total");