Files
clean-architecture-backend-…/docs/web/runbook.md
DongHyeonka 0fded57cb3
pr / done (pull_request) Canceled after 0s
docs(runbooks): runbook 신호를 지금 코드가 내는 응답·로그·지표로 고친다
runbook이 코드가 내지 않는 신호로 장애를 찾게 한다. actuator·cross-tenant
runbook은 아무 코드도 내지 않는 ACTUATOR_FORBIDDEN·AUTHZ_TENANT_MISMATCH를
증상으로 적고, 없는 경보·지표·로그 칸을 적는다. auth runbook은 로그에서
token payload·Authorization 원문을 보라고 하고(남지도 않고 남겨서도 안
된다), 없는 JWKS 캐시 손잡이와 decoder가 읽지 않는 Spring issuer 키를
적는다. rate-limit·dependency runbook은 없는 gateway 지표·헤더·
CACHE_UNAVAILABLE·dependency_name 칸을, web runbook은 연산마다의 TTL,
시험 도구 GracefulShutdownProbe, 없는 tag routeTemplate, 기동이 거부하는
CORS 설정을 「기동은 된다」고 적는다. job runbook은 내는 코드가 없는
JOB_DEAD_LETTER·JOB_TIMEOUT과 job.* 지표에 경보를 걸게 한다.

각 runbook을 지금 코드가 내는 신호로 다시 쓴다: 응답 코드·헤더, 보안
로그 줄 `security failure: code=… path=…`, 요청 로그 줄, ServerFailureLog
의 고정 문구(`dependency failure classified as … dependency=<이름>`,
`persistence failure classified as …`), 실제 설정 키
APP_SECURITY_JWT_ISSUER, registry에 있는 지표. 이 템플릿에 경보 규칙이
없다는 것, 내는 코드가 없는 코드·지표는 서비스가 낼 때만 있다는 것을
적는다. 진단 순서도 고친다: actuator 노출은 관리 포트 9001로 가르고,
INTERNAL_AUTH_MISCONFIGURATION은 issuer discovery(4xx·issuer 불일치·
jwks_uri 없음은 500, 연결 실패·5xx·JSON 아님은 503)부터, 종료 예산은
웹 drain 30s + async 19s + preStop의 합으로 본다. 같은 원인의 다른
자리(경보 이름을 지어 적은 job·outbox·internal-error-spike, traceId로
적은 칸, 지적 밖 auth·dependency·db·outbox runbook, error-codes.yaml 주석,
같은 틀린 신호를 적은 shared-contract README·web README·
DependencyFailureException Javadoc)도 고치고, 본문의 리뷰 ID는 지운다.

버린 안: 선언만 있는 두 코드를 내는 WARN·counter를 새로 만들기. actuator
노출 밖 경로는 메인 chain이 401 AUTH_TOKEN_MISSING(익명)·404(인증됨)로
답해 403 상황이 없고, cross-tenant는 정한 규칙(남의 것은 404)이라 판정
자리가 서비스 코드에 있다. 새 신호는 서비스가 더할 일로 runbook에 적는다.

위험: 문서만 바뀐다. runbook은 모두 status 초안으로 둔다.
dependency-unavailable이 적은 hikaricp.connections.pending·timeout 행과
job.* 행의 emitted_when은 관측 registry 변경(같은 묶음의 다른 PR)이
더하고, auth-jwks-unavailable의 「캐시가 지난 뒤 503」은 인증 PR의 JWKS
재조회 분류 수정이 만든다. 세 PR을 함께 병합한다.

검증: python3 scripts/check-docs.py·check-work-docs.py OK, desktop
:app-bootstrap:documentContractTest :app-bootstrap:repositoryContractTest,
scripts/verify.sh pr rc=0.

Refs: RR9-02-04, RR9-02-24, RR9-04-34, RR9-04-37
2026-11-13 09:35:50 +09:00

7.0 KiB

Web 플랫폼 runbook

