lab/grpc_performance_comparison
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity

docs: 프로젝트 README 추가 (루트 + src/)

Browse Source 
두 README의 역할을 분리한다:

- README.md (루트): 프로젝트 1페이지 overview
  - 핵심 기여, 비교 대상, 워크로드 시나리오, KPI 요약
  - 네트워크 제어 단계 (Phase 1 tc · Phase 2 mininet)
  - 문서 안내 표 (CLAUDE.md / IMPLEMENTATION.md / BACKGROUND.md / SGS)
  - 구현 코드 실행은 src/README.md로 위임

- src/README.md: 구현 코드 가이드
  - Phase 0~6 진행 상태 체크리스트
  - 사전 요구사항 (Go 1.22+, UTF-8 터미널, tc)
  - 빌드/실행 (go run ./cmd/benchcli)
  - src/ 디렉터리 구조와 각 파일 역할
  - UI 사용법 (화면 흐름·키 바인딩·파라미터 범위)
  - mock 시뮬레이터 가정과 실측 전환 경로
  - 트러블슈팅 (한글·색상·폰트 등)

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Godopu
2026-05-07 01:32:31 +00:00
parent 3db48c3bae
commit 2e565db65b
2 changed files with 275 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+91
View File
@@ -0,0 +1,91 @@
# AIoT gRPC 고성능 통신 모듈
> AI Agent 및 AIoT 환경에서 고성능·경량 서비스 간 통신을 위한 **gRPC over HTTP/3 (QUIC) 통신 모듈**과 **엣지 게이트웨이** 설계·구현·성능 검증 연구 프로젝트.
## 핵심 기여
1. **HTTP/3 (QUIC) 전송 계층을 채택한 gRPC 통신 모듈**을 AIoT 환경에서 실증
2. 위 모듈을 활용해 AI Agent 통신과 IoT 프로토콜을 통합 처리하는 **엣지 게이트웨이 아키텍처** 제안
## 비교 대상 시스템
| ID | 전송 | 직렬화 | 비고 |
|----|------|--------|------|
| `rest-h2` | HTTP/2 (TCP+TLS) | JSON | 베이스라인 |
| `grpc-h2` | HTTP/2 (TCP+TLS) | Protobuf | 선행 연구 (SGS) 확인 |
| `grpc-h3` | HTTP/3 (QUIC+TLS1.3) | Protobuf | **본 연구 제안** |
## 워크로드 시나리오
| 이름 | 메시지 크기 | 횟수 | 의도 |
|------|-----------|------|------|
| **Small-Many** | 1 KB | 10,000회 / 디바이스 | AI Agent RPC 패턴 |
| **Large-Few** | 1 MB | 50회 / 디바이스 | IoT 이미지 전송 (해충 탐지 ROI) |
## 측정 지표 (KPI)
- Latency P50 / P95 / P99
- Throughput (RPS)
- 데이터 전송량 (Payload Size)
- 성공률 (패킷 손실 환경 내구성)
- 연결 수립 시간 (Connection Overhead)
- 0-RTT Resumption · HoL Blocking 내성 (Phase 2)
## 네트워크 제어 단계
| 단계 | 도구 | 범위 |
|-----|------|------|
| **Phase 1 (현재 계획)** | Linux `tc netem` | 단일 NIC 구간의 지연·손실·대역폭 제어 |
| **Phase 2 (예정)** | Mininet | SDN 스위치 기반 다중 홉 토폴로지, 다중 디바이스 동시 시뮬레이션 |
## 프로젝트 구조
```
.
├── README.md # (본 파일) 프로젝트 개요 — 연구 목적·비교 대상·KPI
├── CLAUDE.md # 연구 방향·동기·목표·평가 지표·코드 정책
├── IMPLEMENTATION.md # 디렉터리 구조·네이밍·워크플로우·코드 패턴
├── BACKGROUND.md # 연구 수행 배경 (AI Agent 시대의 통신 인프라 변화)
├── 참고/
│ └── SGS/ # 선행 연구 (스마트팜 해충 탐지, gRPC vs REST/HTTP-2)
└── src/ # 구현 코드 — 빌드/실행/UI 가이드는 src/README.md
└── README.md
```
## 구현 코드 실행
구현 디렉터리(`src/`)는 자체 README와 빌드 가이드를 제공한다.
→ **[`src/README.md`](src/README.md)** 에서 다음을 확인할 수 있다:
- 사전 요구사항 (Go 버전, 터미널 환경)
- Terminal UI 데모 빌드 및 실행 방법
- UI 화면 흐름·키 바인딩·조절 가능한 파라미터
- 디렉터리 구조 (`cmd/`, `internal/ui/`)
- mock 시뮬레이터의 가정과 실측 전환 경로
- Phase별 구현 진행 상태
## 진행 상태 (연구 단계)
- [x] 연구 방향 문서화 (`CLAUDE.md`, `BACKGROUND.md`)
- [x] 구현 가이드 분리 (`IMPLEMENTATION.md`)
- [x] 테스트베드 계획 수립
- [x] Phase 0 — Terminal UI 데모 (자세한 사항: `src/README.md`)
- [ ] Phase 1 — Proto + gRPC/REST 서버, tc 통합, 벤치마크 러너
- [ ] Phase 2 — gRPC over QUIC 전송 계층 + Mininet 환경
## 문서 안내
작업 종류에 따라 참조할 문서:
| 상황 | 우선 참조 |
|------|----------|
| 프로젝트 개요·연구 목적 | 본 README |
| 연구 방향·동기·평가 지표 | [`CLAUDE.md`](CLAUDE.md) |
| 디렉터리·네이밍·코드 패턴·작업 분담 | [`IMPLEMENTATION.md`](IMPLEMENTATION.md) |
| 연구 시작의 구조적 배경 (발표 자료 추출 가능) | [`BACKGROUND.md`](BACKGROUND.md) |
| 선행 연구 | [`참고/SGS/README.md`](참고/SGS/README.md) |
| **빌드·실행·UI 사용법** | [`src/README.md`](src/README.md) |
## 라이선스 / 안내
본 프로젝트는 연구 목적의 프로토타입입니다. 프로덕션 환경의 안정성·보안·가용성을 보장하지 않습니다.
src/README.md
+184
View File
@@ -0,0 +1,184 @@
# `src/` — 구현 코드
본 디렉터리는 **AIoT gRPC 고성능 통신 모듈** 프로젝트의 구현 코드 루트다.
프로젝트 전체 개요·연구 목적·비교 대상은 [상위 디렉터리의 `README.md`](../README.md)를, 연구 방향과 평가 지표는 [`../CLAUDE.md`](../CLAUDE.md)를 참고한다.
---
## 1. 현재 구현 단계
현재 빌드는 **Phase 0 — Terminal UI 데모**다. 실제 gRPC/REST 서버나 `tc` 연동 없이, 파라미터에 반응하는 시뮬레이션 값으로 최종 목표 화면을 가시화한다.
| Phase | 상태 | 내용 |
|------|------|------|
| **0. Demo UI** | ✅ 완료 | Bubble Tea 기반 TUI · mock 시뮬레이터 |
| 1. Proto + gRPC 서버/클라이언트 | ☐ | `proto/`, `cmd/server`, `cmd/client` |
| 2. REST 비교군 | ☐ | `cmd/rest-server`, `internal/client/rest_client.go` |
| 3. gRPC over QUIC 전송 계층 | ☐ | `internal/transport/quic_*.go` |
| 4. tc 스크립트 + 벤치마크 러너 | ☐ | `scripts/tc-*.sh`, `cmd/benchmark-runner` |
| 5. UI ↔ 실측 데이터 연결 | ☐ | `internal/ui/simulator.go` 교체 |
| 6. Mininet 토폴로지 | ☐ | Phase 2 평가 환경 |
---
## 2. 사전 요구사항
- **Go 1.22+** (현재 빌드는 1.26에서 검증됨)
- 256색 / UTF-8 지원 터미널
- (Linux, Phase 1+) `iproute2` 패키지의 `tc` 명령
```bash
go version # 1.22 이상 확인
```
---
## 3. 빌드 및 실행
### 3.1. Terminal UI 데모
```bash
# 본 src/ 디렉터리에서
go mod tidy # 최초 1회 의존성 다운로드
go run ./cmd/benchcli # 즉시 실행
# 또는 바이너리 빌드
go build -o ../bin/benchcli ./cmd/benchcli
../bin/benchcli
```
### 3.2. 검증
```bash
go vet ./... # 정적 분석
go build ./... # 전체 컴파일
go test ./... # (테스트 추가 후) 단위·통합 테스트
```
---
## 4. 디렉터리 구조 (src/)
```
src/
├── go.mod # 모듈명: aiot-grpc-bench, Go 1.22
├── go.sum
│
├── cmd/
│ └── benchcli/
│ └── main.go # Terminal UI 진입점
│
└── internal/
└── ui/ # Bubble Tea + Lipgloss 기반 TUI
├── app.go # Model + Update + View dispatcher
├── types.go # Config / Result / RunState 정의
├── styles.go # Lipgloss 색상·스타일
├── components.go # progressBar / sparkline / slider / formatBytes
├── simulator.go # ★ mock 시뮬레이터 (Phase 5에서 교체 예정)
├── screen_menu.go # 메인 메뉴
├── screen_config.go # 시나리오·네트워크·시스템 설정
├── screen_running.go # 실시간 진행 화면
├── screen_results.go # 비교 차트 화면
└── screen_about.go # 테스트베드 정보
```
향후 Phase 1 이후 추가될 디렉터리는 [`../IMPLEMENTATION.md`](../IMPLEMENTATION.md) 1절(프로젝트 구조)을 따른다(`proto/`, `gen/`, `internal/transport/`, `internal/server/`, `internal/gateway/` 등).
---
## 5. UI 사용법
### 5.1. 화면 흐름
```
[메인 메뉴]
│
├─ 새 실험 시작 ─→ [Config] ─→ [Running] ─→ [Results]
│ │
│ └─ r: 같은 조건 재실행
│ └─ n: 새 실험
│
└─ 테스트베드 정보 ─→ [About]
```
### 5.2. 키 바인딩
| 키 | 동작 |
|----|------|
| `↑/↓` `j/k` | 항목 이동 |
| `←/→` `h/l` | 파라미터 값 조정 |
| `Space` | 비교 시스템 선택 토글 |
| `Enter` | 선택 / 실험 시작 |
| `r` | (결과 화면) 같은 조건으로 재실행 |
| `n` | (결과 화면) 새 실험 시작 |
| `Esc` | 한 단계 뒤로 / 진행 중단 |
| `q` `Ctrl+C` | 종료 |
### 5.3. 조절 가능한 파라미터
| 파라미터 | 범위 | 단위/단계 |
|---------|-----|----------|
| 시나리오 | Small-Many / Large-Few | 토글 |
| 링크 지연 (편도) | 0 – 500 | ms (10ms 단위) |
| 패킷 손실율 | 0.0 – 5.0 | % (0.5% 단위) |
| 대역폭 | 1, 5, 10, 25, 50, 100, 250, 500, 1000 | Mbps (이산) |
| 디바이스 수 | 1 – 100 | 1/5/10 단위 (값 크기에 따라) |
| 비교 시스템 | rest-h2 / grpc-h2 / grpc-h3 | 개별 토글 |
---
## 6. 의존성
```
github.com/charmbracelet/bubbletea v1.2.4 # TUI 프레임워크
github.com/charmbracelet/lipgloss v1.0.0 # 스타일링
```
간접 의존성은 `go.mod`의 `// indirect` 블록 참고.
---
## 7. mock 시뮬레이터의 가정
`internal/ui/simulator.go`는 실제 측정 없이 파라미터에 반응하여 그럴듯한 추세를 만든다. 시뮬레이션이 가정한 추세는 다음과 같다.
| 가정 | 코드 위치 |
|------|----------|
| HTTP/3 (QUIC)은 패킷 손실 환경에서 HoL Blocking 해소로 처리량/latency 안정성 우위 | `simSpeed`, `mockLatency` |
| gRPC (Protobuf)는 REST (JSON) 대비 페이로드 ~30% 절감 | `step` 함수의 bytes 계산 |
| QUIC 연결 수립은 0/1-RTT (≈0.5×RTT), TCP+TLS는 ≈1.5×RTT | `mockConnectionTime` |
| Large-Few 시나리오는 대역폭 영향 지배적 | `mockLatency`의 bandwidth 항 |
| 디바이스 수 증가 시 병렬성으로 처리량 비례 증가 | `simSpeed`의 `parFactor` |
> ⚠ **이 수치는 모두 시뮬레이션이다.** 실제 gRPC/QUIC 구현이 같은 추세를 보일지는 Phase 1 이후의 실측으로 검증한다. 시뮬레이터 가중치는 발표·논의를 위한 예시이며, 실측을 대신하지 않는다.
---
## 8. 다음 단계
### 8.1. UI 측면
- 결과 export (JSON / CSV) 기능 추가
- 시나리오 저장/불러오기 (프리셋)
- 비교 결과를 동시에 여러 개 누적 보기 (네트워크 조건 매트릭스 sweep)
### 8.2. 백엔드 연결 (Phase 1+)
1. `proto/aiot/inference/inference.proto` 정의 및 `make proto`로 코드 생성
2. `cmd/server`에 gRPC InferenceService 구현 (HTTP/2)
3. `cmd/rest-server`에 동일 시나리오의 REST 엔드포인트 구현
4. `cmd/benchmark-runner`에서 두 서버 호출하는 부하 생성기 구현
5. `internal/ui/simulator.go`의 `step()` 함수를 실측 데이터 수집기로 교체
6. `scripts/tc-setup.sh`를 UI에서 자동 호출하도록 통합
자세한 구현 패턴은 [`../IMPLEMENTATION.md`](../IMPLEMENTATION.md) 4절(코드 패턴)과 7절(자주 수행하는 작업 시나리오)을 참고한다.
---
## 9. 트러블슈팅
| 증상 | 원인 / 해결 |
|------|-----------|
| 한글이 깨져 보임 | 터미널 로케일을 UTF-8로 설정 (`export LANG=ko_KR.UTF-8`) |
| 색상이 단조로움 | `TERM` 환경변수가 256색을 지원하는지 확인 (`echo $TERM` → `xterm-256color` 등) |
| `go: module ... not found` | `cd src && go mod tidy` 재실행 |
| sparkline/막대가 깨짐 | 터미널 폰트가 Block Element(`▓░█▁▂▃▄▅▆▇`)를 지원하는지 확인 (Nerd Font 권장) |
| 화면이 잘림 | 최소 터미널 크기 약 100×40 권장 |