문제: 서버 쪽 상한이 찬 거절이 전송마다 다른 코드였다. 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
4.6 KiB
Virtual thread MVC profile
바꾸는 것과 바꾸지 않는 것
virtual thread는 스레드가 기다리는 비용을 없앤다. 기다림에 상한을 둔 이유는 없애지 않는다.
platform 스레드 MVC 배포에는 숨은 동시성 상한이 있다. 스레드 pool이다. 아무도 그것을 허가 정책으로 적지 않았지만, DB pool, 외부 HTTP bulkhead, 모든 하류 서비스를 전체 도착률로부터 지켜 온 것이 그것이다.
virtual thread로 바꾸면 그 상한이 사라지고, 그것에 기대던 것은 하나도 사라지지 않는다. 결과는 느린 시스템이 아니다. 동시 요청 만 개를 받아 connection 스무 개짜리 pool에 모두 줄 세우고, 쓸모 있는 일은 하나도 못 한 채 모두 시간 초과를 내는 시스템이다. 예전에 앞문에서 버리던 부하를 받는 비용을 치른 뒤 뒷문에서 버린다.
켜기
profile은 기본 조립에 없는 adapter:inbound:web-advanced에 있다. 서비스에 그 leaf를 더하고, 설정 둘을 준다. profile은
하나만 주면 만들어지기를 거부한다.
app:
web:
advanced:
mvc-virtual-threads:
enabled: true
admission-limit: 100 # 필수
database-pool-size: 20 # 밝혀 둔다. 바뀌지 않는다
outbound-bulkhead: 20 # 밝혀 둔다. 바뀌지 않는다
하류 숫자를 profile에 싣는 것은, 핵심이 바로 그 숫자가 늘지 않았다는 데 있기 때문이다.
VirtualThreadProfile.admissionFitsDownstreamBudgets()가 허가 상한이 그것을 넘으면 보고한다. 거부하지는 않는다. 일이
모두 DB에 묶이지 않았으면 배포가 pool보다 많이 허가하는 것도 정당하다. 다만 그 선택을 선택으로 만든다.
상한은 스레드가 아니라 use case를 제한한다
VirtualThreadAdmissionGuard는 pool이 아니라 공정한 semaphore다. 스레드를 제한하면 기다림을 되돌려 놓고 virtual
thread로 얻은 것을 버리게 된다. virtual thread 만 개가 있어도 백 개만 허가를 쥐고 나머지는 문 앞에서 거부된다.
상한은 VirtualThreadAdmissionFilter가 모든 요청에 건다. request-id filter 바로 뒤, 보안 chain보다 앞이라 거부된 요청은
아무 일도 하지 않는다. async 요청은 async 일이 끝날 때까지 허가를 쥔다. 넘겨준 순간 돌려주면 넘기는 일만 제한하고 정작
하류 pool을 쓰는 일은 제한하지 못한다.
거부는 Retry-After가 붙은 503(공용 코드 SERVER_BUSY)이고, 상한이 만들려는 결과가 바로 그것이다. 1밀리초 만에 거부된 요청이, 받아들여진 뒤
가득 찬 pool 뒤에서 30초 뒤에 시간 초과가 난 같은 요청보다 client에게 확실히 낫다.
semaphore는 일부러 공정하다. 불공정한 것이 빠르지만, 새로 온 요청이 기다리던 요청을 앞지르게 두고, 앞지름당한 client는 그것을 무작위 시간 초과로 겪는다.
볼 것
| 신호 | 이유 |
|---|---|
jdk.VirtualThreadPinned JFR event |
blocking 호출을 가로질러 쥔 synchronized 블록은 carrier 스레드를 고정한다. carrier pool은 CPU 수로 제한되므로 고정된 carrier가 충분하면 deadlock이다. thread dump로는 잘 보이지 않는다. |
| carrier pool 큐 깊이 | 같은 문제를 반대쪽에서 본 것이다. |
| 허가 거부 | 부하가 오르면 같이 올라야 한다. 오르지 않으면 상한이 적용되지 않고 있다. |
| 하류 대기 시간 | 허가가 pool이 받을 수 있는 것보다 많이 허가하고 있다는 신호다. |
VirtualThreadProfile.requiredObservations()가 코드로 된 같은 목록이다.
시험하기
VirtualThreadAdmissionGuard.peakActive()는 부하 시험이 상한이 적용됐음을 단언할 수 있게 하려고 있다. 처리량으로는 보이지
않는다. 처리량만 재는 부하 시험은 guard를 빼도 통과한다. 이 profile이 막으려는 실패가 바로 그것이다.
중요한 시험은 두 가지를 함께 단언한다. 최대 동시성이 상한 이하이고, 그리고 만든 스레드가 상한보다 많다. 둘째가 없으면 virtual thread를 아예 쓰지 않은 배포에서도 시험이 통과한다.
되돌리기
enabled: false로 두거나 leaf를 뺀다. 되돌리기 시험은 그때 Stable 동작이 같은지 단언한다. 같지 않으면 그 기능은 처음부터
선택 사항이 아니었고 모든 배포가 그것을 가지고 있다.
이것은 쓰지 않는 요청에도 영향을 주는 유일한 web Advanced capability다. 그래서 되돌리기 시험이 가장 중요하다.