ClaudeDevs는 Claude Platform의 OpenTelemetry 트레이스가 공개 베타라고 밝혔습니다

무엇이 바뀌었나

ClaudeDevs는 스팬이 OpenTelemetry gen_ai 컨벤션을 따르며, 기본값으로는 소요 시간, 상태, 토큰 수, 모델, 도구 이름 같은 메타데이터를 담는다고 밝혔습니다. 같은 글은 대상을 "full content"로 바꾸면 프롬프트, 응답, 도구 입력, 도구 결과도 함께 내보낸다고 했습니다.

API 문서는 Claude API가 모델 요청마다, 그리고 도구 사용마다 스팬을 내보내며, 대상은 Messages API 요청과 Managed Agents 세션이라고 합니다. 대상이 있으면 애플리케이션 코드를 바꾸지 않고 그 스팬을 볼 수 있습니다. 기본값에서 한 요청이나 한 세션의 스팬은 자체 트레이스에서 시작합니다. 그 스팬이 애플리케이션 트레이스 아래에 붙어야 하면 API는 W3C traceparent 헤더를 읽습니다. 그 헤더의 sampled 플래그가 꺼져 있으면 API는 그 요청의 스팬도, 그 아래 스팬도 내보내지 않습니다. Claude Platform on AWS는 아직 이 헤더를 지원하지 않습니다. 그쪽으로 보낸 요청의 스팬은 sampled 플래그가 꺼져 있어도 항상 자체 트레이스에서 시작합니다.

SDK 문서는 다른 경로를 설명합니다. SDK는 자신이 보내는 요청마다, 그리고 tool runner가 실행하는 도구 사용마다 애플리케이션 안에서 스팬을 내고, 애플리케이션의 OpenTelemetry 익스포터가 그것을 보냅니다. 베타 동안 SDK 옵션과 스팬 스키마는 코드, 쿼리, 대시보드를 깨뜨릴 수 있으며, 스팬, 속성, 옵션, 환경 변수의 이름 변경도 여기에 포함됩니다. SDK 페이지는 SDK 버전을 고정하라고 합니다. 스팬은 기본으로 켜져 있습니다.

Console 대상은 Metadata only 또는 Full content입니다. SDK에서 traces.content_mode의 기본값은 metadata_only입니다. 프롬프트와 응답을 포함하는 SDK 값은 content이며, Console 대상의 Full content와는 다른 라벨입니다. SDK 옵션 표는 스팬당 기본 0.75 MB를 적고, traces.max_content_bytes로 바꿉니다. 그 페이지들이 이름을 밝히는 gen_ai 속성은 gen_ai.conversation.id에 두는 선택적 대화 id뿐이며, 두 콘텐츠 모드에서 모두 내보내집니다. SDK 페이지는 그 id에 개인정보나 비밀을 넣지 말라고 합니다. Full content 대상인데도 프롬프트나 응답이 없으면, API 문서는 HIPAA, FERPA, 또는 K-12 제한 가능성을 가리킵니다.

같은 요청의 SDK 스팬과 API 스팬은 이름을 공유할 수 있습니다. 그 쌍은 span kind 또는 service.name으로 구분합니다. 이것은 대상이 같은 API 스팬을 두 번 받는 일과는 별개입니다.

• ClaudeDevs 발표
• Claude API의 OpenTelemetry
• Claude SDK의 OpenTelemetry

누가 켤 수 있나

대상을 추가하거나 바꾸려면 Claude Console 조직의 admin 역할이 필요합니다. developer 역할은 대상을 볼 수 있습니다. Claude Platform on AWS에서는 AWS Console로 로그인합니다. 그곳에서 대상을 누가 관리하는지는 IAM 정책이 정합니다.

