Files
clean-architecture-backend-…/docs/adr/ADR-WEB-ADV-002-virtual-threads-do-not-remove-admission.md
T
DongHyeonka 59dff0041c ci(docs): 문서 검사에 문체를 더하고 번역한 결정 기록의 머리 문구를 맞춘다
문체 규칙(「~한다」, 「~합니다」와 섞지 않음)은 docs/README.md에 있지만
지키는 검사가 없어서, 번역 뒤에도 runbook 열 개에 높임 문장이 남았다.
그리고 결정 기록 머리 블록의 둘째 줄은 「본문은 결정한 때의 원문이다」인데,
2026-11-07에 본문을 한국어로 옮긴 ADR에는 맞지 않는다.

- check-docs.py `style`: 살아 있는 문서의 문장 끝이 높임(습니다·합니다·
  입니다·됩니다·십시오·하세요·주세요)이면 실패. 코드 블록, 인라인 코드,
  따옴표·낫표 안 인용, 「이력」 인용 블록은 보지 않는다.
- runbook 열 개의 「이 runbook은 다음 alert에서 발동됩니다.」를 「다음 alert가
  울리면 쓴다.」로 고쳤다. 지금 걸리는 곳은 이것뿐이었다.
- 결정 기록 표시 줄을 「본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지
  않았다)」로 바꿨다: check-docs.py의 DECISION_LABEL, docs/README.md 설명,
  docs/adr의 머리 블록 33개(기록은 머리 블록만 고친다는 규칙 안).
- docs/README.md 「문서 검사」에 앞 커밋이 더한 `link`와 이번 `style`을 적고,
  링크 검사 설명을 바로잡았다. 「모듈 README」 절(design-docs
  docs-system.md 6.2절 다섯 칸)을 더했다.

버린 대안: 문체를 리뷰로만 보기(번역 묶음 네 개를 거쳐도 남았다).

위험: design-docs docs-system.md 4.1절과 프론트의 같은 문구는 이 repo
밖이라 고치지 않았다(총괄에게 알린다).

검증: python3 -m unittest discover -s scripts/tests(문체 시험 5 포함),
check-docs.py, check-work-docs.py 모두 rc=0. 이 커밋의 트리만 얹은 임시
worktree에서 돌렸다. 검사 조건을 끈 사본 둘에서 문체 시험이 각각 2건,
1건 실패했다.
2026-11-07 22:20:18 +09:00

5.0 KiB

결정 기록 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.

  • 상태: 채택
  • 작성일: 2026-08-25
  • 요약: 가상 스레드는 스케줄링을 바꿀 뿐 동시성 예산을 없애지 않는다는 결정이다.
  • 현재 정본: docs/web/virtual-thread-profile.md

ADR-WEB-ADV-002: virtual thread는 스케줄링을 바꾸지 동시성 예산을 바꾸지 않는다

  • 상태: 채택
  • 날짜: 2026-08-25
  • 범위: adapter:inbound:web — advanced.virtualthread, advanced.blockingbridge

배경

Advanced Task 2는 MVC용 virtual thread executor를 준다. Task 3은 WebFlux용 한계 있는 blocking bridge를 줬다. (그 WebFlux 어댑터는 2026-09-25에 지웠다 — 템플릿은 servlet만이다. advanced.blockingbridge는 라이브러리 코드로 남는다.)

platform thread MVC 배포에는 숨은 동시성 한계 — thread pool — 가 있고, 보통 그 한계가 데이터베이스 pool, outbound HTTP bulkhead, 모든 하류 서비스를 전체 도착 비율로부터 지켜 왔다. 아무도 그것을 admission 정책으로 적지 않았다. pool 크기의 부작용이었다.

virtual thread로 바꾸면 그 한계가 지워지는데, 그것에 기대던 것은 하나도 지워지지 않는다.

결정

