관측성 · Agent-Lab

OpenTelemetry로 모든 에이전트 상호작용의 트레이스, 메트릭, 로그를 수집

관측성이 내장된 이유

에이전트는 로그만 읽어서는 디버깅하기 어렵습니다. 중요한 동작은 중첩된 LLM 호출, 도구 호출, 데이터베이스 왕복 안에 있기 때문입니다. Agent-Lab은 관측성을 나중에 덧붙이는 부가 기능이 아니라 프레임워크의 기능으로 다룹니다. 모든 HTTP 요청, 모델 호출, SQL 쿼리, 외부 HTTP 호출이 스팬이 되며, 업계 표준인 OpenTelemetry (OpenLLMetry 및 OpenInference 시맨틱 규칙 포함)로 내보내집니다.

처음부터 끝까지 OTLP를 사용하므로, Grafana 스택, Elastic, Langfuse, LangWatch, 또는 회사에서 이미 사용 중인 APM 등 컬렉터와 호환되는 모든 백엔드를 사용할 수 있습니다.

계측 대상

설정은 agent_lab/infrastructure/metrics/tracer.py에 있습니다. OTEL_EXPORTER_OTLP_ENDPOINT가 설정되어 있으면 다음 항목이 자동으로 트레이싱됩니다.

계측기	확인할 수 있는 내용
FastAPI	요청마다 라우트, 상태, 소요 시간을 담은 서버 스팬 하나
HTTPX	에이전트나 서비스가 수행하는 모든 외부 HTTP 호출
LangChain	토큰 사용량을 포함한 모든 LLM/체인 호출 — 에이전트 트레이싱의 핵심
OpenAI	OpenAI 네이티브 호출(OpenInference 규칙)
SQLAlchemy	모든 데이터베이스 구문(관계형, 벡터 검색, 체크포인트)

리소스 식별 정보는 SERVICE_NAME(기본값 Agent-Lab)과 SERVICE_VERSION(기본값 snapshot)에서 가져옵니다. 불필요한 경로(/status/*, /docs, /openapi.json, 파비콘)는 사용자 정의 샘플러가 제외합니다.

활성화하기

코드 변경 없이 엔드포인트만 설정하면 됩니다. OTEL_EXPORTER_OTLP_ENDPOINT가 설정되어 있으면 스팬이 OTLP/HTTP를 통해 <endpoint>/v1/traces, /v1/metrics, /v1/logs로 전송됩니다. 설정되어 있지 않으면 트레이싱이 꺼집니다.

# Point the app at any OTLP/HTTP collector
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 uvicorn agent_lab.main:app --reload

로컬 개발 환경에서는 사전 구성된 두 가지 스택이 모든 연결 작업을 대신 처리합니다(프레임워크 저장소에서 실행).

docker compose -f compose-grafana.yml up --build      # collector + Prometheus + Tempo + Loki + Grafana
docker compose -f compose-opensearch.yml up --build   # collector + Data Prepper + OpenSearch + Dashboards

각 스택은 각각 otel/grafana/와 otel/opensearch/ 아래에 자체 OpenTelemetry Collector 구성을 포함하고 있으며, 이 파일들이 트레이스, 메트릭, 로그의 라우팅 방식에 대한 레퍼런스입니다. 프로덕션 토폴로지는 배포 가이드를 참고하세요.

LLM 관측성 백엔드

Agent-Lab은 기본 OTel 외에도 TracingBackend 추상화(agent_lab/core/container.py에서 DI 프로바이더로 연결됨)를 통해 목적에 맞게 설계된 LLM 관측성 플랫폼과 연동됩니다. 기본 제공되는 두 백엔드는 모두 환경 변수만으로 활성화되며, 해당 변수가 없으면 별도 알림 없이 스스로 비활성화되므로 앱은 항상 정상적으로 부팅됩니다.

Langfuse

Langfuse 프로젝트의 세 가지 변수를 설정하면 모든 트레이스가 langfuse.trace.* 속성과 함께 Langfuse의 OTLP 엔드포인트({LANGFUSE_HOST}/api/public/otel/v1/traces)로 미러링됩니다. 프롬프트, 완성 결과, 토큰 사용량, 비용이 기록되므로 시뮬레이션 실험에 바로 활용할 수 있습니다.

변수	용도
`LANGFUSE_HOST`	Langfuse 기본 URL
`LANGFUSE_PUBLIC_KEY`	`pk-lf-…`
`LANGFUSE_SECRET_KEY`	`sk-lf-…`

LangWatch

변수	용도
`LANGWATCH_ENDPOINT`	LangWatch 엔드포인트
`LANGWATCH_API_KEY`	LangWatch API 키

LangWatch는 메시지마다 langwatch.trace() 스팬을 기록하며, 시뮬레이션 스위트는 이를 통해 실험별 심사 점수를 기록합니다.

참고용 대시보드

스택	가이드	UI
Grafana + Prometheus + Tempo + Loki	otel/GRAFANA.md	http://localhost:3000
OpenSearch Dashboards	otel/OPENSEARCH.md	http://localhost:5601

두 가이드 모두 대시보드가 동작하는 모습을 담은 데모 영상을 포함하고 있습니다.

확장: 사용자 정의 백엔드

TracingBackend는 공개 API의 일부입니다. 이를 상속해 스팬을 자체 플랫폼으로 전달하고, Container에 등록하세요.

from agent_lab import Container, TracingBackend


class MyBackend(TracingBackend):
    ...  # export spans wherever your platform needs them


class MyContainer(Container):
    # replace or extend the shipped tracing_backends provider list
    ...

구성 레퍼런스에서 관측성 관련 변수를 하나의 표로 모두 확인할 수 있습니다.