130 lines
17 KiB
Markdown
130 lines
17 KiB
Markdown
# 고성능 병렬 운용 기준선과 최적화
|
|
|
|
## 목표
|
|
|
|
`수신 큐와 처리 순서 보장` Milestone에서 확보한 FIFO, nonce matching, close cleanup 안정성을 바탕으로 Dart, Go, Kotlin, Python, TypeScript 구현이 실제 고성능 병렬 운용에서 어느 정도까지 안전하고 빠르게 동작하는지 측정하고 최적화한다. 단순 PASS/FAIL 안정성 검증을 넘어, 언어별 TCP/WS 경로, payload 크기, connection 수, sustained load, gateway 처리 조건에서 병목을 식별하고 기본 정책을 정한다.
|
|
|
|
이 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가 실제 transport 수신 경로에서 제품 기본 신뢰 경로로 동작할 수 있게 순차 보장, event loop 보호, bounded backlog, close cleanup 조건을 명확히 한다.
|
|
- 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 신뢰 성능 정책
|
|
|
|
gateway receive coordinator를 제품 기본 수신 경로로 유지하기 위한 신뢰 hard gate와 성능 hardening 조건을 수치로 정한다. TypeScript의 `worker_threads` per-frame offload는 현재 측정 대상인 구현 세부사항이며, 제품 정책의 사용자/운영 옵션으로 두지 않는다.
|
|
|
|
- [x] [gateway-real-path] TCP/WS 실제 수신 경로에서 gateway baseline을 추가한다. 검증: in-process `onReceivedFrame`뿐 아니라 실제 transport frame ingest에서 gateway path throughput, p95/p99, memory, backlog가 기록된다.
|
|
- [x] [gateway-threshold] gateway 기본 정책 기준을 선언한다. 검증: mandatory gateway hard gate와 단일 receive path hardening 조건이 문서화된다.
|
|
- [x] [gateway-cleanup] gateway close/cancel/drain 계측을 추가한다. 검증: close 후 gateway queue, pending, worker-backed implementation 상태가 비어 있고 repeated run에서 memory growth가 누적되지 않는다.
|
|
|
|
### Epic: [optimize] 병목 최적화
|
|
|
|
측정 결과를 근거로 병목을 줄이고 regression gate를 만든다.
|
|
|
|
- [x] [hotspot-report] 언어별 병목 리포트를 작성한다. 검증: queue/channel/lock/serialization/worker/transport write path 중 주요 병목 후보와 근거가 결과 파일 또는 작업 문서에 남는다.
|
|
- [x] [targeted-opt] 측정으로 확인된 상위 병목을 우선 최적화한다. 검증: 최적화 전후 같은 local profile에서 stability hard gate를 유지하고, 대상 metric이 개선되거나 남은 병목과 hardening 계획이 명확해진다. (evidence: `agent-task/archive/2026/06/m-performance-hotspot-optimization/01_hotspot_report/complete.log`가 상위 병목과 hardening 계획을 확정했고, `agent-task/archive/2026/06/m-performance-hotspot-optimization/02+01_ts_gateway_perf_rows/complete.log`가 TypeScript gateway worker-hop 제거/overhead 정량화를 PASS로 남겼으며, 남은 Dart/Kotlin/Go/Python 후보는 `agent-roadmap/milestones/performance-hotspot-optimization.md`로 이관됨)
|
|
- [x] [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는 순차 보장과 event loop 보호를 담당하는 제품 기본 신뢰 경로다. 같은 payload/profile에서 p95/p99 또는 throughput 회귀, memory/backlog 비용이 크면 gateway를 끄는 정책이 아니라 gateway hardening 대상으로 분류한다.
|
|
- 절대 throughput 수치는 hardware/runtime 의존 baseline으로 저장하고, release gate보다 regression 분석과 병목 우선순위 선정에 사용한다.
|
|
|
|
## gateway 정책
|
|
|
|
- 운영 기본값: gateway는 순차 이벤트 보장과 event loop 보호를 담당하는 mandatory receive path로 정의한다.
|
|
- 단일 경로 원칙: gateway/worker on-off를 사용자 또는 운영 옵션으로 노출하지 않는다. TypeScript `worker_threads` per-frame offload가 성능 회귀를 만들면, 이를 끄는 정책이 아니라 단일 gateway 경로 내부의 제거/재설계 대상으로 분류한다.
|
|
- legacy inline control: inline decode 비교 row는 성능 분석용 대조군으로만 사용하고 운영 정책으로 문서화하지 않는다.
|
|
|
|
## 완료 리뷰
|
|
|
|
- 상태: 승인됨
|
|
- 요청일: 2026-06-06
|
|
- 승인일: 2026-06-06
|
|
- 완료 근거:
|
|
- benchmark/stress schema, same-language/cross-language/payload/load/gateway policy/regression/matrix Task가 archive complete log와 결과 record 근거로 완료됐다.
|
|
- [targeted-opt]는 직접 완료 이벤트가 없어 미반영 상태였으나, 상위 병목 리포트와 TypeScript gateway worker-hop 제거/overhead 정량화가 PASS로 완료됐고 남은 병목의 hardening 계획은 `언어별 성능 병목 개선` Milestone에 이관되어 검증 조건을 충족한다.
|
|
- 실제 최적화 구현의 나머지 범위는 `agent-roadmap/milestones/performance-hotspot-optimization.md`에서 진행하므로 이 Milestone은 성능 기준선과 측정 표준 완료 후보로 본다.
|
|
- 리뷰 필요:
|
|
- [x] 사용자가 완료 후보 결과를 확인했다
|
|
- [x] 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는 순차 이벤트 보장과 event loop 보호를 담당하는 mandatory receive path로 선언했다. 성능 회귀가 확인되면 gateway 비활성화 정책이 아니라 worker hop 제거/재설계, backpressure, reorder, cleanup hardening 대상으로 분류한다. inline decode 비교 row는 성능 분석용 대조군으로만 남긴다.
|
|
- [gateway-real-path] TypeScript gateway profile이 in-process frame-ingest row와 실제 TCP/WS transport read loop row를 함께 기록하도록 정리되었다. 검증: `agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_performance.sh`의 `typescript-gateway` component, `typescript/bench/stress.ts`의 `runGatewayTransportBaseline`, `agent-test/runs/20260603-080241-proto-socket-stress-full.md`의 `transport=tcp/ws` gateway on/off rows PASS.
|
|
- [gateway-cleanup] TypeScript gateway stats와 stress rows가 queued/reorder/sink/worker pending 기반 `GatewayBacklog`와 close 후 residual backlog를 기록하도록 정리되었다. 검증: `typescript/src/inbound_gateway.ts`, `typescript/src/node_inbound_gateway.ts`, `typescript/test/communicator.test.ts`의 WorkerGateway cleanup stats, `agent-test/runs/20260603-092819-proto-socket-performance-quick.md`의 `backlog`/`residual` 로그와 stability hard gate PASS.
|
|
- [hotspot-report] `언어별 성능 병목 개선` Milestone의 병목 리포트가 Dart TCP fixed latency/1MB payload/isolate gateway, TypeScript WS 1MB/gateway worker overhead, Kotlin WS latency/large payload/slow-mix, Go/Python reference 기준점을 근거 파일과 수치로 정리했다. 검증: `agent-roadmap/milestones/performance-hotspot-optimization.md`의 `작업 컨텍스트 > 병목 리포트`.
|
|
- [regression-gate] `run_performance.sh`가 baseline row 비교, throughput 하락, p99 악화, WARN/FAIL 후보, `--fail-on-regression`을 처리하도록 정리되었고 local 성능 테스트 규칙에도 같은 판정 기준이 기록되었다. 검증: `agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_performance.sh`, `agent-test/local/proto-socket-performance-baseline.md`, `agent-test/runs/20260603-095712-proto-socket-performance-quick.md`의 `compared rows: 90`, `warning rows: 0`.
|
|
- [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.
|
|
- 작업 동기화:
|
|
- 2026-06-03 기준 full matrix, 성능 전용 quick 표준, baseline 비교 경로, 5개 언어별 병목 분석이 완료되었다.
|
|
- 현재 활성 `agent-task/` 작업 디렉터리는 없다. gateway 실제 transport 경로와 cleanup 계측은 이 Milestone의 `gateway-policy` 에픽 완료 근거로 정리되었고, 성능 회귀를 줄이는 구현 작업은 새 `언어별 성능 병목 개선` Milestone의 작업 순서 안에서 다시 계획한다.
|
|
- 이 Milestone은 성능 기준선과 측정 표준의 선행 근거로 유지하고, 실제 최적화 구현은 `agent-roadmap/milestones/performance-hotspot-optimization.md`에서 진행한다.
|
|
- 후속 이관: Dart TCP 40ms대 고정 지연 및 1MB payload 병목 개선, Dart isolate receive gateway의 실제 transport 경로 적용/backpressure/error ordering/large payload transfer/cleanup hardening, Go slow-mix 검증 모델 보정, Kotlin WS 40ms대 고정 지연 개선, Kotlin slow-mix 검증 모델 보정, Kotlin large payload heap peak 관찰, Go/Python sustained memory 측정 artifact 분리, Python 고동시성 p99 기준점과 gateway API 정책 검토는 `언어별 성능 병목 개선` Milestone으로 넘긴다.
|
|
- 확인 필요: 없음
|