OpenTelemetry 추적

OpenTelemetry 추적 (OpenTelemetry Tracing)

Docker Agent는 에이전트 실행(run)의 OpenTelemetry 트레이스를 어떤 OTLP/HTTP 백엔드로든 내보낼 수 있어요. 이는 제품 분석 텔레메트리와는 별개이며, --otel 플래그로 선택(opt-in)할 수 있답니다.

출처: 문서

본문

활성화하면 Docker Agent는 OpenTelemetry semantic conventions을 따르는 OpenTelemetry GenAI(gen_ai.*) 및 MCP(mcp.*) 스팬(span)을 내보내요. 스팬은 에이전트 턴, 모델 호출(토큰 사용량·비용 속성 포함), 도구 호출, MCP 클라이언트/서버 활동, 하위 에이전트 핸드오프, 제공자 폴백을 모두 다뤄요. W3C traceparent 컨텍스트도 전파되어 전체 실행이 하나의 연결된 트레이스 트리로 렌더링돼요.

활성화 (Enabling)

docker agent run agent.yaml --otel

내보내기(exporter) 엔드포인트를 구성하지 않으면 스팬은 no-op으로 로컬에만 기록돼요. 어딘가로 보내려면 아래에 설명된 표준 OTLP 환경 변수를 설정하면 돼요.

구성 (Configuration)

Docker Agent는 표준 OTLP 환경 변수를 읽어요:

Variable	Purpose
`OTEL_EXPORTER_OTLP_ENDPOINT`	기본 OTLP/HTTP 엔드포인트. 신호 하위 경로(`/v1/traces`, `/v1/metrics`, `/v1/logs`)가 자동으로 추가돼요.
`OTEL_EXPORTER_OTLP_HEADERS`	모든 내보내기 요청과 함께 보내는 쉼표로 구분된 key=value 헤더 (예: Authorization 헤더).
`OTEL_RESOURCE_ATTRIBUTES`	모든 스팬에 병합되는 추가 리소스 속성.
`OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT`	`true` 로 설정하면 프롬프트와 응답 메시지 내용을 스팬 속성으로 캡처해요. 기본값은 꺼짐.

Note 기본 엔드포인트 (Base endpoint), 전체 신호 URL이 아님 OTEL_EXPORTER_OTLP_ENDPOINT 는 기본 엔드포인트로 설정해요 (예: https://cloud.langfuse.com/api/public/otel). Docker Agent가 알아서 /v1/traces 를 붙여주는데, 이는 Langfuse와 LangSmith가 문서화한 값과 일치해요. 호스트:포트만 넣어도 되며 https:// (localhost는 http://)가 붙어요.

Warning 메시지 내용에는 민감한 데이터가 포함될 수 있어요 OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT 는 채팅 기록에 PII, 비밀, 내부 문서가 자주 포함되기 때문에 기본적으로 꺼져 있어요. 그 내용을 내보내는 것이 허용되는 백엔드와 환경에서만 활성화하세요.

백엔드 (Backends)

프로토콜 지원은 OTLP over HTTP(http/protobuf)예요. gRPC 엔드포인트는 현재 지원되지 않아요.

Langfuse

Langfuse는 OTLP 엔드포인트를 노출하고 프로젝트의 public/secret 키로 만든 HTTP Basic 인증을 사용해요:

# Base64 of "public_key:secret_key"
LANGFUSE_AUTH=$(echo -n "pk-lf-...:sk-lf-..." | base64)

export OTEL_EXPORTER_OTLP_ENDPOINT="https://cloud.langfuse.com/api/public/otel"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic ${LANGFUSE_AUTH}"

docker agent run agent.yaml --otel

지역별 및 자체 호스팅 호스트도 같은 /api/public/otel 기본 경로를 사용해요:

Region	Endpoint
EU	`https://cloud.langfuse.com/api/public/otel`
US	`https://us.cloud.langfuse.com/api/public/otel`
Self-hosted (>= v3.22.0)	`http://localhost:3000/api/public/otel`

LangSmith

LangSmith는 x-api-key 헤더(원시 API 키, Basic/Bearer 접두사 없음)로 인증해요. 선택적인 Langsmith-Project 헤더로 트레이스를 이름 있는 프로젝트로 라우팅할 수 있어요:

export OTEL_EXPORTER_OTLP_ENDPOINT="https://api.smith.langchain.com/otel"
export OTEL_EXPORTER_OTLP_HEADERS="x-api-key=<your-api-key>,Langsmith-Project=<project>"

docker agent run agent.yaml --otel

OpenTelemetry Collector

어떤 OTLP/HTTP 수집기(OpenTelemetry Collector, Grafana Alloy, Jaeger 등)든 기본 엔드포인트만 가리키면 동작해요:

export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318"
docker agent run agent.yaml --otel

Note Langfuse와 LangSmith는 트레이스만 수집해요 두 백엔드 모두 traces 신호만 받아요. Docker Agent는 같은 엔드포인트에서 metric과 log 내보내기도 연결하므로, 이들의 주기적 내보내기는 트레이스 전용 백엔드에서 404를 반환해요. 이는 트레이스에는 무해하고 debug 로그에만 나타나요. 메트릭과 로그도 원하면 전체 OTLP 수집기를 엔드포인트에 연결하세요.

로컬에서 트레이스 확인하기 (Inspecting traces locally)

--debug 를 사용하면 백엔드를 세우지 않고도 텔레메트리 활동을 디버그 로그(~/.cagent/cagent.debug.log, 기본값)로 출력할 수 있어요:

docker agent run agent.yaml --otel --debug

OpenTelemetry 추적