toki
4dbeecf2fb
- Add gateway real path implementation (06_gateway_real_path) - Add gateway cleanup tasks (07+06_gateway_cleanup) - Update Go WebSocket client and benchmark - Update Kotlin Communicator, TcpClient, WsClient and stress tests - Update TypeScript base_client, communicator, inbound_gateway, node variants, tcp/ws clients and tests - Update Kotlin and TypeScript stress benchmarks - Update roadmap milestone documentation
122 lines
13 KiB
Markdown
122 lines
13 KiB
Markdown
# 고성능 병렬 운용 기준선과 최적화
|
|
|
|
## 목표
|
|
|
|
`수신 큐와 처리 순서 보장` Milestone에서 확보한 FIFO, nonce matching, close cleanup 안정성을 바탕으로 Dart, Go, Kotlin, Python, TypeScript 구현이 실제 고성능 병렬 운용에서 어느 정도까지 안전하고 빠르게 동작하는지 측정하고 최적화한다. 단순 PASS/FAIL 안정성 검증을 넘어, 언어별 TCP/WS 경로, payload 크기, connection 수, sustained load, gateway on/off 조건에서 병목을 식별하고 기본 정책을 정한다.
|
|
|
|
이 Milestone의 결과는 package registry 릴리즈나 외부 CI/CD 연결이 아니라, Git ref/tag 기반 소비자가 참고할 수 있는 로컬 성능 기준선과 최적화 근거다.
|
|
|
|
## 단계
|
|
|
|
안정화와 유지
|
|
|
|
## 상태
|
|
|
|
[진행중]
|
|
|
|
## 구현 잠금
|
|
|
|
- 상태: 해제
|
|
- 결정 필요: 없음
|
|
|
|
## 범위
|
|
|
|
- Dart, Go, Kotlin, Python, TypeScript의 same-language TCP/WS 성능 기준선을 모두 확보한다.
|
|
- 지원 가능한 크로스 언어 request-response 경로에서 병렬 운용 안정성과 주요 성능 지표를 측정한다.
|
|
- concurrency, client connection 수, payload size, burst size, sustained duration을 축으로 하는 stress/benchmark matrix를 만든다.
|
|
- gateway on/off가 실제 transport 수신 경로에서 이득인지 언어별로 판단하고, 이득이 불명확하거나 손해인 경우 안전한 fallback/default-off 정책을 명확히 한다.
|
|
- queue depth, pending request 수, gateway backlog, memory peak/growth, close cleanup을 직접 계측한다.
|
|
- 병목이 확인된 언어/경로는 queue/channel/lock/worker/serialization 비용을 우선순위에 따라 최적화한다.
|
|
- 결과는 local baseline으로 저장하고, 안정성 hard gate와 성능 regression gate를 분리한다.
|
|
|
|
## 기능
|
|
|
|
### Epic: [bench-matrix] 언어별 benchmark matrix
|
|
|
|
모든 지원 언어가 같은 축의 benchmark/stress 결과를 남기도록 진입점과 결과 schema를 정렬한다.
|
|
|
|
- [x] [bench-schema] stress/benchmark 결과 schema를 공통화한다. 검증: 결과 파일이 언어, transport, payload size, concurrency, client count, throughput, p50/p95/p99 latency, timeout, nonce mismatch, type mismatch, FIFO violation, pending leak, queue/gateway backlog, peak memory를 기록한다.
|
|
- [x] [lang-baseline] Dart, Go, Kotlin, Python, TypeScript same-language TCP/WS full baseline을 추가한다. 검증: 각 언어별 full run이 결과 파일을 남기고 stability hard gate를 통과한다.
|
|
- [x] [cross-baseline] 지원 가능한 크로스 언어 request-response 병렬 baseline을 추가한다. 검증: 서버 가능한 5개 구현과 클라이언트 가능한 구현 조합에서 concurrency 1/16/64/256 기준의 nonce/FIFO 독립성이 유지된다.
|
|
- [x] [payload-matrix] payload size matrix를 추가한다. 검증: 1KB, 64KB, 1MB payload에서 latency, throughput, memory peak, gateway backlog가 기록된다.
|
|
|
|
### Epic: [load-profile] 운영형 부하 기준선
|
|
|
|
짧은 smoke가 아니라 병렬 운용에서 재현 가능한 부하 프로파일을 만든다.
|
|
|
|
- [x] [burst-100k] burst inbound 기준선을 10k에서 100k message/request까지 확장한다. 검증: 입력 순서, dispatch 순서, pending cleanup, queue drain 결과가 기록되고 hard gate 위반이 0이다.
|
|
- [x] [parallel-1k] 다중 connection 기준선을 16 clients에서 128/512/1024 clients 후보까지 확장한다. 검증: connection별 FIFO와 nonce matching이 독립적으로 유지되고, 한 connection의 지연/포화가 다른 connection의 pending map을 오염시키지 않는다.
|
|
- [x] [soak-load] sustained load를 30초에서 5분 smoke, 30분 full 후보로 확장한다. 검증: p95/p99 latency trend, throughput trend, memory growth, queue/pending/gateway backlog trend가 결과 파일에 기록된다.
|
|
- [x] [slow-mix] 빠른 handler와 느린 handler가 섞인 혼합 부하를 추가한다. 검증: 느린 handler가 같은 connection FIFO를 계약대로 지연시키되 다른 connection의 nonce/FIFO 상태를 오염시키지 않는다.
|
|
|
|
### Epic: [gateway-policy] gateway 성능 정책
|
|
|
|
worker gateway가 실제 성능 이득을 주는 조건과 fallback 조건을 수치로 정한다.
|
|
|
|
- [ ] [gateway-real-path] TCP/WS 실제 수신 경로에서 gateway on/off baseline을 추가한다. 검증: in-process `onReceivedFrame`뿐 아니라 실제 transport frame ingest에서 gateway 사용 여부별 throughput, p95/p99, memory, backlog가 기록된다.
|
|
- [x] [gateway-threshold] gateway 기본 정책 기준을 선언한다. 검증: payload/traffic 조건별로 default on, default off, adaptive candidate 중 하나가 문서화되고, 이득이 불명확하면 fallback을 기본으로 둔다.
|
|
- [ ] [gateway-cleanup] gateway worker close/cancel/drain 계측을 추가한다. 검증: close 후 worker, queue, pending 상태가 비어 있고 repeated run에서 memory growth가 누적되지 않는다.
|
|
|
|
### Epic: [optimize] 병목 최적화
|
|
|
|
측정 결과를 근거로 병목을 줄이고 regression gate를 만든다.
|
|
|
|
- [ ] [hotspot-report] 언어별 병목 리포트를 작성한다. 검증: queue/channel/lock/serialization/worker/transport write path 중 주요 병목 후보와 근거가 결과 파일 또는 작업 문서에 남는다.
|
|
- [ ] [targeted-opt] 측정으로 확인된 상위 병목을 우선 최적화한다. 검증: 최적화 전후 같은 local profile에서 stability hard gate를 유지하고, 대상 metric이 개선되거나 fallback 정책이 명확해진다.
|
|
- [ ] [regression-gate] 성능 regression gate를 추가한다. 검증: 같은 환경의 이전 baseline 대비 throughput 20% 이상 하락 또는 p99 latency 25% 이상 악화가 발생하면 WARN/FAIL 후보로 표시하되, 환경 차이는 별도 baseline으로 분리할 수 있다.
|
|
- [x] [matrix] 전체 로컬 검증 매트릭스를 실행해 최적화 후에도 프로토콜 호환성과 크로스 언어 통신이 유지되는지 확인한다. 검증: `bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh --all` 통과.
|
|
|
|
## 성능 기준선
|
|
|
|
- 안정성 hard gate: timeout 0, nonce mismatch 0, response type mismatch 0, connection별 FIFO violation 0, close 후 pending/queue/gateway backlog leak 0.
|
|
- local full baseline 최소 축: concurrency 1/16/64/256, burst 10k/100k, sustained 5분 smoke와 30분 full 후보, parallel clients 16/128/512/1024 후보, payload 1KB/64KB/1MB.
|
|
- 초기 성능 기대선: same-language TCP 기준 concurrency 256에서 p99 100ms 이하, sustained 5분 smoke에서 unexpected timeout 0, memory growth가 안정 구간 진입 후 선형 증가하지 않을 것.
|
|
- regression gate: 같은 환경과 같은 profile에서 throughput 20% 이상 하락 또는 p99 latency 25% 이상 악화를 WARN/FAIL 후보로 본다.
|
|
- gateway 정책 기준: gateway on이 같은 payload/profile에서 p95/p99 또는 throughput을 유의미하게 개선하지 못하거나 memory/backlog 비용이 크면 default off 또는 adaptive fallback을 기본으로 둔다.
|
|
- 절대 throughput 수치는 hardware/runtime 의존 baseline으로 저장하고, release gate보다 regression 분석과 병목 우선순위 선정에 사용한다.
|
|
|
|
## gateway 정책
|
|
|
|
- 기본값: default off. 현재 안정적으로 검증된 gateway는 TypeScript `Communicator.onReceivedFrame` opt-in frame-ingest 경로이며, 일반 TCP/WS transport read loop는 inline decode 경로를 기본으로 유지한다.
|
|
- default on 후보: 실제 TCP/WS 수신 경로에서 같은 payload/profile 기준 p95/p99 latency 또는 throughput이 반복 측정에서 유의미하게 개선되고, memory peak와 gateway backlog 비용이 안정성 hard gate를 해치지 않는 경우에만 후보로 둔다.
|
|
- adaptive 후보: payload가 크거나 frame ingest가 CPU-bound로 확인되는 조건에서만 별도 후보로 둔다. 해당 조건도 `gateway-real-path` 결과가 있어야 선언한다.
|
|
- fallback: 개선 폭이 불명확하거나 memory/backlog 비용이 크거나 close/cancel/drain 계측이 불충분하면 inline decode fallback을 기본으로 유지한다.
|
|
|
|
## 완료 리뷰
|
|
|
|
- 상태: 없음
|
|
- 요청일: 없음
|
|
- 완료 근거: 없음
|
|
- 리뷰 필요:
|
|
- [ ] 사용자가 완료 결과를 확인했다
|
|
- [ ] archive 이동을 승인했다
|
|
- 리뷰 코멘트: 없음
|
|
|
|
## 범위 제외
|
|
|
|
- wire format, proto schema, nonce 의미를 변경하지 않는다.
|
|
- package registry 릴리즈, 외부 CI/CD runner 연결을 시작하지 않는다.
|
|
- C# 또는 Swift 포팅을 시작하지 않는다.
|
|
- 애플리케이션 레벨 priority queue, routing key, room/session semantics를 추가하지 않는다.
|
|
- 절대 성능 수치를 모든 환경의 고정 합격선으로 선언하지 않는다.
|
|
|
|
## 작업 컨텍스트
|
|
|
|
- 관련 경로: `agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh`, `agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_stress.sh`, `typescript/bench/stress.ts`, `dart/`, `go/`, `kotlin/`, `python/`, `typescript/`
|
|
- 선행 작업: 수신 큐와 처리 순서 보장
|
|
- 후속 작업: 릴리즈 준비 또는 사용처별 성능 요구가 생길 때 package/runtime 정책 정리
|
|
- 현재 근거: `agent-test/runs/20260602-095911-proto-socket-stress-full.md`는 TypeScript same-language local baseline으로 roundtrip, burst, sustained, parallel, gateway profile에서 stability violations 0을 기록했다.
|
|
- 완료 근거:
|
|
- [bench-schema] `agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_stress.sh`와 `typescript/bench/stress.ts`의 stress result row/table schema가 language, transport, payload bytes, client count, queue backlog, gateway backlog 필드를 기록하도록 확장되었다. 검증: `cd typescript && npm run check`, `bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_stress.sh --quick --profile gateway` PASS, 결과 기록 `agent-test/runs/20260602-112945-proto-socket-stress-quick.md`.
|
|
- [cross-baseline] `run_stress.sh --profile cross`가 Dart/Go/Kotlin/Python/TypeScript 서버/클라이언트 방향에서 TCP/WS와 concurrency 1/16/64/256 조합을 별도 실행하도록 정리되었다. 검증: `agent-test/runs/20260602-194252-proto-socket-stress-quick-cross.md`, `agent-test/runs/20260602-200010-proto-socket-full-matrix.md`, 완료 로그 `agent-task/archive/2026/06/m-high-performance-parallel-operations/02+01_cross_baseline/complete.log`.
|
|
- [lang-baseline] Dart, Go, Kotlin, Python, TypeScript same-language TCP/WS full roundtrip/payload baseline이 required SKIP 없이 stability hard gate를 통과했다. 지연 사유였던 Kotlin TCP delayed-ACK/TCP_NODELAY 부재, Kotlin WS frame별 coroutine launch에 따른 FIFO 불안정, Go WS 기본 32KiB read limit, Kotlin server-side listener 설치 전 초기 frame 소비 race는 `TcpClient.tcpNoDelay`, Kotlin WS 단일 receive queue, Go WS `SetReadLimit(MaxPacketSize)`, Kotlin stress server setup barrier로 제거했다. 검증: `agent-test/runs/20260603-062724-proto-socket-stress-full.md` PASS.
|
|
- [payload-matrix] Dart, Go, Kotlin, Python, TypeScript stress harness가 quick 1KB/64KB와 full 1KB/64KB/1MB payload rows를 기록하고, Python WS 1MB 회귀를 통과하도록 정리되었다. 검증: `agent-test/runs/20260602-205755-proto-socket-stress-full.md`, `agent-test/runs/20260602-205849-proto-socket-full-matrix.md`, `cd python && python3 -m pytest -q`, `git diff --check`, 완료 로그 `agent-task/archive/2026/06/m-high-performance-parallel-operations/03+01_payload_matrix/complete.log`.
|
|
- [gateway-threshold] gateway 기본 정책은 default off로 선언했다. 실제 TCP/WS 수신 경로에서 p95/p99 또는 throughput 개선이 반복 측정되고 memory/backlog 비용이 안정적일 때만 default on/adaptive 후보로 승격하며, 이득이 불명확하거나 cleanup 계측이 부족하면 inline decode fallback을 유지한다.
|
|
- [burst-100k], [parallel-1k], [soak-load] Dart/Go/Kotlin/Python/TypeScript stress harness가 full load profile 축을 100k burst, 128/512/1024 clients, 30초/5분/30분 sustained 후보로 확장했다. 검증: `agent-test/runs/20260602-232000-proto-socket-stress-full.md`는 Dart/Go/Python TCP 축에서 hard gate 위반 0을 기록했고, TypeScript 512/1024 client 회귀는 `agent-test/runs/20260603-015953-proto-socket-stress-full.md`에서 0 violation PASS로 재확인되었다.
|
|
- [slow-mix] Dart, Go, Kotlin, Python, TypeScript stress harness에 빠른/느린 handler 혼합 부하 profile이 추가되었다. 검증: `agent-test/runs/20260603-035342-proto-socket-stress-quick.md`는 Dart/Python/TypeScript TCP slow-mix PASS와 Go deferred를 기록했고, `agent-test/runs/20260603-035352-proto-socket-stress-quick.md`는 Kotlin TCP/WS deferred를 병목 후보로 기록했다.
|
|
- [matrix] slow-mix 작업 후 전체 로컬 검증 매트릭스가 프로토콜 호환성과 크로스 언어 통신을 유지했다. 검증: `agent-test/runs/20260603-035403-proto-socket-full-matrix.md` PASS.
|
|
- 진행 근거:
|
|
- [gateway-real-path] 실제 transport 수신 경로 benchmark는 큰 작업으로 분리해 `agent-task/m-high-performance-parallel-operations/06_gateway_real_path/PLAN-cloud-G07.md`에 구현 계획과 review stub을 만들었다.
|
|
- [gateway-cleanup] gateway worker close/cancel/drain 계측은 `gateway-real-path` 완료 후 진행하는 큰 작업으로 분리해 `agent-task/m-high-performance-parallel-operations/07+06_gateway_cleanup/PLAN-cloud-G06.md`에 구현 계획과 review stub을 만들었다.
|
|
- 보강 필요: gateway 실제 transport 수신 경로 baseline, gateway cleanup 계측, Go/Kotlin slow-mix deferred 축, 언어별 병목 리포트와 regression gate가 남아 있다.
|
|
- 확인 필요: 없음
|