forge-bot/runtime-smoke-20260710143823
1
0
Fork 0
Code Issues Pull requests 4 Projects Releases Packages Wiki Activity Actions
runtime-smoke-20260710143823/runtime-analysis/AGENT_RUNTIME_ANALYSIS.md

7.1 KiB
Raw Permalink Blame History

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: 메트릭 및 컴포넌트 인벤토리