virtual thread를 켜면 명시적 admission 한계가 필요하다. VirtualThreadProfile은 그것 없이는 만들어지기를 거절한다. 없으면 배포는 모든 도착을 받고, 그것을 모두 하류 예산 위에 줄 세우며, 거절됐으면 성공했을 일을 timeout으로 끝낸다. 예전에 정문에서 덜어 내던 부하를, 받아들이는 비용을 치른 뒤 뒷문에서 덜어 낸다.

한계는 스레드가 아니라 동시 유스케이스를 묶는다. VirtualThreadAdmissionGuard는 pool이 아니라 공정한 semaphore다. 스레드를 묶으면 기다림을 되돌려 놓고 virtual thread가 산 것을 버린다. virtual thread 만 개가 있어도 허가를 쥔 것은 백 개일 수 있다.

하류 예산은 profile에 싣고 바뀌지 않았다고 밝힌다. 요점은 그것이 늘지 않았다는 것이다. admissionFitsDownstreamBudgets()는 admission 한계가 그것을 넘으면 거절하지 않고 알린다 — 일이 모두 데이터베이스에 묶인 것이 아니면 배포가 pool보다 많이 받는 것이 정당할 수 있고, 그것은 사고가 아니라 선택이어야 한다.

blocking offload는 등록하고, 한계를 두고, timeout을 둔다. boundedElastic()은 어디서나 쓸 수 있고 실제로는 한계가 없어서, 그것을 부르는 controller는 애플리케이션 전체를 소리 없이 한계 없는 pool에 들여놓는다. BlockingBridgeProfile이 offload해도 되는 operation을 이름으로 대고, BlockingBridgeBudget이 동시성을 묶으며 제때 자리를 얻지 못한 호출자를 거절한다. 그렇지 않으면 느린 의존 대상의 호출자가 heap이 찰 때까지 쌓이고 빠른 의존 대상이 그 뒤에서 굶는다.

2026-09-25: advanced.blockingbridge를 지웠다. 그 WebFlux 어댑터는 WebFlux 쌍둥이와 함께 갔고(D4), 더는 없는 bridge의 예산은 아무것도 묶지 않았다.

pinning은 없다고 치지 않고 관찰한다. VirtualThreadProfile.requiredObservations()가 지켜봐야 할 것 — 무엇보다 jdk.VirtualThreadPinned — 을 적는다. blocking 호출을 가로질러 쥔 synchronized 블록은 carrier thread를 고정하고, carrier pool은 CPU 수로 묶여 있으며, 고정된 carrier가 충분히 많으면 thread dump로도 잘 드러나지 않는 교착이 된다.

결과

  • virtual thread 켜기는 두 부분짜리 변경이다: executor와 admission 한계. profile은 그것이 한 부분이 되게 두지 않는다.
  • 부하 아래에서 거절이 오르고, 그것이 맞다. 1밀리초 안에 거절된 요청이, 꽉 찬 pool 뒤에서 받아들여졌다가 30초 뒤 timeout된 같은 요청보다 client에게 낫다. 503이 오르는 것을 본 운영자는 그것을 한계가 동작하는 것으로 읽어야 한다.
  • VirtualThreadAdmissionGuard.peakActive()는 부하 시험이 한계가 적용됐음을 단언할 수 있게 하려고 있다. 처리량에서는 보이지 않는다. 그래서 처리량만 재는 부하 시험은 guard를 빼도 통과한다.

따져 본 대안

  • virtual thread를 켜고 하류 예산을 거기 맞춰 올린다. 버렸다: 예산은 web 계층이 받을 수 있는 양이 아니라 의존 대상이 감당할 수 있는 양에 맞춘 것이다.
  • 고정 크기 executor로 virtual thread 자체를 묶는다. 버렸다: 단계만 더 많은 platform thread pool이다.
  • controller가 boundedElastic()을 직접 부르게 둔다. 버렸다: 그런 호출 자리는 pool이 heap을 먹는 범인이 될 때까지 하나도 보이지 않는다.