Agent Super Spy: 로컬 LLM 관측성(Observability) 통합 스택

섹션별 상세

Agent Super Spy는 llm-proxy, mitmproxy, Phoenix, Opik을 결합하여 로컬 개발 환경에서 LLM 호출을 모니터링하는 통합 환경을 구축한다. llm-proxy는 경로 기반 라우팅을 통해 Anthropic, OpenAI 등 다양한 프로바이더의 요청을 처리하며, OpenTelemetry(OTEL)를 통해 트레이스 데이터를 내보낸다.

mitmproxy를 활용하여 암호화된 HTTPS 트래픽을 포함한 모든 원시 네트워크 패킷을 웹 UI에서 직접 검사할 수 있다. 이를 통해 HTTP 헤더, 요청 페이로드, 응답 데이터를 상세히 확인할 수 있으며, 로컬 개발 시 에이전트가 외부와 어떻게 통신하는지 투명하게 파악 가능하다.

bash

# Route all traffic through mitmproxy for inspection
export HTTP_PROXY=http://localhost:8080
export HTTPS_PROXY=http://localhost:8080

# Or route only LLM calls through the llm-proxy
export ANTHROPIC_BASE_URL=http://localhost:4000/anthropic
export OPENAI_BASE_URL=http://localhost:4000/openai

에이전트의 트래픽을 프록시로 라우팅하기 위한 환경 변수 설정

프록시 레벨에서 API 키 관리 기능을 제공하여 보안과 편의성을 동시에 확보한다. keys.jsonc 파일을 통해 로컬용 가상 키와 실제 프로바이더 키를 매핑하면, SDK에는 가상 키를 사용하고 프록시가 업스트림 API로 전달할 때 실제 키로 교체하는 방식이다.

json

{
  "my-local-key": {
    "anthropic": "sk-ant-real-key...",
    "openai": "sk-real-key...",
    "api.openrouter.com": "sk-or-real-key..."
  }
}

keys.jsonc 파일을 이용한 로컬 키와 실제 API 키 매핑 설정 예시

Docker Compose를 기반으로 설계되어 기존 프로젝트와의 연결이 용이하다. 공유 네트워크(llm-proxy-net)를 통해 다른 컨테이너에서 실행 중인 에이전트도 쉽게 프록시에 접근할 수 있으며, setup.sh와 start.sh 스크립트로 복잡한 설정 없이 즉시 스택을 실행할 수 있다.

yaml

networks:
  llm-proxy-net:
    name: llm-proxy-net
    external: true

services:
  my-agent:
    networks:
      - default
      - llm-proxy-net
    environment:
      ANTHROPIC_BASE_URL: http://llm-proxy:4000/anthropic

기존 Docker 프로젝트를 LLM 관측성 네트워크에 연결하는 설정

용어 해설

관측성(Observability): — 시스템의 내부 상태를 외부로 출력되는 데이터를 통해 파악할 수 있는 능력이다. LLM 애플리케이션에서는 프롬프트 입력, 모델 응답, 실행 시간, 비용 등을 추적하여 성능을 모니터링하고 문제를 진단하는 데 필수적이다.
역방향 프록시(Reverse Proxy): — 클라이언트와 서버 사이에서 요청을 대신 받아 전달하는 서버이다. 이 아티클에서는 LLM API 요청을 가로채서 인증 키를 교체하거나 데이터를 로깅하는 중간 매개체 역할을 수행한다.
오픈텔레메트리(OpenTelemetry): — 로그, 메트릭, 트레이스 등 텔레메트리 데이터를 수집하고 전송하기 위한 오픈소스 표준 프레임워크이다. 다양한 관측성 도구들이 서로 호환될 수 있도록 데이터 형식을 표준화하는 역할을 한다.
인증 기관 인증서(CA Certificate): — 디지털 인증서의 정당성을 보증하는 신뢰 기관의 증명서이다. mitmproxy를 통해 암호화된 HTTPS 트래픽을 복호화하여 내용을 확인하려면 클라이언트 기기에 해당 프록시의 CA 인증서를 설치해야 한다.

기술

Opik
Phoenix
mitmproxy
Docker
Claude SDK

활용 사례

로컬 LLM 에이전트 호출 트레이싱
에이전트 네트워크 트래픽 실시간 모니터링
API 키 보안 관리 및 스와핑
복잡한 에이전트 워크플로우 디버깅

언급된 리소스

GitHubOpik GitHub

문서Phoenix Documentation

문서mitmproxy Documentation