fix(logging)!: 로그 줄이 원본 경로·SQL을 싣지 않고 감사 줄을 버리지 않게 한다

로그 줄이 남기지 말아야 할 값을 싣고, 남겨야 할 줄을 버린다. 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행.
This commit is contained in:
DongHyeonka
2026-11-13 13:12:09 +09:00
parent e6c3b15959
commit 75df7615e5
31 changed files with 725 additions and 113 deletions
+2 -1
View File
@@ -402,7 +402,8 @@ app:
**Sampling (`SamplingTurboFilter`)**
- **`APP_LOG_SAMPLING_RATE`** — `INFO` 이하 로그를 남길 확률. [0.0, 1.0] float. prod 는 `0.1`(10%
샘플링)이 권장, `WARN`/`ERROR` 는 항상 유지. `1.0` = 샘플링 없음(dev/local/staging 기본).
샘플링)이 권장, `WARN`/`ERROR` 는 항상 유지. 감사·보안 기록(logger 이름의 마지막 마디가 `audit`·`security`, 또는
`AUDIT` marker)도 레벨과 상관없이 유지한다. `1.0` = 샘플링 없음(dev/local/staging 기본).
### 분산 추적
+1
View File
@@ -529,3 +529,4 @@ web 경로의 `W/`는 `src/adapter/inbound/web/src/main/java/dev/caskeleton/adap
| 설정 키 `app.notification.platform.smtp.max-concurrency`(이름 변경 → `dispatch-concurrency`, env `APP_NOTIFICATION_PLATFORM_SMTP_DISPATCH_CONCURRENCY` 그대로) | `NotificationSmtpSettings.java`, `notification.yml` | `0ebb77b5` | P20-new-1 |
| Redis ACL `+@pubsub`·`&prod:*`(application 계정 2개) | `infra/redis-sdk/acl/*.acl` | `0ebb77b5` | P22-new-2 |
| 시험 `ComposeMergeCharacterizationTest` | `src/bootstrap/app/src/integrationTest/java/dev/caskeleton/bootstrap/compose/ComposeMergeCharacterizationTest.java` | `ca1fbfde`(지운 커밋 `23139722`의 부모) | 어느 lane도 고르지 않아 한 번도 돌지 않았다(`integrationTest` lane은 `requires`로 적은 클래스만 고른다). 보던 것(기본·dev 조합 렌더링, 계약 스크립트)은 PR 단계 `verifyComposeProfiles`가 모든 lane으로 본다(2026-11-12 리뷰) |
| `HeaderSanitizer`(로그용 헤더 가림)와 시험 `HeaderSanitizerTest` | `src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/observability/HeaderSanitizer.java`, `src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/observability/HeaderSanitizerTest.java` | `e6c3b159` | 운영 코드가 부르지 않았다. 요청 로그는 헤더를 싣지 않는다 |
@@ -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·헤더 이름과 응답 모양은 그대로다.
+2 -1
View File
@@ -329,7 +329,8 @@
"source_path": "src/bootstrap/outbox-relay",
"allowed_dependencies": [
"application-core",
"adapter-outbound-support"
"adapter-outbound-support",
"shared-contract"
]
},
{
+10 -8
View File
@@ -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 를 읽으면 안 된다.
@@ -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) {
@@ -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<Object> handleMethodArgumentNotValid(
MethodArgumentNotValidException ex,
@@ -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);
}
/**
@@ -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();
}
}
@@ -0,0 +1,70 @@
package dev.caskeleton.adapter.inbound.web.observability;
import jakarta.servlet.http.HttpServletRequest;
import java.util.StringJoiner;
import java.util.regex.Pattern;
import org.springframework.web.servlet.HandlerMapping;
/**
* The path a server log line names a request by.
*
* <p>The matched pattern when the dispatcher found a handler ({@code /v1/orders/{id}}): low
* cardinality and free of identifiers. An unmatched path that Boot's static-resource handler takes
* is named {@code /**} that way. Otherwise — a request the security chain refused before dispatch,
* a request no handler mapping took — the request path with every segment that could carry an
* identifier or a personal value replaced by {@value #HIDDEN}: only a segment of letters and
* hyphens ({@code orders}, {@code notificationTemplates}) or an API version ({@code v1}) stays, and
* at most {@value #MAX_SEGMENTS} segments are kept. The raw {@code getRequestURI()} used to be
* logged on those paths (review 2026-11-12), so an email address, a token or an object id in the
* path reached the log.
*
* <p>The rule is by shape, so it has two known edges. A segment of letters only stays even when it
* is a value ({@code /users/alice}): a service that puts names in paths gets them in these lines
* and should give such routes ids instead. A route literal with a digit or a dot ({@code oauth2},
* {@code .well-known}) is hidden like a value. A matched request is named by its template and has
* neither edge.
*/
public final class LoggedPath {
/** What a segment that may carry a value is replaced by. */
public static final String HIDDEN = "{}";
/** Segments kept before the rest is cut to {@code /...}. */
static final int MAX_SEGMENTS = 8;
private static final Pattern PLAIN_SEGMENT =
Pattern.compile("[A-Za-z][A-Za-z-]{0,39}|v[0-9]{1,3}");
private LoggedPath() {}
/** The matched route template, or the redacted request path. */
public static String of(HttpServletRequest request) {
Object template = request.getAttribute(HandlerMapping.BEST_MATCHING_PATTERN_ATTRIBUTE);
if (template instanceof String matched && !matched.isBlank()) {
return matched;
}
return redacted(request.getRequestURI());
}
/** The path with every segment outside the plain form replaced. */
public static String redacted(String path) {
if (path == null || path.isEmpty() || "/".equals(path)) {
return "/";
}
String[] segments = path.split("/", -1);
StringJoiner out = new StringJoiner("/");
int kept = 0;
for (String segment : segments) {
if (segment.isEmpty()) {
out.add("");
continue;
}
if (kept++ == MAX_SEGMENTS) {
out.add("...");
break;
}
out.add(PLAIN_SEGMENT.matcher(segment).matches() ? segment : HIDDEN);
}
return out.toString();
}
}
@@ -9,6 +9,7 @@ import dev.caskeleton.shared.error.Category;
import dev.caskeleton.shared.error.ClientErrorMessages;
import java.io.IOException;
import java.util.List;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import org.slf4j.LoggerFactory;
@@ -178,13 +179,18 @@ class EnvelopeAuthenticationEntryPointTest {
/** The lines the security writer logs while the entry point answers {@code failure}. */
private List<ILoggingEvent> writerLinesFor(AuthenticationException failure) throws Exception {
return writerLinesFor(failure, "/v1/things");
}
private List<ILoggingEvent> writerLinesFor(AuthenticationException failure, String path)
throws Exception {
Logger logger = (Logger) LoggerFactory.getLogger(AuthErrorResponseWriter.class);
ListAppender<ILoggingEvent> appender = new ListAppender<>();
appender.start();
logger.addAppender(appender);
try {
entryPoint.commence(
new MockHttpServletRequest("GET", "/v1/things"), new MockHttpServletResponse(), failure);
new MockHttpServletRequest("GET", path), new MockHttpServletResponse(), failure);
} finally {
logger.detachAppender(appender);
appender.stop();
@@ -192,6 +198,25 @@ class EnvelopeAuthenticationEntryPointTest {
return appender.list;
}
@Test
@DisplayName("보안 실패 줄은 원본 경로 대신 식별자를 가린 경로를 남긴다(route 를 찾기 전이라 template 이 없다)")
void theSecurityLineNamesARedactedPathNotTheRawOne() throws Exception {
// given
AuthenticationException missing =
new org.springframework.security.authentication.InsufficientAuthenticationException("x");
// when
List<ILoggingEvent> lines = writerLinesFor(missing, "/v1/users/alice@example.com/orders/42");
// then
assertThat(lines)
.singleElement()
.extracting(ILoggingEvent::getFormattedMessage)
.isEqualTo(
"security failure: code=AUTH_TOKEN_MISSING category=AUTH method=GET"
+ " path=/v1/users/{}/orders/{}");
}
@Test
void tokenValueNeverLeaksIntoResponseBodyOrLogs(CapturedOutput output) throws Exception {
// §테스트 계약: a JWT value must never appear in the response or the log output.
@@ -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<ILoggingEvent> appender = new ListAppender<>();
appender.start();
logger.addAppender(appender);
// when
try {
handler.handleUnknown(
new RuntimeException("boom"),
new ServletWebRequest(new MockHttpServletRequest("GET", "/v1/orders/SECRET-0042/items")));
} finally {
logger.detachAppender(appender);
appender.stop();
}
// then
assertThat(appender.list)
.singleElement()
.extracting(ILoggingEvent::getFormattedMessage)
.isEqualTo("unhandled exception on /v1/orders/{}/items");
}
@Test
void internalErrorIsNotRetryableAndHidesMessage() {
ResponseEntity<Envelope<Void>> response =
@@ -12,6 +12,7 @@ import java.util.List;
import java.util.Set;
import java.util.concurrent.atomic.AtomicReference;
import org.junit.jupiter.api.AfterEach;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.slf4j.LoggerFactory;
import org.slf4j.MDC;
@@ -93,6 +94,27 @@ class RequestLoggingFilterTest {
}
}
@Test
@DisplayName("route 를 못 찾은 요청 줄은 원본 경로가 아니라 식별자 마디를 가린 경로를 싣는다")
void anUnmatchedRequestIsLoggedWithTheRedactedPath() throws Exception {
// given
MockHttpServletRequest req = new MockHttpServletRequest("GET", "/v1/orders/SECRET-0042/items");
MockHttpServletResponse res = new MockHttpServletResponse();
ListAppender<ILoggingEvent> listAppender = attachAppender();
// when
String msg;
try {
filter.doFilter(req, res, (rq, rs) -> {});
msg = httpRequestEvent(listAppender).getFormattedMessage();
} finally {
detach(listAppender);
}
// then
assertThat(msg).contains("uri_template=/v1/orders/{}/items").doesNotContain("SECRET-0042");
}
// DRIFT-6: user_principal on MDC must be pseudonymized, never raw
@Test
void putsPseudonymizedUserPrincipalOnMdcNotRawId() throws Exception {
@@ -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");
}
}
@@ -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}");
}
}
+4
View File
@@ -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 위에 마커 기반 확장으로 문서화만 되어
@@ -0,0 +1,41 @@
package dev.caskeleton.bootstrap.logging;
import ch.qos.logback.classic.spi.ILoggingEvent;
import com.fasterxml.jackson.core.JsonGenerator;
import java.io.IOException;
import net.logstash.logback.composite.AbstractFieldJsonProvider;
import net.logstash.logback.composite.JsonWritingUtils;
/**
* Writes the JSON {@code profile} field from the logger context property at the moment each line is
* written.
*
* <p>{@code customFields} in {@code logback-spring.xml} is substituted once, when Logback reads the
* file — before {@link ResolvedProfileLoggingContextListener} replaces the property with the
* resolved profile. So the field kept the environment variable's value (or {@code unresolved})
* while the property beside it was corrected, and the characterization test, which read only the
* property, passed (review 2026-11-12). Reading the property per line is what makes the correction
* reach the line.
*/
public class ResolvedProfileJsonProvider extends AbstractFieldJsonProvider<ILoggingEvent> {
/** The JSON field name. */
static final String FIELD = "profile";
/** What the field says before any profile is known. */
static final String UNRESOLVED = "unresolved";
public ResolvedProfileJsonProvider() {
setFieldName(FIELD);
}
@Override
public void writeTo(JsonGenerator generator, ILoggingEvent event) throws IOException {
String profile =
getContext() == null
? null
: getContext().getProperty(ResolvedProfileLoggingContextListener.PROFILE_PROPERTY);
JsonWritingUtils.writeStringField(
generator, getFieldName(), profile == null || profile.isBlank() ? UNRESOLVED : profile);
}
}
@@ -30,6 +30,10 @@ import org.springframework.core.env.ConfigurableEnvironment;
* sentinel {@code unresolved}; it no longer guesses {@code local}. Once the environment-prepared
* event fires, this listener replaces that sentinel with the resolved profile.
*
* <p>The property is what {@link ResolvedProfileJsonProvider} reads for each JSON line. The JSON
* field used to come from {@code customFields}, which Logback substitutes once when it reads the
* file, so this correction changed the property and not the field (review 2026-11-12).
*
* <p>Registered in {@code META-INF/spring.factories}. A listener for this event cannot be a bean:
* the event fires long before there is a context to hold one.
*/
@@ -4,6 +4,10 @@ import ch.qos.logback.classic.Level;
import ch.qos.logback.classic.Logger;
import ch.qos.logback.classic.turbo.TurboFilter;
import ch.qos.logback.core.spi.FilterReply;
import java.util.Locale;
import java.util.Map;
import java.util.Set;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.ThreadLocalRandom;
import org.slf4j.Marker;
@@ -11,11 +15,27 @@ import org.slf4j.Marker;
* Level-aware log sampler. {@code WARN}/{@code ERROR} are never sampled because they are
* diagnostic/incident signals that must be guaranteed; only {@code INFO} and below are sampled. See
* README for the design rationale.
*
* <p>An audit or security record is never sampled either, whatever its level: a logger whose name
* ends in an {@code audit} or {@code security} segment ({@code notification.audit}, {@code
* dev.caskeleton.fileserver.audit}, {@code notification.security}), or a line carrying the {@value
* #AUDIT_MARKER} marker. The last segment only, so a library package such as {@code
* org.springframework.security.web.FilterChainProxy} is still sampled. The answer is kept per
* logger name: the filter runs before the level check, on every call below WARN. Those loggers
* write at INFO, so at the recommended production rate of 0.1 nine audit records in ten were
* dropped (review 2026-11-12). An audit trail with holes is not one.
*/
public class SamplingTurboFilter extends TurboFilter {
private static final double KEEP_ALL = 1.0d;
/** A marker that exempts one line from sampling, for an audit logger with another name. */
public static final String AUDIT_MARKER = "AUDIT";
private static final Set<String> NEVER_SAMPLED_SEGMENTS = Set.of("audit", "security");
private final Map<String, Boolean> auditLoggers = new ConcurrentHashMap<>();
private volatile double rate = KEEP_ALL;
/** Logback Joran setter — {@code <rate>${LOG_SAMPLING_RATE}</rate>}. */
@@ -46,8 +66,8 @@ public class SamplingTurboFilter extends TurboFilter {
if (level.toInt() >= Level.WARN_INT) {
return FilterReply.NEUTRAL;
}
// <= INFO: keep with probability `rate`.
if (rate >= KEEP_ALL) {
// <= INFO: keep with probability `rate`, audit and security records always.
if (rate >= KEEP_ALL || isAuditRecord(marker, logger)) {
return FilterReply.NEUTRAL;
}
if (rate <= 0.0d) {
@@ -55,4 +75,19 @@ public class SamplingTurboFilter extends TurboFilter {
}
return ThreadLocalRandom.current().nextDouble() < rate ? FilterReply.NEUTRAL : FilterReply.DENY;
}
private boolean isAuditRecord(Marker marker, Logger logger) {
// The marker's own name: SLF4J 2 deprecates marker references, so a line carries the AUDIT
// marker itself rather than one that refers to it.
if (marker != null && AUDIT_MARKER.equals(marker.getName())) {
return true;
}
return logger != null
&& auditLoggers.computeIfAbsent(logger.getName(), SamplingTurboFilter::endsInAuditSegment);
}
private static boolean endsInAuditSegment(String loggerName) {
String last = loggerName.substring(loggerName.lastIndexOf('.') + 1);
return NEVER_SAMPLED_SEGMENTS.contains(last.toLowerCase(Locale.ROOT));
}
}
@@ -55,7 +55,8 @@
<springProperty scope="context" name="JSON_LOGGER_NAME_LENGTH"
source="app.logging.json.logger-name-length" defaultValue="0"/>
<!-- D5/D8: ≤INFO sampling rate (prod 0.1 = 10%); WARN/ERROR always kept. -->
<!-- D5/D8: ≤INFO sampling rate (prod 0.1 = 10%); WARN/ERROR always kept, and so are audit and
security records at any level (SamplingTurboFilter). -->
<springProperty scope="context" name="LOG_SAMPLING_RATE"
source="app.logging.sampling-rate" defaultValue="1.0"/>
@@ -64,7 +65,8 @@
<conversionRule conversionWord="maskedMsg"
class="dev.caskeleton.bootstrap.logging.SecretMaskingMessageConverter"/>
<!-- Sampling Policy (final): drop a share of ≤INFO events; WARN/ERROR pass unconditionally. -->
<!-- Sampling Policy (final): drop a share of ≤INFO events; WARN/ERROR, the AUDIT marker and loggers
whose last segment is audit or security pass unconditionally. -->
<turboFilter class="dev.caskeleton.bootstrap.logging.SamplingTurboFilter">
<rate>${LOG_SAMPLING_RATE}</rate>
</turboFilter>
@@ -86,7 +88,10 @@
<appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
<encoder class="net.logstash.logback.encoder.LogstashEncoder">
<includeContext>false</includeContext>
<customFields>{"app":"${APP_NAME}","profile":"${APP_PROFILE}"}</customFields>
<customFields>{"app":"${APP_NAME}"}</customFields>
<!-- profile per line from the context property the resolved environment sets;
customFields is fixed when this file is read (ResolvedProfileJsonProvider). -->
<provider class="dev.caskeleton.bootstrap.logging.ResolvedProfileJsonProvider"/>
<includeMdcKeyName>trace_id</includeMdcKeyName>
<includeMdcKeyName>span_id</includeMdcKeyName>
<includeMdcKeyName>request_id</includeMdcKeyName>
@@ -119,7 +124,10 @@
</rollingPolicy>
<encoder class="net.logstash.logback.encoder.LogstashEncoder">
<includeContext>false</includeContext>
<customFields>{"app":"${APP_NAME}","profile":"${APP_PROFILE}"}</customFields>
<customFields>{"app":"${APP_NAME}"}</customFields>
<!-- profile per line from the context property the resolved environment sets;
customFields is fixed when this file is read (ResolvedProfileJsonProvider). -->
<provider class="dev.caskeleton.bootstrap.logging.ResolvedProfileJsonProvider"/>
<includeMdcKeyName>trace_id</includeMdcKeyName>
<includeMdcKeyName>span_id</includeMdcKeyName>
<includeMdcKeyName>request_id</includeMdcKeyName>
@@ -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 <includeMdcKeyName>} values from the structured JSON appenders. */
private static Set<String> includeMdcKeyNames() throws IOException {
String logback = logbackText();
@@ -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();
}
}
@@ -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);
}
}
@@ -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<Throwable> carrier = ApiErrorCarrier.firstIn(failure);
if (carrier.isPresent()) {
ApiErrorCode code = ((ApiErrorCarrier) carrier.get()).errorCode();
ServerFailureLog line = ServerFailureLog.forBackgroundTask(carrier.get(), code);
LOG.warn(line.format("; " + message), line.arguments(fields));
return;
}
Object[] withFailure = Arrays.copyOf(fields, fields.length + 1);
withFailure[fields.length] = failure;
LOG.warn(message, withFailure);
}
}
@@ -1,14 +1,23 @@
package dev.caskeleton.composition.fileserver;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.tuple;
import ch.qos.logback.classic.Level;
import ch.qos.logback.classic.Logger;
import ch.qos.logback.classic.spi.ILoggingEvent;
import ch.qos.logback.core.read.ListAppender;
import dev.caskeleton.application.fileserver.api.FileId;
import dev.caskeleton.application.fileserver.cleanup.CleanupBatchResult;
import dev.caskeleton.application.fileserver.recovery.FileReconciliationService;
import dev.caskeleton.application.fileserver.recovery.ReconciliationResult;
import dev.caskeleton.shared.error.OperationalError;
import dev.caskeleton.shared.error.PersistenceFailureException;
import java.util.ArrayList;
import java.util.List;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.slf4j.LoggerFactory;
class FileserverCleanupWorkerTest {
@@ -61,4 +70,40 @@ class FileserverCleanupWorkerTest {
// then
assertThat(reconciled).containsExactly(25);
}
@Test
@DisplayName("분류된 persistence 실패는 분류만 WARN 으로 남기고 SQL·값을 담은 원인 사슬을 붙이지 않는다")
void aClassifiedCleanupFailureIsLoggedWithoutItsCause() {
// given
FileserverCleanupWorker worker =
new FileserverCleanupWorker(
(maxItems, maxBytes) -> {
throw new PersistenceFailureException(
OperationalError.DB_UNAVAILABLE,
"SECRET_SQL delete from file_metadata where id=7",
new IllegalStateException("SECRET_SQL cause"));
},
reconciliation,
25,
1024);
Logger logger = (Logger) LoggerFactory.getLogger(FileserverCleanupWorker.class);
ListAppender<ILoggingEvent> appender = new ListAppender<>();
appender.start();
logger.addAppender(appender);
// when
try {
worker.runBatch();
} finally {
logger.detachAppender(appender);
}
// then
assertThat(appender.list)
.extracting(
ILoggingEvent::getLevel,
event -> event.getFormattedMessage().contains("SECRET_SQL"),
event -> event.getThrowableProxy() == null)
.containsExactly(tuple(Level.WARN, false, true));
}
}
+3
View File
@@ -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'
@@ -5,6 +5,11 @@ import static net.logstash.logback.argument.StructuredArguments.kv;
import dev.caskeleton.application.outbox.OutboxRelayResult;
import dev.caskeleton.application.outbox.PublishPendingOutboxEventsCommand;
import dev.caskeleton.application.outbox.PublishPendingOutboxEventsUseCase;
import dev.caskeleton.shared.error.ApiErrorCarrier;
import dev.caskeleton.shared.error.ApiErrorCode;
import dev.caskeleton.shared.error.ServerFailureLog;
import java.util.Arrays;
import java.util.Optional;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.context.SmartLifecycle;
@@ -112,16 +117,38 @@ public class OutboxRelayScheduler implements SmartLifecycle {
} while (!stopRequested && result.publishedAny() && cycles < MAX_CYCLES_PER_TICK);
} catch (Exception ex) {
log.error(
"outbox relay scheduler: unexpected error in relay cycle — "
+ "relay will retry on the next tick",
kv("capability", "outbox"),
kv("operation", "relay"),
kv("retry.disposition", "next-tick"),
ex);
logRelayFailure(ex);
}
}
/**
* One line per failed tick. A classified failure is written as every transport writes it ({@link
* ServerFailureLog}): a persistence failure by its classification only, because its cause holds
* SQL, constraint names and values; any other carrier, client-side code included, with its stack
* ({@link ServerFailureLog#forBackgroundTask}). The whole exception used to be attached whatever
* it was (review 2026-11-12). An unclassified failure is a defect and keeps its stack.
*/
private static void logRelayFailure(Exception failure) {
Object[] fields = {
kv("capability", "outbox"), kv("operation", "relay"), kv("retry.disposition", "next-tick")
};
Optional<Throwable> carrier = ApiErrorCarrier.firstIn(failure);
if (carrier.isPresent()) {
ApiErrorCode code = ((ApiErrorCarrier) carrier.get()).errorCode();
ServerFailureLog line = ServerFailureLog.forBackgroundTask(carrier.get(), code);
log.error(
line.format(" in an outbox relay cycle; the relay retries on the next tick"),
line.arguments(fields));
return;
}
Object[] withFailure = Arrays.copyOf(fields, fields.length + 1);
withFailure[fields.length] = failure;
log.error(
"outbox relay scheduler: unexpected error in relay cycle — "
+ "relay will retry on the next tick",
withFailure);
}
@Override
public void start() {
synchronized (monitor) {
@@ -12,8 +12,14 @@ import ch.qos.logback.classic.spi.ILoggingEvent;
import ch.qos.logback.core.read.ListAppender;
import dev.caskeleton.application.outbox.PublishPendingOutboxEventsCommand;
import dev.caskeleton.application.outbox.PublishPendingOutboxEventsUseCase;
import dev.caskeleton.shared.error.ApiErrorCarrier;
import dev.caskeleton.shared.error.ApiErrorCode;
import dev.caskeleton.shared.error.OperationalError;
import dev.caskeleton.shared.error.PersistenceFailureException;
import java.util.Arrays;
import java.util.List;
import java.util.stream.Collectors;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.slf4j.LoggerFactory;
@@ -44,6 +50,63 @@ class OutboxRelaySchedulerLoggingTest {
}
}
@Test
@DisplayName("분류된 persistence 실패는 분류만 남기고 SQL·값을 담은 원인 사슬을 붙이지 않는다")
void aPersistenceFailureIsLoggedByItsClassificationWithoutItsCause() {
// given
PublishPendingOutboxEventsUseCase relay = mock(PublishPendingOutboxEventsUseCase.class);
when(relay.handle(any(PublishPendingOutboxEventsCommand.class)))
.thenThrow(
new PersistenceFailureException(
OperationalError.DB_UNAVAILABLE,
"SECRET_SQL select * from outbox where tenant='acme'",
new IllegalStateException("SECRET_SQL cause")));
OutboxRelayScheduler scheduler = new OutboxRelayScheduler(relay, mock(OutboxMetrics.class));
scheduler.start();
// when
ILoggingEvent event;
try (CapturedLogger captured = capture(OutboxRelayScheduler.class)) {
scheduler.relay();
event = captured.singleEvent();
}
// then
assertThat(
List.of(
event.getFormattedMessage().contains("SECRET_SQL"),
event.getThrowableProxy() == null,
event
.getFormattedMessage()
.startsWith("persistence failure classified as DB_UNAVAILABLE")))
.containsExactly(false, true, true);
}
@Test
@DisplayName("client 쪽 코드를 실은 실패도 스케줄러에서는 결함이라 stack 과 함께 분류해 남긴다")
void aClientSideCarrierInARelayCycleKeepsItsStack() {
// given
PublishPendingOutboxEventsUseCase relay = mock(PublishPendingOutboxEventsUseCase.class);
RuntimeException failure = new ClientSideCarrier();
when(relay.handle(any(PublishPendingOutboxEventsCommand.class))).thenThrow(failure);
OutboxRelayScheduler scheduler = new OutboxRelayScheduler(relay, mock(OutboxMetrics.class));
scheduler.start();
// when
ILoggingEvent event;
try (CapturedLogger captured = capture(OutboxRelayScheduler.class)) {
scheduler.relay();
event = captured.singleEvent();
}
// then
assertThat(event)
.extracting(
e -> e.getFormattedMessage().startsWith("failure classified as BAD_PARAMETER"),
e -> e.getThrowableProxy() == null ? null : e.getThrowableProxy().getClassName())
.containsExactly(true, ClientSideCarrier.class.getName());
}
private static CapturedLogger capture(Class<?> owner) {
Logger logger = (Logger) LoggerFactory.getLogger(owner);
ListAppender<ILoggingEvent> appender = new ListAppender<>();
@@ -61,6 +124,19 @@ class OutboxRelaySchedulerLoggingTest {
return Arrays.stream(arguments).map(String::valueOf).collect(Collectors.joining(" | "));
}
private static final class ClientSideCarrier extends RuntimeException implements ApiErrorCarrier {
private static final long serialVersionUID = 1L;
ClientSideCarrier() {
super("a client-side code raised by server code");
}
@Override
public ApiErrorCode errorCode() {
return OperationalError.BAD_PARAMETER;
}
}
private record CapturedLogger(Logger logger, ListAppender<ILoggingEvent> appender)
implements AutoCloseable {
+3
View File
@@ -101,6 +101,9 @@ Spring/Lettuce 타입을 노출하지 않는다.
- `DependencyFailureException`: `dependency failure classified as <code> (..., dependency=<이름>)` + 예외.
- 그 밖의 5xx carrier: `failure classified as <code> (...)` + 예외. 4xx carrier는 남기지 않는다(응답이지
사고가 아니다). `IDEMPOTENCY_RECOVERY_REQUIRED`는 예외 메시지 끝의 scope digest로 runbook이 기록을 찾는다.
- 요청 없이 도는 일(스케줄러)은 `forBackgroundTask`를 쓴다. persistence 실패는 위와 같이 분류만, 그 밖의 carrier는
4xx 코드여도 `failure classified as <code> (...)` + 예외다. 탓할 client가 없으니 4xx 코드도 결함이다(outbox relay,
파일 서버 정리).
- 전송은 자기 상관 정보를 뒤에 붙인다: gRPC ` (method=<서비스/메서드>)`, GraphQL ` (executionId=<id>)`.
예외는 늘 마지막 인자라 SLF4J가 예외로 받는다.
- 로그 줄은 찾은 carrier 의 타입으로 정한다. 감싼 persistence 실패도 감싼 예외나 SQL 원인 없이 분류 한 줄만 남는다.
@@ -22,11 +22,13 @@ import java.util.Optional;
* by ({@code docs/runbooks/idempotency-unavailable.md}).
* </ul>
*
* <p>A client-side carrier is not logged: it is an answer, not an incident. The line is written in
* the SLF4J style — {@code {}} placeholders, with an attached exception as the last argument — so a
* transport hands {@link #format(String)} and {@link #arguments(Object...)} straight to {@code
* Logger.error}. A transport adds its own correlation (a gRPC method, a GraphQL execution id) as a
* suffix; the failure stays last.
* <p>A client-side carrier is not logged: it is an answer, not an incident. Work no client started
* — a scheduled task — uses {@link #forBackgroundTask} instead, which logs a client-side code like
* a server-side one, exception attached: with no client to blame, it is a defect. The line is
* written in the SLF4J style — {@code {}} placeholders, with an attached exception as the last
* argument — so a transport hands {@link #format(String)} and {@link #arguments(Object...)}
* straight to {@code Logger.error}. A transport adds its own correlation (a gRPC method, a GraphQL
* execution id) as a suffix; the failure stays last.
*
* <p>One line is not an error: {@link #refusedArgument(IllegalArgumentException)}, which every
* transport writes at WARN when it answers an {@link IllegalArgumentException} as {@link
@@ -83,6 +85,25 @@ public final class ServerFailureLog {
return Optional.empty();
}
/**
* The line for a classified failure in work no client started, such as a scheduled task: {@link
* #of}'s line, and for a client-side code the same shape as a server-side one, with the failure
* attached. A client-side code with no client to blame is a defect, so its stack stays; {@link
* #refused} would drop it.
*
* @param failure the carrier found in the task's failure — not a wrapper around it
* @param code the code it carries
*/
public static ServerFailureLog forBackgroundTask(Throwable failure, ApiErrorCode code) {
return of(failure, code)
.orElseGet(
() ->
new ServerFailureLog(
"failure classified as {} (category={}, retryable={})",
new Object[] {code.code(), code.category(), code.retryable()},
failure));
}
/**
* The WARN line for an {@link IllegalArgumentException} a transport answers as {@link
* OperationalError#BAD_PARAMETER}: the request was wrong, so it is not an error, but the line
@@ -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