Files
clean-architecture-backend-…/docs/runbooks/server-busy.md
T
DongHyeonka 697e62e8cb fix(errors)!: 서버 포화는 모든 전송이 공용 SERVER_BUSY 하나로 답한다
문제: 서버 쪽 상한이 찬 거절이 전송마다 다른 코드였다. web-advanced는
ADMISSION_REFUSED(503), fileserver는 instance·전송 pool 포화까지
TRANSFER_ADMISSION_REJECTED(429 RATE_LIMIT), gRPC는 RATE_LIMIT_EXCEEDED
(RESOURCE_EXHAUSTED, "요청이 너무 잦습니다")였다. client는 자기 빈도 탓인지 서버
포화인지 가를 수 없었다. web은 상태만 아는 모든 503을 REQUEST_TIMEOUT으로 답했다
(§4는 비동기 시간 초과만). §4에 OPERATION_NOT_FOUND가 없었고, fileserver 오류
code 27개 중 23개가 계약 문서에 없었으며 예시가 "data": null을 실었다. fileserver는
Retry-After를 발생만 보고 붙여, 본문이 retryable=false로 좁힌 code에도 헤더가
나갔다. gRPC Javadoc과 graphql 스냅숏 머리말이 지운 이름(WORKLOG_NOT_FOUND, spi)을
적었다.

고른 방법(리뷰 README 6절 ②):
- 공용 OperationalError.SERVER_BUSY(503, TRANSIENT_DEPENDENCY, retryable,
  Retry-After 1)를 더했다. registry 행, RetryAfterAdvisor, runbook
  server-busy.md를 같이 둔다.
- web-advanced admission 거절, gRPC call admission(UNAVAILABLE), fileserver의
  instance permit·직접 다운로드 permit·전송 pool 포화가 이 코드다. fileserver는
  같은 이름의 FileserverErrorCode.SERVER_BUSY를 두고, 이름이 같은 code의 뜻이
  같은지 FileserverExceptionTest가 이미 본다. 호출자 자기 scope의 동시 전송
  초과만 TRANSFER_ADMISSION_REJECTED 429로 남는다.
- 상태만 아는 503은 SERVER_BUSY, AsyncRequestTimeoutException만
  REQUEST_TIMEOUT이다(HttpStatusErrorCodes.forException).
- fileserver Retry-After는 본문과 같은 규칙(code와 발생이 모두 retryable)으로
  붙인다. 재시도 불가 code인 ATOMIC_PUBLISH_UNSUPPORTED를 표에서 뺐다.
- docs/fileserver/http-contract.md에 오류 code 표 전체를 두고 예시의 data:null을
  지웠다. http-contract §4에 OPERATION_NOT_FOUND와 SERVER_BUSY를 적었다.
- decisions 2.3에 결정 ①②③ 행을 더했다.
- 포화 시험의 sleep(200)을 첫 거절 신호로 바꾸고, timeout 시험이 code까지
  본다(같은 파일이라 RR9-03-20의 그 부분을 여기서 고친다).
- web-advanced 파일의 spotless 정리(앞 커밋분)를 함께 싣는다.
버린 대안: JOB_EXECUTOR_REJECTED를 재사용 — 백그라운드 job 이름이라 요청 허가
거절을 읽는 client와 runbook을 잘못 이끈다.

위험·한계: 포화 거절로 분기하던 client와 재시도 정책, WebAdvancedError
.ADMISSION_REFUSED를 참조하던 코드, 모든 503을 REQUEST_TIMEOUT으로 보던 client가
바뀐다(upgrade 안내 8·9·13).

BREAKING CHANGE: 서버 포화 코드가 SERVER_BUSY 하나다(web-advanced
ADMISSION_REFUSED 삭제, fileserver instance·pool 포화 429 → 503, gRPC
RESOURCE_EXHAUSTED → UNAVAILABLE). 상태만 아는 503은 SERVER_BUSY다. 할 일은
docs/upgrade/2026-11-round9-contracts.md.

Refs: RR9-03-06, RR9-03-07, RR9-03-11, RR9-03-12, RR9-03-15, RR9-03-16, RR9-03-20
2026-11-13 04:47:03 +09:00

2.5 KiB

title, category, error_codes, severity, owner, last_updated, status
title category error_codes severity owner last_updated status
Runbook — 서버 포화(SERVER_BUSY) TRANSIENT_DEPENDENCY
SERVER_BUSY
P2 oncall 2026-11-13 운영

Runbook: 서버 포화 (runbook://server/busy)

이 instance가 요청을 더 받을 자리가 없어 바로 거절했다. 호출자의 빈도 초과(RATE_LIMIT_EXCEEDED 429)와 다르다. 이 코드는 서버 쪽 상한이 찼다는 뜻이다.

증상

  • HTTP 503과 error.code = SERVER_BUSY, Retry-After: 1. gRPC는 UNAVAILABLE와 trailer error-code: SERVER_BUSY.
  • http_server_requests_seconds_count{status="503"}이 오르고, 같은 때 p95 지연은 오르지 않는다. 거절은 일을 하기 전에 나기 때문이다.
  • 이 코드를 내는 곳은 셋이다.
내는 곳 찬 상한 설정
web-advanced VirtualThreadAdmissionFilter 동시에 처리하는 요청 수 app.web.advanced.mvc-virtual-threads.admission-limit
fileserver 전송 허가 instance 전체 업로드·직접 다운로드 permit, 전송 worker pool app.fileserver-platform.quota.instance-upload-permits, …direct-download-permits
gRPC GrpcCallAdmission feature 호출 worker와 대기열 app.grpc.server.executor-max-pool-size, executor-queue-capacity

진단

  1. 거절이 한 instance에만 몰리는지 본다. 한 instance만이면 부하 분산이 고르지 않거나 그 instance의 하류가 느리다.
  2. 같은 때 하류 지연(DB pool 대기, 외부 HTTP 지연)을 본다. 하류가 느리면 허가를 쥔 요청이 오래 머물러 상한이 찬다. 이때 상한을 올리면 하류 pool 앞의 줄만 길어진다.
  3. 정상 부하에서 상한 자체가 작은지 본다. 거절률이 트래픽에 비례하고 하류가 건강하면 상한이 작다.

조치

  • 하류가 느린 경우: 하류 runbook(db-unavailable, dependency-timeout)을 먼저 따른다. 상한은 그대로 둔다.
  • 상한이 작은 경우: instance를 늘리거나 위 표의 설정을 올린다. virtual thread admission-limit은 DB pool과 외부 bulkhead를 넘지 않게 둔다(docs/web/virtual-thread-profile.md).
  • client는 Retry-After 뒤에 같은 요청을 다시 보낸다. 고칠 것이 없으면 거절은 1초 안에 풀린다.

에스컬레이션

  • 5분 넘게 거절률이 전체 요청의 5%를 넘으면 P1으로 올리고 인프라 당번을 부른다.
  • 모든 instance가 같이 거절하고 하류가 건강하면 용량 문제다. 배포 소유자에게 scale-out을 요청한다.