diff --git a/.forge/runtime-analysis-001-attempt-2-run-53557bb0b282.md b/.forge/runtime-analysis-001-attempt-2-run-53557bb0b282.md deleted file mode 100644 index 44058ce..0000000 --- a/.forge/runtime-analysis-001-attempt-2-run-53557bb0b282.md +++ /dev/null @@ -1,3 +0,0 @@ -# runtime-analysis-001-attempt-2-run-53557bb0b282 - -Forge 이슈 작업 브랜치 `forge/runtime-analysis-001-attempt-2-run-53557bb0b282`. diff --git a/runtime-analysis/AGENT_RUNTIME_ANALYSIS.md b/runtime-analysis/AGENT_RUNTIME_ANALYSIS.md deleted file mode 100644 index eb4f7bf..0000000 --- a/runtime-analysis/AGENT_RUNTIME_ANALYSIS.md +++ /dev/null @@ -1,186 +0,0 @@ -# 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: 메트릭 및 컴포넌트 인벤토리 diff --git a/runtime-analysis/INVENTORY.json b/runtime-analysis/INVENTORY.json deleted file mode 100644 index 0c6fbc3..0000000 --- a/runtime-analysis/INVENTORY.json +++ /dev/null @@ -1,140 +0,0 @@ -{ - "inventory_version": "1.0.0", - "last_updated": "2026-07-10", - "components": { - "MiniMaxConnector": { - "type": "connector", - "description": "MiniMax API와의 HTTP/WebSocket 연결 관리", - "dependencies": ["ConnectionPool", "RetryHandler"], - "observation_points": ["request.start", "request.duration"] - }, - "ConnectionPool": { - "type": "pool", - "description": "연결 풀링 및 리소스 관리", - "dependencies": [], - "observation_points": ["connection.acquired", "connection.wait_time", "connection.released"] - }, - "HealthChecker": { - "type": "monitor", - "description": "연결 상태 모니터링 및 헬스 체크", - "dependencies": ["MetricsCollector"], - "observation_points": ["health.status"] - }, - "ContractEmitter": { - "type": "validator", - "description": "출력 계약 검증 및 에미터", - "dependencies": [], - "observation_points": ["contract.validation"] - }, - "RetryHandler": { - "type": "handler", - "description": "재시도 정책 및 지연 관리", - "dependencies": [], - "observation_points": ["retry.attempt", "retry.success", "retry.exhausted"] - }, - "CircuitBreaker": { - "type": "protection", - "description": "서킷 브레이커 상태 관리", - "dependencies": ["MiniMaxConnector"], - "observation_points": ["circuit.state", "circuit.transitions", "circuit.rejected"] - } - }, - "metrics": [ - { - "name": "request.start", - "type": "Counter", - "labels": ["endpoint", "method"], - "description": "API 요청 시작 카운터" - }, - { - "name": "request.duration", - "type": "Histogram", - "labels": ["endpoint", "status"], - "description": "API 요청 소요 시간" - }, - { - "name": "connection.acquired", - "type": "Gauge", - "labels": ["pool_name"], - "description": "현재 획득된 연결 수" - }, - { - "name": "connection.wait_time", - "type": "Histogram", - "labels": ["pool_name"], - "description": "연결 대기 시간" - }, - { - "name": "connection.released", - "type": "Gauge", - "labels": ["pool_name"], - "description": "반환된 연결 수" - }, - { - "name": "retry.attempt", - "type": "Counter", - "labels": ["endpoint", "error_type"], - "description": "재시도 발생 횟수" - }, - { - "name": "retry.success", - "type": "Counter", - "labels": ["endpoint"], - "description": "재시도 후 성공 횟수" - }, - { - "name": "retry.exhausted", - "type": "Counter", - "labels": ["endpoint"], - "description": "재시도 횟수 소진 횟수" - }, - { - "name": "contract.validation", - "type": "Counter", - "labels": ["schema_version", "result"], - "description": "계약 검증 결과 카운터" - }, - { - "name": "circuit.state", - "type": "Gauge", - "labels": ["endpoint"], - "description": "서킷 브레이커 상태 (0=CLOSED, 1=OPEN, 2=HALF_OPEN)" - }, - { - "name": "circuit.transitions", - "type": "Counter", - "labels": ["from_state", "to_state"], - "description": "서킷 브레이커 상태 전이 횟수" - }, - { - "name": "circuit.rejected", - "type": "Counter", - "labels": ["endpoint"], - "description": "차단된 요청 수" - }, - { - "name": "health.status", - "type": "Gauge", - "labels": ["component"], - "description": "컴포넌트 헬스 상태" - } - ], - "observation_points": { - "Tracer": { - "description": "분산 추적 수집기", - "spans": ["request.start", "connection.acquired", "contract.validation"] - }, - "MetricsCollector": { - "description": "메트릭 수집 및 집계", - "metrics": ["request.*", "connection.*", "retry.*", "contract.*", "circuit.*", "health.*"] - }, - "LogEmitter": { - "description": "로그 출력", - "events": ["request.start", "retry.attempt", "contract.validation"] - }, - "AlertManager": { - "description": "알림 및 경고 관리", - "triggers": ["circuit.state", "retry.exhausted", "health.status"] - } - } -} diff --git a/runtime-analysis/SPECIFICATION.md b/runtime-analysis/SPECIFICATION.md deleted file mode 100644 index aea31b3..0000000 --- a/runtime-analysis/SPECIFICATION.md +++ /dev/null @@ -1,165 +0,0 @@ -# Agent Runtime Specification - -## 1. 개요 - -본 문서는 Agent Runtime의 컴포넌트 구조, 의존성, 메트릭 명명 규칙을 정의한다. - -## 2. 컴포넌트 의존성 다이어그램 - -``` -┌─────────────────────────────────────────────────────────────────┐ -│ Agent Runtime │ -├─────────────────────────────────────────────────────────────────┤ -│ │ -│ ┌─────────────────┐ ┌─────────────────┐ │ -│ │ MiniMaxConnector │────▶│ ConnectionPool │ │ -│ └────────┬────────┘ └─────────────────┘ │ -│ │ │ -│ ▼ │ -│ ┌─────────────────┐ ┌─────────────────┐ │ -│ │ RetryHandler │ │ CircuitBreaker │ │ -│ └─────────────────┘ └─────────────────┘ │ -│ │ -│ ┌─────────────────┐ ┌─────────────────┐ │ -│ │ HealthChecker │────▶│ MetricsCollector│ │ -│ └─────────────────┘ └─────────────────┘ │ -│ │ -│ ┌─────────────────┐ │ -│ │ ContractEmitter │ │ -│ └─────────────────┘ │ -│ │ -└─────────────────────────────────────────────────────────────────┘ -``` - -## 3. 컴포넌트 정의 - -### 3.1 MiniMaxConnector - -| 속성 | 값 | -|------|-----| -| 타입 | connector | -| 설명 | MiniMax API와의 HTTP/WebSocket 연결 관리 | -| 의존성 | ConnectionPool, RetryHandler | - -### 3.2 ConnectionPool - -| 속성 | 값 | -|------|-----| -| 타입 | pool | -| 설명 | 연결 풀링 및 리소스 관리 | -| 의존성 | 없음 | - -### 3.3 RetryHandler - -| 속성 | 값 | -|------|-----| -| 타입 | handler | -| 설명 | 재시도 정책 및 지연 관리 | -| 의존성 | 없음 | - -### 3.4 CircuitBreaker - -| 속성 | 값 | -|------|-----| -| 타입 | protection | -| 설명 | 서킷 브레이커 상태 관리 | -| 의존성 | MiniMaxConnector | - -### 3.5 HealthChecker - -| 속성 | 값 | -|------|-----| -| 타입 | monitor | -| 설명 | 연결 상태 모니터링 및 헬스 체크 | -| 의존성 | MetricsCollector | - -### 3.6 ContractEmitter - -| 속성 | 값 | -|------|-----| -| 타입 | validator | -| 설명 | 출력 계약 검증 및 에미터 | -| 의존성 | 없음 | - -## 4. 메트릭 명명 규칙 - -### 4.1 명명 체계 - -모든 메트릭은 **dot-notation** 형식을 사용한다: - -``` -{domain}.{subdomain}.{name} -``` - -### 4.2 도메인 분류 - -| 도메인 | 설명 | 예시 | -|--------|------|------| -| request | 요청 관련 | request.start, request.duration | -| connection | 연결 관련 | connection.acquired, connection.wait_time | -| retry | 재시도 관련 | retry.attempt, retry.success | -| contract | 계약 관련 | contract.validation | -| circuit | 서킷 브레이커 관련 | circuit.state, circuit.transitions | -| health | 헬스 체크 관련 | health.status | - -### 4.3 메트릭 정의 - -| 메트릭명 | 타입 | 라벨 | 설명 | -|----------|------|------|------| -| request.start | Counter | endpoint, method | API 요청 시작 카운터 | -| request.duration | Histogram | endpoint, status | API 요청 소요 시간 | -| connection.acquired | Gauge | pool_name | 현재 획득된 연결 수 | -| connection.wait_time | Histogram | pool_name | 연결 대기 시간 | -| connection.released | Gauge | pool_name | 반환된 연결 수 | -| retry.attempt | Counter | endpoint, error_type | 재시도 발생 횟수 | -| retry.success | Counter | endpoint | 재시도 후 성공 횟수 | -| retry.exhausted | Counter | endpoint | 재시도 횟수 소진 횟수 | -| contract.validation | Counter | schema_version, result | 계약 검증 결과 카운터 | -| circuit.state | Gauge | endpoint | 서킷 브레이커 상태 | -| circuit.transitions | Counter | from_state, to_state | 서킷 브레이커 상태 전이 횟수 | -| circuit.rejected | Counter | endpoint | 차단된 요청 수 | -| health.status | Gauge | component | 컴포넌트 헬스 상태 | - -## 5. 관측 가능성 (Observability) - -### 5.1 관측 컴포넌트 - -| 컴포넌트 | 설명 | 수집 데이터 | -|----------|------|-------------| -| Tracer | 분산 추적 수집기 | request.start, connection.acquired, contract.validation | -| MetricsCollector | 메트릭 수집 및 집계 | request.*, connection.*, retry.*, contract.*, circuit.*, health.* | -| LogEmitter | 로그 출력 | request.start, retry.attempt, contract.validation | -| AlertManager | 알림 및 경고 관리 | circuit.state, retry.exhausted, health.status | - -### 5.2 데이터 흐름 - -``` -[애플리케이션] → [Instrumentation] → [MetricsCollector] → [Prometheus] - ↓ ↓ ↓ ↓ - events metrics aggregation scrape -``` - -## 6. 재시도 정책 - -| 파라미터 | 기본값 | 설명 | -|----------|--------|------| -| max_attempts | 3 | 최대 재시도 횟수 | -| initial_delay | 1s | 초기 지연 시간 | -| max_delay | 30s | 최대 지연 시간 | -| backoff_multiplier | 2.0 | 지연 증가 배율 | -| jitter | true | 랜덤 지터 적용 | - -## 7. 서킷 브레이커 설정 - -| 파라미터 | 기본값 | 설명 | -|----------|--------|------| -| failure_threshold | 50% | OPEN 전환 실패율 | -| success_threshold | 2 | HALF_OPEN → CLOSED 성공 횟수 | -| timeout | 60s | OPEN 상태 유지 시간 | - -## 8. 버전 정보 - -| 항목 | 값 | -|------|-----| -| 스키마 버전 | 1.0.0 | -| 문서 업데이트 | 2026-07-10 |