HTTP 경계가 이상할 때 운영자에게 필요한 것이다. 어느 모듈이 가졌는지가 아니라 무엇을 보았는지로 나눴다. 새벽 3시에 손에 있는 것이 그것이기 때문이다.

429 읽기

RateLimitInterceptor는 edge 속도 제한이 호출자를 거부하면 Retry-After와 함께 429 RATE_LIMIT_EXCEEDED로 답한다. RATE_LIMIT_UNAVAILABLE은 호출자가 무언가를 넘었다는 뜻이 아니라 속도 제한 저장소에 닿지 못했다는 뜻이다. 호출자가 아니라 저장소를 본다.

Envelope가 아닌 오류

애플리케이션이 쓰는 모든 HTTP 오류는 GlobalExceptionHandler가 쓰는 Envelope이고 (spring.mvc.problemdetails.enabled=false), client가 분기하는 error.code를 가진다.

  • 빨리 확인하는 법: 검증에 실패해야 하는 요청을 보내고 본문에 error.code가 있는지 본다. 없으면(Spring의 ProblemDetail이나 container의 오류 쪽) handler가 설치되지 않았거나 응답이 edge에서 왔다.

응답이 잘리거나 문서 중간에 connection이 끊긴다

원인은 둘이고, client가 받은 상태로 구분한다.

  • client가 상태를 받고 그다음 아무것도 없다 — 응답이 commit 뒤에 실패했다. 상태는 되돌릴 수 없으므로 문서 중간에 connection이 끝난다.
  • client가 애플리케이션에서 아무것도 받지 못했다 — proxy가 거부했다. nginx의 client_max_body_size는 Envelope가 아니라 자기 HTML로 답한다. repository-adaptation.md §8을 본다.

재시도한 쓰기가 두 번 일어났다

통제 수단은 멱등 key이고, 그것이 적용되지 않는 길은 정확히 셋이다.

  1. client가 key를 보내지 않았다. endpoint가 key를 요구하지 않으니 보호 없이 돌았다. 중복을 받아들일 수 없으면 key를 요구한다.
  2. client가 다른 본문을 보냈다. 422 IDEMPOTENT_REQUEST_MISMATCH로 답하고 절대 다시 보내지 않는다. 다시 보내면 호출자가 한 적 없는 요청의 영수증을 돌려주게 된다.
  3. 기록이 만료됐다. TTL은 전역 하나다: APP_IDEMPOTENCY_TTL(app.capabilities.idempotency.replay-ttl, 기본 24h, 상한 72h). 연산마다 정하는 손잡이는 없다. 이 값은 실패 기록 보존 APP_IDEMPOTENCY_FAILURE_RETENTION(기본 24h)보다 길 수 없다. TTL만 48h로 올리면 기동이 실패하니 둘을 같이 올린다(IdempotencySettings). 만료 뒤의 재시도는 정의상 새 요청이다.

409 IDEMPOTENT_IN_FLIGHT(retryable=true, Retry-After: 2)는 실패가 아니다. 앞 시도가 아직 돌고 있고 그 결과를 모른다. 호출자는 Retry-After 뒤에 같은 Idempotency-Key로 다시 보낸다. 새 key는 새 요청이고, 쓰기가 두 번 적용되는 길이 그것이다. 멱등성 답 넷은 http-contract.md §2에 있다.

rolling 배포가 인스턴스를 반쯤 비운 채 멈춘다

graceful shutdown(server.shutdown=graceful)은 진행 중인 요청이 끝나기를 기다린다. 끝나지 않는 요청이 있으면 그 기다림이 길어진다.

  • 증상: 종료 중인 인스턴스가 새 요청을 받지 않은 채 오래 남는다. 종료 예산보다 유예가 짧으면 멈추는 대신 SIGKILL로 끝나고, 진행 중이던 요청·async 작업이 끊긴다. 로그에 오류가 없다.
  • 원인: 종료 단계는 차례로 더해진다. 웹 drain(spring.lifecycle.timeout-per-shutdown-phase, APP_SERVER_SHUTDOWN_TIMEOUT, 기본 30s)이 끝난 뒤 async executor가 남은 작업을 19s 기다린다 (AsyncExecutorConfig.AWAIT_TERMINATION_SECONDS). 합계 49s에 preStop(5s)과 여유를 더한 값보다 배포의 종료 유예 (Kubernetes terminationGracePeriodSeconds 등, 기본 30s)가 짧으면 async 대기 중에 죽는다. compose는 60s다 (compose.yaml stop_grace_period). 같은 예산을 docs/runbooks/job-timeout.md 「Escalation」이 적는다.
  • GracefulShutdownProbe는 시험 도구다(web testFixtures, 성능 lane이 쓴다). 운영 코드에는 없다.

