--- title: Runbook — 서버 포화(SERVER_BUSY) category: TRANSIENT_DEPENDENCY error_codes: [SERVER_BUSY] severity: P2 owner: oncall last_updated: 2026-11-13 status: 운영 --- # 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을 요청한다.