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