metric이 오지 않거나 청구액이 뛰었다

거의 늘 가짓수가 많은 tag다. 흔히 풀린 경로를 담은 경로 tag이고, 자원마다 시계열 하나가 된다. 이 템플릿의 http.server.requests는 Spring Framework 기본 convention(DefaultServerRequestObservationConvention)의 tag uri를 쓴다(docs/registries/metrics.yaml). 맞는 route가 있으면 template(/v1/orders/{id})이고, 없으면 그 convention이 정한 상수(NOT_FOUND, REDIRECTION, UNKNOWN, root)다.

  • 확인: metric 저장소에서 uri의 tag 값을 본다. 중괄호가 있으면 template이고, 식별자가 있으면 풀린 경로가 새어 나갔다(서비스가 자기 convention으로 tag를 바꿨을 때 생긴다).
  • 절대 tag로 쓰지 않는 것: URL, query string, 식별자, tenant, key, token, cookie, 본문. tag 값은 가려지지 않은 채 metric 저장소에 닿고, 보통 그와 함께 외부 SaaS에도 닿는다.

브라우저에서만 cross-origin 요청이 실패한다

API는 맞게 답하는데 브라우저가 응답을 거부한다. CORS는 SecurityConfig가 적용하는 CorsSettings(app.cors.*)다. 시작 단계는 아래 설정을 거부한다.

  • origin 없이 APP_SECURITY_CORS_ENABLED=true.
  • APP_SECURITY_CORS_ALLOW_CREDENTIALS=true와 함께 APP_SECURITY_CORS_ORIGINS의 * — 어떤 브라우저도 받아들이지 않는다.
  • origin 목록의 https://*.example.com 같은 wildcard origin과 경로가 있는 origin(https://app.example.com/ui) — origin은 scheme, host, port뿐이다(CorsSettings).

응답은 오는데 브라우저 코드에서 헤더가 null로 읽힌다(Retry-After, X-Request-Id, Location, tus Upload-Offset): 그 헤더가 Access-Control-Expose-Headers에 없다. 노출 목록은 CorsExposedHeaders.PLATFORM과 모듈마다의 CorsExposedHeaders bean이다(docs/web/http-contract.md §3). 서비스가 더한 헤더에는 자기 bean이 필요하다. Access-Control-Expose-Headers를 지우거나 고쳐 쓰는 proxy도 같은 증상을 낸다.

preflight가 401로 답하면 CORS가 인증 뒤에 돈 것이다. preflight는 설계상 credential을 싣지 않는다. 순서는 WebPipelineOrderContract가 단언한다.

요청 하나에 접근 로그 줄이 둘

async 요청은 servlet filter chain을 두 번 지난다. 처음 요청 때 한 번, ASYNC 재전달 때 또 한 번이다. isAsyncStarted()를 확인하지 않고 기록한 완료는 두 번 쓰이고, 그 데이터로 계산한 모든 지연 백분위수는 그럴듯해 보이면서 틀린다. WebPipelineOrderContract가 모든 container에서 논리 요청마다 관측이 정확히 하나임을 단언한다.

확인 명령

./gradlew :adapter:inbound:web:test                          # 단위, 경계, 아키텍처
./gradlew :adapter:inbound:web:systemTest                    # Tomcat, 실제 socket
./gradlew :adapter:inbound:web:webJettyCompatTest            # 두 번째 servlet container