- 결정 16: `ca-skeleton.*`·`backend.graphql` 등 → `app.*`(APP_* env 키 이름 유지), selector 키 상수 하나(`CapabilitySelectors`), 바인딩만 되던 `streaming-idle` 삭제 - `StrictSettingsBinder`가 env 오타까지 거부 — 모든 capability(graphql·websocket·mongo는 edge 제약으로 파일만 strict), httpclient 리플렉션 `HttpClientEnvironmentKeys` 삭제 - persistence-jpa가 `APP_DATASOURCE_PASSWORD` secret 요구를 기여(bootstrap이 JPA 스위치를 읽지 않음), Redis ACL fixture에서 pub/sub 권한 제거 - 결함 수정: SMTP 설정 env 이름 충돌(P20-new-1), `bindExcept`가 system env까지 filter(P20-new-2), graphql 빈 deployment-mode 메시지(P20-new-6) - 통합: P30과 충돌 11건(P30의 명시적 bean 구조 유지), P30 코드의 옛 키를 app.*로, persistence-jpa 포맷 - 현황표: 소유자 결정 36(persistence-jpa 설정은 플랫폼 키만 app.persistence-jpa.*로, 공유 기능 트리 예외), 재개 문서에 일시 정지 상태 Wave 3 종료 검증: check · ci verifyDependencyLocks --warning-mode=fail(714 task) · mainCheck · architectureCheck verifyPublicPathSnapshot :app-bootstrap:verifyEnvKeys configContractCheck · :app-bootstrap:integrationTest :sample-portfolio:integrationTest :sample-portfolio:systemTest · integrationCheck · -p build-logic test · -p optional-platforms ci · :app-bootstrap:qualificationBootJar releaseCheck 통과 Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
79 lines
3.8 KiB
Markdown
79 lines
3.8 KiB
Markdown
# The virtual-thread MVC profile
|
|
|
|
## What it changes, and what it does not
|
|
|
|
Virtual threads remove the cost of a thread waiting. They do not remove the reason the waiting was
|
|
bounded.
|
|
|
|
A platform-thread MVC deployment has an implicit concurrency limit — the thread pool. Nobody wrote
|
|
it down as an admission policy, but it is what has been protecting the database pool, the outbound
|
|
HTTP bulkhead and every downstream service from the full arrival rate.
|
|
|
|
Switching to virtual threads deletes that limit and deletes nothing that depended on it. The result
|
|
is not a slow system. It is a system that accepts ten thousand concurrent requests, queues all of
|
|
them on a twenty-connection pool, and times out every one — having done no useful work. The load
|
|
that used to be shed at the front door is shed at the back, after the cost of accepting it.
|
|
|
|
## Enabling it
|
|
|
|
The profile ships in `adapter:inbound:web-advanced`, which no default composition carries. Add
|
|
that leaf to the service, then two settings — the profile refuses to be constructed with only one:
|
|
|
|
```yaml
|
|
app:
|
|
web:
|
|
advanced:
|
|
mvc-virtual-threads:
|
|
enabled: true
|
|
admission-limit: 100 # required
|
|
database-pool-size: 20 # stated, and unchanged
|
|
outbound-bulkhead: 20 # stated, and unchanged
|
|
```
|
|
|
|
The downstream numbers are carried in the profile because the whole point is that they did not grow.
|
|
`VirtualThreadProfile.admissionFitsDownstreamBudgets()` reports when the admission limit exceeds
|
|
them. It does not refuse — a deployment can legitimately admit more than its pool when the work is
|
|
not all database-bound — but it makes the choice a choice.
|
|
|
|
## The limit bounds use cases, not threads
|
|
|
|
`VirtualThreadAdmissionGuard` is a fair semaphore, not a pool. Bounding the threads would put the
|
|
waiting back and throw away what virtual threads bought. Ten thousand virtual threads may exist
|
|
while a hundred hold permits and the rest are refused at the door.
|
|
|
|
A refusal is a **503 with `Retry-After`**, and it is the outcome the limit exists to produce. A
|
|
request refused in a millisecond is strictly better for the client than the same request accepted
|
|
and timed out thirty seconds later behind a full pool.
|
|
|
|
The semaphore is fair on purpose. An unfair one is faster and lets newer arrivals overtake waiting
|
|
ones, which the overtaken client experiences as a random timeout.
|
|
|
|
## What to watch
|
|
|
|
| Signal | Why |
|
|
| --- | --- |
|
|
| `jdk.VirtualThreadPinned` JFR events | A `synchronized` block held across a blocking call pins the carrier thread. The carrier pool is bounded by CPU count, so enough pinned carriers is a deadlock — and a thread dump does not obviously show it. |
|
|
| Carrier pool queue depth | The same problem, from the other side. |
|
|
| Admission rejections | They should rise under load. If they do not, the limit is not being applied. |
|
|
| Downstream wait time | The signal that admission is admitting more than the pools serve. |
|
|
|
|
`VirtualThreadProfile.requiredObservations()` is the same list, in code.
|
|
|
|
## Testing it
|
|
|
|
`VirtualThreadAdmissionGuard.peakActive()` exists so a load test can assert the limit was applied.
|
|
It is invisible from throughput — a load test that only measures throughput passes with the guard
|
|
removed, which is precisely the failure this profile guards against.
|
|
|
|
The test that matters asserts two things together: peak concurrency at or below the limit, **and**
|
|
more threads created than the limit. Without the second, the test would pass on a deployment that
|
|
never used virtual threads at all.
|
|
|
|
## Rolling back
|
|
|
|
Set `enabled: false`, or drop the leaf. The rollback test asserts that Stable behaviour is then
|
|
identical — if it is not, the feature was never optional and every deployment has it.
|
|
|
|
This is the only web Advanced capability that affects requests which do not use them, which is why
|
|
its rollback test is the one that matters most.
|