proto-socket/agent-roadmap/milestones/high-performance-parallel-operations.md

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

목표

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

• [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 성능 정책

worker gateway가 실제 성능 이득을 주는 조건과 fallback 조건을 수치로 정한다.

• [gateway-real-path] TCP/WS 실제 수신 경로에서 gateway on/off baseline을 추가한다. 검증: in-process onReceivedFrame뿐 아니라 실제 transport frame ingest에서 gateway 사용 여부별 throughput, p95/p99, memory, backlog가 기록된다.
• [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으로 분리할 수 있다.
• [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 분석과 병목 우선순위 선정에 사용한다.

완료 리뷰

• 상태: 없음
• 요청일: 없음
• 완료 근거: 없음
• 리뷰 필요:
  • 사용자가 완료 결과를 확인했다
  • 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.
• 보강 필요: 현재 stress baseline은 TypeScript 중심이고 gateway profile은 실제 TCP/WS transport 수신 경로가 아니라 onReceivedFrame opt-in 경로 중심이다. 고성능 병렬 운용 근거로 쓰려면 언어별/transport별 full baseline과 장시간/대규모 connection 계측이 필요하다.
• 확인 필요: 없음