From 75df7615e51301f43fd6fe93e07eced32fb7f637 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 13 Nov 2026 13:12:09 +0900 Subject: [PATCH 1/3] =?UTF-8?q?fix(logging)!:=20=EB=A1=9C=EA=B7=B8=20?= =?UTF-8?q?=EC=A4=84=EC=9D=B4=20=EC=9B=90=EB=B3=B8=20=EA=B2=BD=EB=A1=9C?= =?UTF-8?q?=C2=B7SQL=EC=9D=84=20=EC=8B=A3=EC=A7=80=20=EC=95=8A=EA=B3=A0=20?= =?UTF-8?q?=EA=B0=90=EC=82=AC=20=EC=A4=84=EC=9D=84=20=EB=B2=84=EB=A6=AC?= =?UTF-8?q?=EC=A7=80=20=EC=95=8A=EA=B2=8C=20=ED=95=9C=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 로그 줄이 남기지 말아야 할 값을 싣고, 남겨야 할 줄을 버린다. 401·403 보안 WARN, route를 못 찾은 요청 로그, 처리하지 못한 예외 ERROR가 원본 request URI(식별자·토큰이 든 경로)를 싣는다. outbox relay·파일 서버 정리 스케줄러는 실패를 통째로 남겨 SQL·제약 이름·값이 원인 사슬로 따라간다. SamplingTurboFilter는 INFO 이하를 logger 구분 없이 표본으로 버려 감사 logger의 INFO 줄도 사라진다. JSON 로그 profile 칸은 Logback이 처음 읽은 환경 변수 값이라 Spring이 해석한 profile과 다를 수 있다. HeaderSanitizer는 운영 코드가 부르지 않는 공개 유틸리티로 남아 있다. - LoggedPath: route template이 있으면 그것, 없으면 식별자가 들 수 있는 마디를 {}로 가린 경로. 세 줄이 모두 쓴다. 버린 안: 원본 URI 그대로 두고 문서로 경고(로그 수집기가 이미 받는다). - 스케줄러 실패는 새 ServerFailureLog.forBackgroundTask로 남긴다: 분류된 persistence 실패는 원인 사슬 없이, 그 밖의 carrier는 client 쪽 코드여도 stack과 함께(요청이 없으니 결함이다). composition:outbox-relay에 shared-contract edge를 더한다(gradle/modules.json). - SamplingTurboFilter는 AUDIT marker와 이름 끝 마디가 audit·security인 logger를 표본에서 뺀다(이름별 판정은 캐시). - ResolvedProfileJsonProvider가 줄을 쓸 때의 해석된 profile을 쓴다. - HeaderSanitizer와 시험을 지우고 capability-status 제거 표에 적는다. 위험: 경로를 보던 로그 검색이 가린 경로를 본다. 감사 줄이 표본에서 빠져 양이 늘 수 있다. docs/upgrade/2026-11-round9-observability.md 1~5행. 검증: desktop에서 바뀐 leaf check·:app-bootstrap:test·systemTest· documentContractTest·repositoryContractTest, scripts/verify.sh pr rc=0 (묶음 셋을 합친 트리). 새 시험은 고치기 전 트리에서 실패했다(RED). Refs: RR9-02-09, RR9-02-15, RR9-02-21, RR9-02-22, RR9-02-26 BREAKING CHANGE: 보안·요청·예외 로그 줄의 경로 값과 JSON profile 칸의 출처, HeaderSanitizer 삭제. docs/upgrade/2026-11-round9-observability.md 1~5행. --- docs/build.md | 3 +- docs/capability-status.md | 1 + docs/upgrade/2026-11-round9-observability.md | 23 ++++++ gradle/modules.json | 3 +- src/adapter/inbound/web/README.md | 18 +++-- .../web/auth/AuthErrorResponseWriter.java | 7 +- .../web/error/GlobalExceptionHandler.java | 10 ++- .../web/filter/RequestLoggingFilter.java | 9 +-- .../web/observability/HeaderSanitizer.java | 25 ------ .../inbound/web/observability/LoggedPath.java | 70 +++++++++++++++++ .../EnvelopeAuthenticationEntryPointTest.java | 27 ++++++- .../web/error/GlobalExceptionHandlerTest.java | 28 +++++++ .../web/filter/RequestLoggingFilterTest.java | 22 ++++++ .../observability/HeaderSanitizerTest.java | 39 ---------- .../web/observability/LoggedPathTest.java | 48 ++++++++++++ src/bootstrap/app/README.md | 4 + .../logging/ResolvedProfileJsonProvider.java | 41 ++++++++++ ...ResolvedProfileLoggingContextListener.java | 4 + .../logging/SamplingTurboFilter.java | 39 +++++++++- .../app/src/main/resources/logback-spring.xml | 16 +++- .../StructuredLogFieldContractTest.java | 22 ++++++ .../ResolvedProfileJsonProviderTest.java | 56 ++++++++++++++ .../logging/SamplingTurboFilterTest.java | 61 +++++++++++++++ .../fileserver/FileserverCleanupWorker.java | 47 +++++++++--- .../FileserverCleanupWorkerTest.java | 45 +++++++++++ src/bootstrap/outbox-relay/build.gradle | 3 + .../outbox/OutboxRelayScheduler.java | 41 ++++++++-- .../OutboxRelaySchedulerLoggingTest.java | 76 +++++++++++++++++++ src/shared-contract/README.md | 3 + .../shared/error/ServerFailureLog.java | 31 ++++++-- .../shared/error/ServerFailureLogTest.java | 16 ++++ 31 files changed, 725 insertions(+), 113 deletions(-) create mode 100644 docs/upgrade/2026-11-round9-observability.md delete mode 100644 src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/observability/HeaderSanitizer.java create mode 100644 src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/observability/LoggedPath.java delete mode 100644 src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/observability/HeaderSanitizerTest.java create mode 100644 src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/observability/LoggedPathTest.java create mode 100644 src/bootstrap/app/src/main/java/dev/caskeleton/bootstrap/logging/ResolvedProfileJsonProvider.java create mode 100644 src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/logging/ResolvedProfileJsonProviderTest.java 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 2302c0a3..04576260 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/upgrade/2026-11-round9-observability.md b/docs/upgrade/2026-11-round9-observability.md new file mode 100644 index 00000000..85ff2e3b --- /dev/null +++ b/docs/upgrade/2026-11-round9-observability.md @@ -0,0 +1,23 @@ +# 업그레이드 안내 — 2026-11 관측 registry·로그 내용·로컬 비밀 기본값 + +- 범위: 2026-11-12 전체 리뷰의 로그 내용 묶음을 고친 변경. 로그 줄이 원본 경로·SQL·요청 값을 덜 싣게 했다. +- 근거: 2026-11-12 전체 리뷰(`docs/reviews/2026-11-12-round9-review/`)의 RR9-02-09·15·21·22·26 + +## 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`를 부르던 서비스 | + +## 3. 바뀌지 않은 것 + +- 지표·MDC key·헤더 이름과 응답 모양은 그대로다. 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/src/adapter/inbound/web/README.md b/src/adapter/inbound/web/README.md index 69345a97..9c596966 100644 --- a/src/adapter/inbound/web/README.md +++ b/src/adapter/inbound/web/README.md @@ -502,20 +502,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 617b1500..12e8afba 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; @@ -210,11 +211,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 faf2ac72..17709e84 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 @@ -31,6 +31,7 @@ import java.time.Duration; import java.util.List; import java.util.Map; import java.util.Set; +import org.junit.jupiter.api.DisplayName; import org.junit.jupiter.api.Test; import org.slf4j.LoggerFactory; import org.slf4j.MDC; @@ -362,6 +363,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/bootstrap/app/README.md b/src/bootstrap/app/README.md index 0acfa9f7..afe37cd4 100644 --- a/src/bootstrap/app/README.md +++ b/src/bootstrap/app/README.md @@ -346,6 +346,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/src/main/java/dev/caskeleton/bootstrap/logging/ResolvedProfileJsonProvider.java b/src/bootstrap/app/src/main/java/dev/caskeleton/bootstrap/logging/ResolvedProfileJsonProvider.java new file mode 100644 index 00000000..660d3190 --- /dev/null +++ b/src/bootstrap/app/src/main/java/dev/caskeleton/bootstrap/logging/ResolvedProfileJsonProvider.java @@ -0,0 +1,41 @@ +package dev.caskeleton.bootstrap.logging; + +import ch.qos.logback.classic.spi.ILoggingEvent; +import com.fasterxml.jackson.core.JsonGenerator; +import java.io.IOException; +import net.logstash.logback.composite.AbstractFieldJsonProvider; +import net.logstash.logback.composite.JsonWritingUtils; + +/** + * Writes the JSON {@code profile} field from the logger context property at the moment each line is + * written. + * + *

