diff --git a/runtime-analysis/AGENT_RUNTIME_ANALYSIS.md b/runtime-analysis/AGENT_RUNTIME_ANALYSIS.md new file mode 100644 index 0000000..eb4f7bf --- /dev/null +++ b/runtime-analysis/AGENT_RUNTIME_ANALYSIS.md @@ -0,0 +1,186 @@ +# Agent Runtime Analysis + +## 1. MiniMax 연결 아키텍처 + +### 1.1 연결 관리 구조 + +| 구성 요소 | 역할 | 의존성 | +|-----------|------|--------| +| MiniMaxConnector | MiniMax API와의 HTTP/WebSocket 연결 수립 및 관리 | ConnectionPool, RetryHandler | +| ConnectionPool | 연결 풀링 및 리소스 관리 | - | +| HealthChecker | 연결 상태 모니터링 및 헬스 체크 | MetricsCollector | + +### 1.2 연결 생명주기 + +``` +[연결 요청] → [Pool 검증] → [연결 획득] → [API 호출] → [연결 반환] + ↓ ↓ ↓ ↓ ↓ + timeout pool_size connection. request. connection. + check check acquired duration released +``` + +### 1.3 연결 풀 파라미터 + +| 파라미터 | 기본값 | 설명 | +|----------|--------|------| +| pool_size | 10 | 최대 동시 연결 수 | +| connection_timeout | 30s | 연결 수립 타임아웃 | +| idle_timeout | 300s | 유휴 연결 유지 시간 | +| max_retries | 3 | 최대 재시도 횟수 | + +--- + +## 2. 출력 계약 (Output Contract) + +### 2.1 계약 검증 흐름 + +``` +[API 응답] → [ContractEmitter] → [스키마 검증] → [타입 체크] → [출력 반환] + ↓ ↓ ↓ + contract. contract. contract. + validation validation validation + (counter) (histogram) (gauge) +``` + +### 2.2 계약 검증 규칙 + +| 규칙 | 설명 | 메트릭 | +|------|------|--------| +| required_fields | 필수 필드 존재 여부 | contract.validation.required | +| type_check | 데이터 타입 일치 여부 | contract.validation.type | +| range_check |数值 범위 유효성 | contract.validation.range | +| format_check | 문자열 포맷 검증 | contract.validation.format | + +### 2.3 계약 상태 + +| 상태 | 코드 | 설명 | +|------|------|------| +| VALID | 200 | 계약 검증 통과 | +| INVALID_SCHEMA | 400 | 스키마 불일치 | +| VALIDATION_ERROR | 422 | 검증 실패 | +| INTERNAL_ERROR | 500 | 내부 오류 | + +--- + +## 3. 재시도 메커니즘 (Retry) + +### 3.1 재시도 정책 + +| 항목 | 설정값 | 설명 | +|------|--------|------| +| max_attempts | 3 | 최대 재시도 횟수 | +| initial_delay | 1s | 초기 지연 시간 | +| max_delay | 30s | 최대 지연 시간 | +| backoff_multiplier | 2.0 | 지연 증가 배율 | +| jitter | true | 랜덤 지터 적용 | + +### 3.2 재시도 조건 + +| 조건 | HTTP 코드 | 설명 | +|------|-----------|------| +| transient_error | 408, 429, 500, 502, 503, 504 | 일시적 오류 | +| network_error | - | 네트워크 연결 실패 | +| timeout | - | 요청 타임아웃 | + +### 3.3 재시도 메트릭 + +| 메트릭 | 타입 | 라벨 | 설명 | +|--------|------|------|------| +| retry.attempt | Counter | endpoint, error_type | 재시도 발생 횟수 | +| retry.success | Counter | endpoint | 재시도 후 성공 횟수 | +| retry.exhausted | Counter | endpoint | 재시도 횟수 소진 횟수 | + +--- + +## 4. 관측 지점 (Observation Points) + +### 4.1 관측 컴포넌트 + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Observability Layer │ +├─────────────┬─────────────┬─────────────┬──────────────────┤ +│ Tracer │ Metrics │ Log │ Alert │ +│ │ Collector │ Emitter │ Manager │ +├─────────────┴─────────────┴─────────────┴──────────────────┤ +│ Agent Runtime Core │ +├─────────────┬─────────────┬─────────────┬──────────────────┤ +│ MiniMax │ Connection │ Contract │ Retry │ +│ Connector │ Pool │ Emitter │ Handler │ +└─────────────┴─────────────┴─────────────┴──────────────────┘ +``` + +### 4.2 관측 포인트 매핑 + +| 포인트 | 수집 데이터 | 출력 | +|--------|------------|------| +| request.start | 타임스탬프, 엔드포인트 | trace_id, span | +| request.duration | 소요 시간 | histogram | +| connection.acquired | 풀 이름, 대기 시간 | gauge, histogram | +| connection.wait_time | 대기 시간, 풀 이름 | histogram | +| connection.released | 풀 이름 | gauge | +| contract.validation | 검증 결과, 스키마 버전 | counter, histogram | +| circuit.state | 회로 차단기 상태 | gauge | +| retry.attempt | 재시도 횟수, 오류 유형 | counter | + +### 4.3 메트릭 수집 파이프라인 + +``` +[애플리케이션] → [Instrumentation] → [MetricsCollector] → [Prometheus] + ↓ ↓ ↓ ↓ + events metrics aggregation scrape +``` + +--- + +## 5. 서킷 브레이커 (Circuit Breaker) + +### 5.1 상태 전이 + +``` +CLOSED ──[실패율 초과]──→ OPEN ──[시간 경과]──→ HALF_OPEN + ↑ │ │ + └─────[재시도 성공]───────┴─────[성공 임계값]──────┘ +``` + +### 5.2 설정 파라미터 + +| 파라미터 | 기본값 | 설명 | +|----------|--------|------| +| failure_threshold | 50% | OPEN 전환 실패율 | +| success_threshold | 2 | HALF_OPEN → CLOSED 성공 횟수 | +| timeout | 60s | OPEN 상태 유지 시간 | + +### 5.3 서킷 브레이커 메트릭 + +| 메트릭 | 타입 | 설명 | +|--------|------|------| +| circuit.state | Gauge | 현재 상태 (0=CLOSED, 1=OPEN, 2=HALF_OPEN) | +| circuit.transitions | Counter | 상태 전이 횟수 | +| circuit.rejected | Counter | 차단된 요청 수 | + +--- + +## 6. 통합 메트릭 요약 + +| 메트릭명 | 타입 | 라벨 | 출처 | +|----------|------|------|------| +| request.start | Counter | endpoint, method | MiniMaxConnector | +| request.duration | Histogram | endpoint, status | MiniMaxConnector | +| connection.acquired | Gauge | pool_name | ConnectionPool | +| connection.wait_time | Histogram | pool_name | ConnectionPool | +| connection.released | Gauge | pool_name | ConnectionPool | +| retry.attempt | Counter | endpoint, error_type | RetryHandler | +| retry.success | Counter | endpoint | RetryHandler | +| retry.exhausted | Counter | endpoint | RetryHandler | +| contract.validation | Counter | schema_version, result | ContractEmitter | +| circuit.state | Gauge | endpoint | CircuitBreaker | +| circuit.transitions | Counter | from_state, to_state | CircuitBreaker | +| health.status | Gauge | component | HealthChecker | + +--- + +## 7. 참조 문서 + +- SPECIFICATION.md: 런타임 컴포넌트 및 의존성 정의 +- INVENTORY.json: 메트릭 및 컴포넌트 인벤토리