고성능 병렬 운용 기준선과 최적화

목표

수신 큐와 처리 순서 보장 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를 정렬한다.

[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를 기록한다.
[lang-baseline] Dart, Go, Kotlin, Python, TypeScript same-language TCP/WS full baseline을 추가한다. 검증: 각 언어별 full run이 결과 파일을 남기고 stability hard gate를 통과한다.
[cross-baseline] 지원 가능한 크로스 언어 request-response 병렬 baseline을 추가한다. 검증: 서버 가능한 5개 구현과 클라이언트 가능한 구현 조합에서 concurrency 1/16/64/256 기준의 nonce/FIFO 독립성이 유지된다.
[payload-matrix] payload size matrix를 추가한다. 검증: 1KB, 64KB, 1MB payload에서 latency, throughput, memory peak, gateway backlog가 기록된다.

Epic: [load-profile] 운영형 부하 기준선

짧은 smoke가 아니라 병렬 운용에서 재현 가능한 부하 프로파일을 만든다.

[burst-100k] burst inbound 기준선을 10k에서 100k message/request까지 확장한다. 검증: 입력 순서, dispatch 순서, pending cleanup, queue drain 결과가 기록되고 hard gate 위반이 0이다.
[parallel-1k] 다중 connection 기준선을 16 clients에서 128/512/1024 clients 후보까지 확장한다. 검증: connection별 FIFO와 nonce matching이 독립적으로 유지되고, 한 connection의 지연/포화가 다른 connection의 pending map을 오염시키지 않는다.
[soak-load] sustained load를 30초에서 5분 smoke, 30분 full 후보로 확장한다. 검증: p95/p99 latency trend, throughput trend, memory growth, queue/pending/gateway backlog trend가 결과 파일에 기록된다.
[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는 현재 측정 대상인 구현 세부사항이며, 제품 정책의 사용자/운영 옵션으로 두지 않는다.

[gateway-real-path] TCP/WS 실제 수신 경로에서 gateway baseline을 추가한다. 검증: in-process onReceivedFrame뿐 아니라 실제 transport frame ingest에서 gateway path throughput, p95/p99, memory, backlog가 기록된다.
[gateway-threshold] gateway 기본 정책 기준을 선언한다. 검증: mandatory gateway hard gate와 단일 receive path hardening 조건이 문서화된다.
[gateway-cleanup] gateway close/cancel/drain 계측을 추가한다. 검증: close 후 gateway queue, pending, worker-backed implementation 상태가 비어 있고 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이 개선되거나 남은 병목과 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로 이관됨)
[regression-gate] 성능 regression gate를 추가한다. 검증: 같은 환경의 이전 baseline 대비 throughput 20% 이상 하락 또는 p99 latency 25% 이상 악화가 발생하면 WARN/FAIL 후보로 표시하되, 환경 차이는 별도 baseline으로 분리할 수 있다.
[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은 성능 기준선과 측정 표준 완료 후보로 본다.
리뷰 필요:
- 사용자가 완료 후보 결과를 확인했다
- 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으로 넘긴다.
확인 필요: 없음

17 KiB Raw Blame History