{@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/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/StructuredLogFieldContractTest.java b/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/StructuredLogFieldContractTest.java index 799bfeb5..5d374395 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 @@ -100,6 +100,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/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/shared-contract/README.md b/src/shared-contract/README.md index dfe9afb5..f103c2ad 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 원인 없이 분류 한 줄만 남는다. 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 -- 2.54.0 From a7f44d8a8d9d616129b4e26554e2575d249f771b Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 13 Nov 2026 13:12:09 +0900 Subject: [PATCH 2/3] =?UTF-8?q?fix(secrets)!:=20=EB=A1=9C=EC=BB=AC=20?= =?UTF-8?q?=EB=B9=84=EB=B0=80=20=EA=B8=B0=EB=B3=B8=EA=B0=92=EC=9D=84=20=5F?= =?UTF-8?q?=5FLOCAL=5FDEV=5F=20=EA=B7=9C=EC=B9=99=EC=97=90=20=EB=A7=9E?= =?UTF-8?q?=EC=B6=94=EA=B3=A0=20=EA=B0=80=EB=A6=BC=20=EC=95=BD=EC=86=8D?= =?UTF-8?q?=EC=9D=84=20=EA=B5=AC=ED=98=84=EA=B3=BC=20=EB=A7=9E=EC=B6=98?= =?UTF-8?q?=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 로컬 비밀 기본값(compose·lane·application-local의 DB 비밀번호, MinIO root, Keycloak admin)이 __LOCAL_DEV_ 접두어 규칙을 따르지 않아 prod sentinel 검사가 그 값을 알아보지 못한다. secrets-classification.yaml은 구현 없는 masking_rule full_except_last_4를 약속하고, full로 적은 키 일부 (salt·PEM·HMAC/signing key, URI 사용자 정보)를 LogMaskingPatterns가 가리지 않는다. required_test는 없는 시험 이름이다. IP 신뢰 설정을 두 문서가 다르게 적는다(application-local은 framework, rate-limiting은 native). - 기본값을 __LOCAL_DEV_db_password__·__LOCAL_DEV_minio_root__· __LOCAL_DEV_keycloak_admin__로 바꾼다. - masking_rule을 full|userinfo|none 셋으로 줄이고, LogMaskingPatterns의 키 목록을 넓히고 URI userinfo와 여러 줄 PEM 블록 가림을 더한다. 시험이 masking_rule 어휘, required_test 클래스 존재, full·userinfo 행이 실제로 가려지는지 본다. 버린 안: full_except_last_4 구현(끝 네 자리를 남길 값이 없다). - IP 신뢰는 native + 내부 proxy 목록 하나로 적는다. 위험: 로컬 compose 볼륨이 옛 비밀번호로 만들어졌으면 DB 접속이 실패한다 (docs/upgrade/2026-11-round9-observability.md 6행). 운영 값은 바뀌지 않는다. 검증: 위와 같은 desktop 실행(묶음 셋을 합친 트리) rc=0. Refs: RR9-02-10, RR9-02-12, RR9-02-13 BREAKING CHANGE: 로컬 compose·lane의 비밀 기본값이 바뀐다. 옛 볼륨은 지우거나 env로 옛 값을 준다(docs/upgrade/2026-11-round9-observability.md 6~7행). --- .claude/skills/be-security/SKILL.md | 2 +- compose.yaml | 10 +- docs/registries/secrets-classification.yaml | 109 ++++++------------ docs/security/rate-limiting.md | 2 +- docs/upgrade/2026-11-round9-observability.md | 7 +- scripts/run-compose-runtime-smoke.sh | 2 +- src/bootstrap/app/README.md | 3 + .../app/compose-lanes/lane-services.yaml | 6 +- .../bootstrap/logging/LogMaskingPatterns.java | 33 +++++- .../src/main/resources/application-local.yml | 6 +- .../SecretsClassificationRegistryTest.java | 65 +++++++++++ .../logging/LogMaskingPatternsTest.java | 93 +++++++++++++++ 12 files changed, 246 insertions(+), 92 deletions(-) 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/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/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 index 85ff2e3b..35ff8444 100644 --- a/docs/upgrade/2026-11-round9-observability.md +++ b/docs/upgrade/2026-11-round9-observability.md @@ -1,7 +1,8 @@ # 업그레이드 안내 — 2026-11 관측 registry·로그 내용·로컬 비밀 기본값 -- 범위: 2026-11-12 전체 리뷰의 로그 내용 묶음을 고친 변경. 로그 줄이 원본 경로·SQL·요청 값을 덜 싣게 했다. -- 근거: 2026-11-12 전체 리뷰(`docs/reviews/2026-11-12-round9-review/`)의 RR9-02-09·15·21·22·26 +- 범위: 2026-11-12 전체 리뷰의 로그 내용 묶음과 비밀·IP 문서 묶음을 고친 변경. 로그 줄이 원본 경로·SQL·요청 값을 덜 + 싣게 했고, 로컬 비밀 기본값을 `__LOCAL_DEV_` 규칙에 맞췄다. +- 근거: 2026-11-12 전체 리뷰(`docs/reviews/2026-11-12-round9-review/`)의 RR9-02-09·10·12·13·15·21·22·26 ## 1. 누가 읽나 @@ -17,6 +18,8 @@ compose로 개발하는 사람이다. | 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에 행을 더한 서비스 | ## 3. 바뀌지 않은 것 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/bootstrap/app/README.md b/src/bootstrap/app/README.md index afe37cd4..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 블롭 같은 난독화된 형태는 놓칠 수 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)(? 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/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); + } } -- 2.54.0 From 354b7fc95934a5e875b955bda6163e816f5b46d4 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 13 Nov 2026 13:12:27 +0900 Subject: [PATCH 3/3] =?UTF-8?q?fix(observability)!:=20=EC=A7=80=ED=91=9C?= =?UTF-8?q?=C2=B7MDC=C2=B7=ED=97=A4=EB=8D=94=20registry=EB=A5=BC=20?= =?UTF-8?q?=EC=BD=94=EB=93=9C=EA=B0=80=20=EC=8B=A4=EC=A0=9C=EB=A1=9C=20?= =?UTF-8?q?=EB=82=B4=EB=8A=94=20=EA=B2=83=EA=B3=BC=20=EB=A7=9E=EC=B6=98?= =?UTF-8?q?=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 관측 registry가 코드와 양쪽으로 어긋난다. metrics.yaml에는 아무 코드도 등록하지 않는 행 열하나와 코드에 없는 tag 값이 있고, 코드가 등록하는 graphql·notification·http.client·fileserver·mongodb·jpa.query 지표 다수가 없다. mdc-keys.yaml은 18키 중 코드가 넣는 5키만 맞고 required_in이 틀렸다. headers.yaml은 X-Request-Id·X-Correlation-Id를 ulid로 적고 아무도 쓰지 않는 Deprecation·Sunset·tracestate를 적는다. 전송마다 correlation 규칙이 다른데 registry는 하나로 적는다. 단일 인스턴스 in-process lock은 lock.acquisition을 세지 않아 그 지표가 0이다. 밑줄 든 meter 이름 둘이 이름 규칙을 어긴다. - 행마다 등록하는 main 파일(source)·상수(constant)·등록 주체 (registered_by)를 적고, MetricsRegistryCodeAlignmentTest가 행 → 코드(이름이 상수면 그 상수를 쓰는 곳까지)와 코드(글자·상수 이름의 builder·registry· Metrics 호출) → 행 두 방향을 본다. 템플릿이 부르지 않는 공개 메서드로만 생기는 job.* 행은 emitted_when을 적는다. 버린 안: 행만 지우기(새 지표가 다시 빠진다). - mdc-keys는 5키와 전송별 표, headers는 source가 든 33행(서비스 controller용 상수는 service: 출처), StructuredLog·HeaderRegistry 시험이 코드 상수와 집합을 대조한다. 두 registry 시험은 시험 도우미 MainSources를 같이 쓴다. - slo_driven 행은 MetricsDistributionMeterFilter 대상과 같은 집합이다(두 방향 시험). histogram을 켜지 않는 hikaricp timer 행은 평균으로 경보한다. graphql.datafetcher·dataloader 행에 Spring 기본 tag를 적는다. - in-process lock을 MeteredDistributedLock으로 감싼다. - http.client.ratelimit.rejected, fileserver.upload.offset.mismatch로 이름을 바꾸고 http.client.circuit.state.rejected를 상수로 둔다. - CardinalityBounds(status 40·outcome 6·uri), MetricNaming 단위 규칙, SLO filter 대상(http.server.requests·jvm.gc.pause)을 문서와 맞춘다. 위험: 지표 이름 둘이 바뀌고 단일 인스턴스 lock 지표가 생긴다. 그 이름으로 만든 대시보드·경보를 옮겨야 한다(docs/upgrade/2026-11-round9-observability.md 8~13행). ApachePoolMetricsBinder·MongoTransactionRetry 지연은 다른 묶음이 맡는다. 검증: 위와 같은 desktop 실행(묶음 셋을 합친 트리) rc=0. Refs: RR9-02-05, RR9-02-07, RR9-02-08, RR9-02-27, RR9-03-05 BREAKING CHANGE: http.client.rate_limit.rejected → http.client.ratelimit.rejected, fileserver.upload.offset_mismatch → fileserver.upload.offset.mismatch, CardinalityBounds 상수. docs/upgrade/2026-11-round9-observability.md 8~13행. --- .claude/skills/be-observability/SKILL.md | 6 +- docs/httpclient/operations.md | 27 +- docs/registries/headers.yaml | 339 +++- docs/registries/mdc-keys.yaml | 250 +-- docs/registries/metrics.yaml | 1415 ++++++++++++++--- docs/runbooks/lock-acquisition-timeout.md | 7 +- docs/upgrade/2026-11-round9-observability.md | 15 +- .../grpc/GrpcCorrelationInterceptor.java | 6 +- src/adapter/inbound/web/README.md | 16 +- .../MicrometerFileserverMetrics.java | 2 +- .../HttpClientObservationNames.java | 3 +- .../ResilienceRejectionRecorder.java | 4 +- .../outbound/persistence-jpa/README.md | 7 +- .../DistributedLockPersistenceConfig.java | 16 +- .../DistributedLockPersistenceConfigTest.java | 29 + .../DistributedTracingContractTest.java | 19 +- .../HeaderRegistryRuntimeAlignmentTest.java | 57 +- .../contract/MetricsAlertingContractTest.java | 125 +- .../MetricsRegistryCodeAlignmentTest.java | 188 +++ .../StructuredLogFieldContractTest.java | 23 + .../contract/support/MainSources.java | 89 ++ .../contract/support/MainSourcesTest.java | 59 + src/bootstrap/service-runtime/README.md | 10 +- .../MetricsDistributionMeterFilter.java | 21 +- .../metrics/MetricsContractConfigTest.java | 6 +- .../MetricsDistributionMeterFilterTest.java | 36 +- src/shared-contract/README.md | 26 +- .../shared/metrics/CardinalityBoundsTest.java | 30 +- .../shared/metrics/CardinalityBounds.java | 29 +- .../shared/metrics/MetricNaming.java | 6 +- 30 files changed, 2158 insertions(+), 708 deletions(-) create mode 100644 src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/MetricsRegistryCodeAlignmentTest.java create mode 100644 src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/support/MainSources.java create mode 100644 src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/support/MainSourcesTest.java 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/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/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/upgrade/2026-11-round9-observability.md b/docs/upgrade/2026-11-round9-observability.md index 35ff8444..8de169ca 100644 --- a/docs/upgrade/2026-11-round9-observability.md +++ b/docs/upgrade/2026-11-round9-observability.md @@ -1,8 +1,9 @@ # 업그레이드 안내 — 2026-11 관측 registry·로그 내용·로컬 비밀 기본값 -- 범위: 2026-11-12 전체 리뷰의 로그 내용 묶음과 비밀·IP 문서 묶음을 고친 변경. 로그 줄이 원본 경로·SQL·요청 값을 덜 - 싣게 했고, 로컬 비밀 기본값을 `__LOCAL_DEV_` 규칙에 맞췄다. -- 근거: 2026-11-12 전체 리뷰(`docs/reviews/2026-11-12-round9-review/`)의 RR9-02-09·10·12·13·15·21·22·26 +- 범위: 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. 누가 읽나 @@ -20,7 +21,13 @@ compose로 개발하는 사람이다. | 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·헤더 이름과 응답 모양은 그대로다. +- 지표·MDC key·헤더 이름은 위 8번 둘 말고 그대로다. 응답 모양도 그대로다. 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 9c596966..bdc316bc 100644 --- a/src/adapter/inbound/web/README.md +++ b/src/adapter/inbound/web/README.md @@ -484,13 +484,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` 은 없다. --- 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/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/StructuredLogFieldContractTest.java b/src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/StructuredLogFieldContractTest.java index 5d374395..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() 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/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 f103c2ad..304cb9a3 100644 --- a/src/shared-contract/README.md +++ b/src/shared-contract/README.md @@ -383,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 는 런타임에 추가 접미사 @@ -396,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/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"); -- 2.54.0