엔드포인트는 protobuf를 쓰는 HTTP상 OpenTelemetry Protocol(OTLP)을, 포트 443의 HTTPS URL에서 받아야 합니다. URL은 호스트 이름을 씁니다. 문서는 자체 호스팅 컬렉터가 기본으로 포트 4318을 듣는다고 하므로, 443에서 HTTPS를 받거나 앞에 로드 밸런서나 리버스 프록시를 둡니다. 자격 증명은 헤더 값에만 넣습니다. 저장 뒤 Console은 그 값을 다시 보여 주지 않습니다. 같은 호스트에 OTLP traces endpoint URL을 설정하지 않으면 API가 /v1/traces를 붙입니다. 대상의 Test 동작은 anthropic.test 스팬을 보냅니다. 엔드포인트가 3xx 리다이렉트를 보내거나, 호스트 이름이 공개 IP가 아닌 주소로 풀리거나, 모든 전달이 24시간 동안 실패하면 API는 대상을 비활성화합니다. 원인을 고친 뒤 대상 메뉴의 Enable이 내보내기를 다시 시작하고, 내보내기는 약 1분 안에 재개됩니다.

워크스페이스 범위는 세 가지입니다. All은 Default Workspace와 나중에 만들어지는 워크스페이스를 포함해 조직의 모든 워크스페이스를 덮습니다. All except는 그 전체에서 지정한 워크스페이스를 뺍니다. Selected는 지정한 워크스페이스만 덮습니다. API는 요청이나 세션이 실행되는 워크스페이스를 덮는, 활성화된 모든 대상에 스팬을 보냅니다. Workspace Admin 역할도 가진 developer는 Selected 대상에서 그 워크스페이스를 넣거나 뺄 수 있습니다. Claude Platform on AWS에는 Workspace Admin 역할이 없습니다. 거기서는 IAM 정책이, 워크스페이스를 대상에 넣거나 빼는 주체를 정합니다.

관리자는 Admin API로도 대상을 만들 수 있습니다. Claude Platform on AWS에서 그 호출은 AWS 자격 증명으로 서명되어 https://aws-external-anthropic.{region}.api.aws 로 갑니다. 그 호출의 요청에는 해당 리전에 있는 그 계정의 워크스페이스만 넣을 수 있습니다.

API 페이지는 이 서버 측 내보내기를 Claude API와 Claude Platform on AWS에서 베타로 표시합니다. SDK 페이지는 그 둘에 Amazon Bedrock, Google Cloud, Microsoft Foundry를 더해 트레이싱을 베타로 표시합니다. 두 페이지 모두 Messages API와 Claude Managed Agents에서 동작한다고 합니다. SDK 스팬은 애플리케이션의 익스포터가 보냅니다. API가 대상으로 보내는 스팬의 전달은 at least once이며 best effort입니다. 같은 스팬이 두 번 이상 도착할 수 있고, 그 사본은 trace ID와 span ID로 제거합니다. 전달 전에 유실된 스팬은 다시 보낼 수 없습니다.

전달 이후에는 선택한 서비스가 Anthropic 밖에서, 그 서비스의 보존 기간과 접근 통제 아래 데이터를 보관합니다. API 페이지는 OpenTelemetry를 ZDR eligible로 표시하고 covered models에 대한 제외를 덧붙입니다. 이 표시는 스스로 ZDR eligible인 기능, 예를 들어 Messages API에만 적용됩니다. 같은 설명은 Claude Managed Agents는 ZDR eligible이 아니라고 합니다. 이 페이지들은 ZDR도 covered models도 정의하지 않습니다.

자체 호스팅 Managed Agents 샌드박스

Managed Agents 자체 호스팅 샌드박스에서는 샌드박스가 도구를 실행하므로, 도구 스팬은 API가 아니라 SDK에서 나옵니다. Python, TypeScript, Go SDK의 environment worker는 자신이 실행하는 도구마다, 그리고 자신이 보내는 요청마다 스팬을 내고, 작업 항목마다 하나의 anthropic.environment.work 스팬 아래에 묶습니다. 워커 프로세스에는 SDK 트레이싱이 설정되어 있어야 하고, 샌드박스는 관측 플랫폼이나 컬렉터에 닿을 수 있어야 합니다. 워커가 도구 결과를 보내면 그 요청의 API 스팬은 자신의 SDK 스팬 아래에 붙습니다. 그 워커가 Claude Platform on AWS로 보내는 요청은 API 스팬을 별도의 트레이스에 둡니다.