클로드 API, OpenTelemetry 추적 지원

앤스로픽이 10월 14일(현지시간) 클로드 API의 OpenTelemetry 트레이스 내보내기를 공개 베타로 내놨다. 클로드 개발자 공식 X 계정 ClaudeDevs는 "클로드 플랫폼이 Messages API와 Claude Managed Agents, 클로드 SDK의 OpenTelemetry 트레이스를 사용자의 관측 스택으로 보낼 수 있다"고 밝혔다. 모델 요청 하나, 도구 사용 하나마다 스팬이라는 기록 단위가 생기고, 개발자는 코드를 바꾸지 않고 이미 쓰는 관측 플랫폼에서 이를 본다. 첫 게시물은 올라온 지 3시간 만에 조회 약 31만 회를 기록했다.

내보내는 내용은 두 단계로 나뉜다. 앤스로픽은 "스팬은 OpenTelemetry gen_ai 규약을 따른다"며 기본값으로 소요 시간, 상태, 토큰 수, 모델, 도구 이름 같은 메타데이터를 담는다고 설명했다. 전송 대상을 전체 콘텐츠 모드로 바꾸면 프롬프트와 응답, 도구 입력과 도구 결과까지 함께 나간다. 플랫폼 문서에 따르면 조직이 앤스로픽과 HIPAA, FERPA, K-12 데이터 처리 제한을 맺은 경우에는 전체 콘텐츠로 설정해도 프롬프트와 응답이 빠질 수 있다.

설정은 클로드 콘솔에서 한다. 조직의 OpenTelemetry 설정 화면에서 전송 대상을 추가하고, 관측 플랫폼의 OTLP 엔드포인트와 인증 헤더를 넣는다. 전송 대상을 추가하거나 바꾸려면 콘솔 조직의 관리자 역할이 필요하고 개발자 역할은 조회만 된다. 엔드포인트는 HTTPS 443번 포트에서 protobuf 인코딩을 받는 OTLP/HTTP여야 하며, 직접 운영하는 OpenTelemetry 수집기는 기본으로 4318번 포트에서 듣기 때문에 443번을 받도록 바꾸거나 앞단에 로드밸런서를 둬야 한다. 전송 대상마다 모든 워크스페이스, 고른 워크스페이스, 일부를 뺀 전체 가운데 하나를 고른다. 설정 뒤 관측 플랫폼에서 service.name이 claude-platform인 스팬을 걸러 보면 되고, 콘솔의 전송 상태가 정상으로 바뀌기까지 약 1분이 걸린다고 문서는 안내했다.

API 쪽 트레이스는 개발자 앱의 트레이스와 이어 붙일 수 있다. API는 요청마다 W3C traceparent 헤더에서 트레이스 맥락을 읽고, 헤더의 샘플링 표시가 꺼져 있으면 그 요청의 스팬을 만들지 않는다. MCP 커넥터로 연결한 MCP 서버에도 traceparent를 넘겨, 서버가 자기 스팬을 API 스팬 밑에 둘 수 있다. 다만 클로드 플랫폼 온 AWS는 아직 이 헤더를 지원하지 않아 그쪽으로 보낸 요청의 스팬은 늘 별도 트레이스로 시작한다.

SDK 쪽은 앱이 등록한 트레이서 프로바이더를 그대로 쓴다. 문서에 따르면 콘텐츠 모드 기본값은 메타데이터만이고, 스팬 하나에 담는 콘텐츠 상한 기본값은 0.75MB다. 대화 ID를 넣으면 여러 호출이 gen_ai.conversation.id 하나로 묶인다. 트레이스 맥락 전파 끄기 옵션은 파이썬, 타입스크립트, 고, 자바, 루비, PHP SDK에서 쓸 수 있다. SDK 추적은 클로드 API와 클로드 플랫폼 온 AWS, 아마존 베드록, 구글 클라우드, 마이크로소프트 파운드리에서 모두 베타로 지원된다. Managed Agents를 자체 샌드박스에서 돌리면 도구 스팬은 API 대신 SDK가 만들고, 작업 항목마다 anthropic.environment.work 스팬 하나로 묶인다.

전송은 최선 노력 방식이다. 문서는 같은 스팬이 두 번 이상 도착할 수 있어 트레이스 ID와 스팬 ID로 중복을 걸러야 하고, 전송 전에 잃어버린 스팬은 다시 보내지 않는다고 적었다. 엔드포인트는 TLS 연결을 5초 안에, 응답 헤더를 5초 안에 돌려줘야 하고 전송 한 번은 모두 10초 뒤 시간 초과된다. 리디렉션으로 응답하거나 공인 IP가 아닌 주소로 풀리거나 24시간 동안 전송이 모두 실패하면 API가 그 대상을 끈다. 조직당 전송 대상은 꺼진 것까지 합쳐 10개, 대상 하나에 고를 수 있는 워크스페이스는 1000개, 요청 헤더는 20개까지다. 문서는 "전송 뒤 데이터는 사용자가 고른 서비스가 앤스로픽 밖에서 그 서비스의 보존·접근 정책에 따라 보관한다"고 명시했다.

메탈이 확인한 시연 영상은 장애 대응 에이전트를 예로 든다. 경보가 울리면 에이전트가 서비스별 지표를 모아 장애 요약을 쓰는데, 오류 상태 스팬을 도구 이름별로 묶자 Query Metrics 도구가 호출의 약 3분의 1에서 시간 초과를 내며 에이전트가 재시도에 턴을 더 쓰고 있었다. 영상 속 개발자는 세션 로그를 열지 않고 약 30초 만에 원인을 찾았고, 모델 요청 스팬의 입력·출력·캐시 토큰 수를 에이전트별로 묶어 재시도 비용까지 확인했다. 메탈은 클로드 매니지드 에이전트가 동적 워크플로를 공개했다고 보도한 바 있으며, 이번 기능은 그렇게 길어진 에이전트 실행을 밖에서 들여다보는 창구다.

이번 발표의 요점은 표준이다. 앤스로픽은 자체 대시보드를 새로 만들지 않고 업계 규약인 OpenTelemetry gen_ai 형식에 맞춰 데이터를 내보내는 길을 택했고, 개발자는 다른 모델과 다른 앱의 트레이스 옆에 클로드 에이전트의 요청과 도구 호출, 비용을 한 화면에 놓게 됐다.