From f61ceda16b56224cded424d72c2323089ce14916 Mon Sep 17 00:00:00 2001 From: forge-bot Date: Tue, 14 Jul 2026 04:55:52 +0000 Subject: [PATCH] =?UTF-8?q?=EC=97=90=EC=9D=B4=EC=A0=84=ED=8A=B8=20?= =?UTF-8?q?=EB=9F=B0=ED=83=80=EC=9E=84=20=EB=B6=84=EC=84=9D=20=EC=82=B0?= =?UTF-8?q?=EC=B6=9C=EB=AC=BC=20=EC=83=9D=EC=84=B1=20(runtime-analysis-001?= =?UTF-8?q?)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- runtime-analysis/SPECIFICATION.md | 165 ++++++++++++++++++++++++++++++ 1 file changed, 165 insertions(+) create mode 100644 runtime-analysis/SPECIFICATION.md diff --git a/runtime-analysis/SPECIFICATION.md b/runtime-analysis/SPECIFICATION.md new file mode 100644 index 0000000..aea31b3 --- /dev/null +++ b/runtime-analysis/SPECIFICATION.md @@ -0,0 +1,165 @@ +# 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 |