클로드 API OpenTelemetry 내보내기 베타: 바뀐 점과 지금 할 일

클로드 OpenTelemetry 내보내기는 Messages API 요청과 클로드 매니지드 에이전트 세션의 처리 기록(트레이스)을 이미 쓰는 모니터링 도구로 보내 주는 베타 기능이다. Anthropic은 릴리스 노트에서 2026년 10월 14일에 이 베타를 시작했다고 밝혔다.

클로드 OpenTelemetry 내보내기, 무엇이 추가됐나

이번 발표로 클로드 API를 운영 중인 팀은 요청이 어디서 느려지고 어떤 도구 호출에서 실패하는지를 기존 모니터링 화면에서 보게 됐다. 택배 송장 번호로 물건이 어느 집하장에 머무는지 따라가는 것과 비슷하다. OpenTelemetry는 어느 모니터링 도구에서나 읽는 공통 표준이라, 도구를 바꿔도 송장 형식은 그대로다. 클로드 쪽도 이 표준에 맞춰 기록을 내보내므로, Datadog이나 Grafana 같은 도구는 별도 변환 없이 읽을 수 있다. 다만 베타라서 항목 이름이 바뀔 수 있다.

공식 문서에 따르면 트레이스는 요청 하나가 거치는 전체 기록이고, 스팬(span)은 그 안의 한 단계(모델 요청, 도구 사용 등)다. 대상은 Messages API 요청, 도구 사용, 매니지드 에이전트 세션이다. 지원 환경은 Claude API와 Claude Platform on AWS이고, SDK 쪽은 Amazon Bedrock, Google Cloud, Microsoft Foundry에서도 베타로 쓸 수 있다.

구분	SDK 추적	API 추적
설정 방법	코드	Console 화면
필요 권한	없음	Console 관리자(admin)
보이는 것	SDK를 쓰는 클라이언트의 요청, 내 쪽 도구 실행	요청 안의 모델 실행, 매니지드 에이전트 턴, API가 돌리는 서버 도구
적용 범위	SDK를 쓰는 클라이언트	모든 클라이언트

둘을 함께 켜면 한 요청의 SDK 기록과 API 기록이 한 트레이스로 이어진다. SDK 스팬은 Python, TypeScript, C#, Go, Java, PHP, Ruby에서 나온다.

Console에서 수신 주소 등록하는 순서

API 추적 설정 문서가 안내하는 순서다. 관리자 권한과, HTTPS 443 포트에서 protobuf를 받는 OTLP/HTTP 주소, 그 주소의 인증 정보(API 키 등)가 필요하다.

1. Console의 OpenTelemetry 설정 페이지에서 Add destination을 누른다.
2. Provider를 고른다. 목록에 없으면 Custom을 고르고 OTLP endpoint URL을 넣는다. 주소 끝에 /v1/traces는 붙이지 않는다. API가 알아서 붙인다.
3. Request headers에 인증 헤더를 넣는다. 저장 뒤에는 값이 다시 보이지 않는다.
4. Content mode와 Workspaces(전체, 선택, 일부 제외)를 정하고 저장한다.
5. destination의 더보기 메뉴에서 Test를 눌러 테스트 스팬을 보낸다.

확인 방법은 두 가지다. Console의 Delivery 열이 Healthy가 되면(최대 1분쯤 걸린다) 전달에 성공한 것이다. 모니터링 도구에서는 service.name = claude-platform으로 걸러 anthropic.test 스팬이 왔는지 본다. Failing이 뜨면 마우스를 올려 마지막 오류를 확인한다. 401·403은 인증 헤더, 404는 주소 경로가 틀린 경우가 많다.

코드로 등록하려면 Admin API의 telemetry-destinations를 쓴다. 문서의 cURL 예시는 anthropic-beta: telemetry-destinations-2026-08-11 헤더를 붙인다.

프롬프트까지 보낼까: 내용 모드 선택

