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