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
+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 {