기본값은 Metadata only로, 식별자·시간·상태·토큰 수와 에이전트·도구 이름만 나간다. Full content를 고르면 프롬프트와 응답까지 스팬에 실려, 실패 원인을 대화 단위로 읽거나 실제 트래픽으로 평가 데이터를 만들 수 있다. 대신 그 내용은 선택한 모니터링 도구에 그 도구의 보관 기간과 접근 권한대로 쌓인다.

공식 문서가 밝힌 조건은 다음과 같다. HIPAA, FERPA, K-12 데이터 처리 제한이 Anthropic과 설정된 조직은 Full content를 골라도 메타데이터만 나간다. 제로 데이터 보관(ZDR)을 쓰는 조직도 Messages API에서는 Full content를 쓸 수 있지만, 매니지드 에이전트는 ZDR 대상이 아니다. 스팬 하나의 내용은 기본 0.75MB까지이고, 넘으면 시스템 프롬프트와 앞쪽 메시지부터 잘리며 anthropic.content.truncated가 true로 표시된다.

SDK로 먼저 확인해 보는 법

SDK 설정 문서는 콘솔 출력으로 먼저 스팬을 보는 방법을 안내한다. Python 기준으로 pip install --upgrade anthropic과 pip install opentelemetry-sdk를 설치하고, 첫 호출 전에 TracerProvider에 ConsoleSpanExporter를 등록한다. 그 뒤 메시지를 한 번 보내면 콘솔에 anthropic.messages.create 스팬 하나가 찍힌다. 이것이 성공 기준이다.

모니터링 도구로 보낼 때는 콘솔 출력 부분을 OTLP 내보내기로 바꾼다. SDK의 내용 모드는 traces.content_mode 옵션이나 ANTHROPIC_OPEN_TELEMETRY_TRACES_CONTENT_MODE=content 환경 변수로 정하고, 기본은 metadata_only다. 베타 동안 SDK 옵션과 스팬 이름이 깨지는 방식으로 바뀔 수 있으니 SDK 버전은 고정해 두는 편이 안전하다.

토큰 합산과 한계, 지금 할 일

스팬으로 토큰을 합산할 때는 한 출처만 더해야 한다. 같은 요청에 SDK 스팬과 API 스팬이 모두 있으면 API 스팬만 합산한다. 둘 다 이름이 anthropic.messages.create이므로 SDK 쪽은 CLIENT, API 쪽은 SERVER 종류로 구분한다. 문서는 스팬 전달이 최선 노력(best effort)이라 일부가 유실될 수 있다고 밝히므로, API 키별 사용량 대조에는 Usage API를 쓰라고 안내한다.

운영 한도도 있다. 조직당 destination은 10개(비활성 포함)까지이고, 24시간 동안 전달이 모두 실패하거나 엔드포인트가 3xx 리디렉션을 보내면 API가 destination을 비활성화한다. 비활성 동안의 스팬은 다시 보내지 않는다. 지금 할 일은 세 가지다.

1. 테스트용 워크스페이스에 destination 하나를 Metadata only로 등록하고 Test로 anthropic.test 스팬을 확인한다.
2. 실제 요청 한 건을 보내 Delivery가 Healthy인지, 도구에서 claude-platform 스팬이 보이는지 확인한다.
3. Full content는 모니터링 도구의 보관 기간과 접근 권한을 확인한 뒤에만 켠다.

같은 계열의 기능이 궁금하면 클로드 매니지드 에이전트 다이내믹 워크플로우 설정·한도 정리와 매니지드 에이전트 예약 배포 소식도 참고할 수 있다.

자주 묻는 질문

클로드 코드 사용량도 이 기능으로 보나요?

아니다. 공식 문서는 Claude Code, Agent SDK, Cowork는 각각 별도의 모니터링 문서를 안내한다.

destination을 등록하려면 어떤 권한이 필요한가요?

Console 조직의 관리자(admin) 역할이 필요하다. 개발자 역할은 목록만 볼 수 있다.

스팬이 안 보일 때는 무엇부터 확인하나요?

그 워크스페이스를 포함하는 활성 destination이 있는지 본다. 새로 포함된 뒤에도 스팬이 도착하기까지 최대 1분쯤 걸린다.