Files
clean-architecture-backend-…/docs/web/virtual-thread-profile.md
DongHyeonka 9d6c67c14e docs(web): web 운영 문서를 한국어로 옮기고 코드와 맞춘다
문제: docs/web 아래 살아 있는 문서 7개가 영어였다(language 예외). http-contract.md는
짝 프론트 repo의 문서를 이 repo 경로처럼 인라인 코드로 적었다(reference 예외).
repository-adaptation.md는 번역하며 보니 지금 코드와 여러 곳이 달랐다.
- 1절 표: 설계 모듈 대부분을 「planned」로 적었지만 `core`·`mvc`는 web leaf에,
  `contract`·`versioning`·`admin`·`openapi`·`idempotency`는 web-advanced leaf에 이미 있다.
  `fileserver.*`·`notification.*`는 web leaf가 아니라 web-fileserver·web-notification leaf다.
- Advanced 절: Advanced가 「이 leaf」의 package이고 `WebArchitectureRules.stableDoesNotDependOnAdvanced()`
  (`WEB-ARCH-ADV`)가 방향을 막는다고 했다. 그런 규칙은 없고, Advanced는 따로 된 leaf
  `adapter:inbound:web-advanced`이며 registry가 web-advanced → web 방향만 허락한다.
- 4절: Spring Boot 기준을 4.0.8로 옮겨 적고 없는 `.vscode/settings.json`을 근거로 들었다.
- 6절: 다시 보내기 JSON 인코딩이 web leaf에 남는다고 했지만 web-advanced에 있다.
- 7절: web leaf가 의존할 수 있는 leaf에서 `adapter-outbound-support`가 빠졌다.

고친 방법: 뜻을 그대로 옮기고 식별자·명령·경로·설정 key·오류 코드·표 구조는 원문으로
둔다. 위 불일치는 registry와 트리에 맞춰 고쳤다. 다른 repo 문서는 경로 대신 repo 이름과
문서 이름을 문장으로 쓴다. 버전은 src/gradle/libs.versions.toml을 가리킨다.

버린 대안: 1절 표를 지우고 registry만 가리키기. 설계와 트리를 대조하는 사람에게 필요한
대응이 사라진다.

위험·한계: 내용 감사는 하지 않았다. 번역하며 본 불일치만 고쳤다.

검증: python3 scripts/check-docs.py에서 이 폴더 예외 줄 0. docs/web을 읽는 테스트는
주석뿐이다(`grep -rn 'docs/web' src --include=*.java`: EnvelopeWireShapeTest 등 주석).
2026-11-07 17:29:57 +09:00

4.2 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 만 개가 있어도 백 개만 허가를 쥐고 나머지는 문 앞에서 거부된다.

거부는 Retry-After가 붙은 503이고, 상한이 만들려는 결과가 바로 그것이다. 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다. 그래서 되돌리기 시험이 가장 중요하다.