Claude Platform Docs
AdministraciónOpenTelemetry

Trazado de OpenTelemetry para la Claude API

Rastrea tus solicitudes a la Messages API, tus usos de herramientas y tus sesiones de Managed Agents con spans de OpenTelemetry desde el Claude SDK y la Claude API.

0:00

La Claude API y el SDK pueden trazar tus solicitudes a la Messages API, tus usos de herramientas y tus sesiones de Managed Agents con OpenTelemetry (OTel). Puedes ver estas trazas en la plataforma de observabilidad que ya tienes. Úsalas para depurar solicitudes fallidas o lentas, hacer seguimiento del gasto de tokens y de la “latency” (latencia), y crear evaluaciones a partir de tráfico real. También puedes ver cada solicitud dentro de las propias trazas de tu aplicación, vinculada al usuario o a la funcionalidad que la envió.

OpenTelemetry es un estándar neutral respecto a proveedores que la mayoría de las plataformas de observabilidad admiten. Una trace (traza) es el registro completo de una solicitud a través de tu sistema. Un span (intervalo) es un paso dentro de una traza, como una solicitud al modelo o un uso de herramienta. La API y el SDK usan atributos de las convenciones semánticas de GenAI, por lo que las plataformas que admiten estas convenciones pueden reconocer los spans sin configuración adicional.

Primeros pasos

Puedes configurar el trazado del SDK, el trazado de la API o ambos. Configura ambos para ver los spans del SDK y de la API de una solicitud en una sola traza, como en las trazas de ejemplo.

Claude Code

Deja que Claude Code configure esta funcionalidad por ti

Configura el trazado de OpenTelemetry con la Claude API y el Claude SDK

Instala el SDK y registra un tracer provider.

Agrega un destino en la Claude Console.

Consulta los spans y sus atributos.

Lo que obtienesTrazado del SDKTrazado de la APIAmbos juntos
Solicitudes a la Messages APIVista previa disponible con enlaces a la referencia de la API — presiona Tab hasta que el foco entre a la tarjeta y Escape para volver.
Solicitudes a la Sessions API
Uso de tokens (consulta Recuento de tokens)
Cada ejecución del modelo dentro de una solicitud
Turnos de Managed Agents
Herramientas de servidor, ejecutadas por la API
Herramientas de cliente, ejecutadas por el ejecutor de herramientas
Herramientas en un sandbox autoalojado
Otras solicitudes a la API, como la carga de archivos
ConfiguraciónCódigoConsoleAmbos
Permiso requeridoNingunoAdministradorAdministrador
CoberturaClientes que usan el SDKCualquier clienteCualquier cliente
Compatibilidad con plataformas en la nubeCualquieraClaude Platform
Claude Platform on AWS
Claude Platform
Claude Platform on AWS

Para Claude Code, el Agent SDK o Cowork, consulta Monitoreo de Claude Code, Observabilidad del Agent SDK o Monitoreo de actividad de Cowork.

Envía trazas a una plataforma asociada

Envía trazas a cualquier plataforma de observabilidad que acepte OTLP, incluidos estos socios:

Plataforma unificada de observabilidad y evaluación para IA.

Plataforma de observabilidad activa para agentes.

Plano de control de IA unificado para observabilidad y evaluación.

Observabilidad y seguridad impulsadas por IA.

Observabilidad creada para la era de la IA.

Observabilidad basada en código abierto.

Plataforma de observabilidad abierta totalmente administrada.

Plataforma de observabilidad para la nueva forma del software.

Plataforma de código abierto de observabilidad y evaluación de agentes.

Plataforma de ingeniería de agentes LangSmith.

Plataforma de observabilidad inteligente.

Plataforma todo en uno para crear productos exitosos.

Observabilidad de IA y general para producción.

Depura tu código defectuoso y tus agentes que se comportan mal.

Plano de control agéntico con observabilidad y gobernanza integradas.

Observa, evalúa y protege tus agentes.

Modos de contenido

Cada destino y cada cliente del SDK tiene un modo de contenido, que determina si los spans incluyen los prompts y las respuestas del modelo. Establécelo cuando agregues un destino o configures el SDK.

  • Solo metadatos (metadata_only en el SDK): El valor predeterminado. Los spans incluyen identificadores, tiempos, estado, recuentos de tokens y el texto que elijas, como los nombres y las descripciones de tus agentes y herramientas y los nombres de tus servidores MCP.
  • Contenido completo (content en el SDK): La mayor visibilidad. Los spans incluyen los prompts y las respuestas del modelo, además de todo lo que incluye Solo metadatos.

Con Contenido completo, también puedes ver por qué una ejecución falló o fue lenta, leer conversaciones completas y crear evaluaciones a partir de trazas reales. En la referencia de spans de OpenTelemetry, los atributos que contienen prompts y respuestas están etiquetados con Contenido.

Si tu organización tiene una restricción de manejo de datos de HIPAA, FERPA o K-12 con Anthropic, los destinos exportan solo metadatos sin importar su modo de contenido. Los spans del SDK no se ven afectados.

Con la retención cero de datos, puedes seguir usando Contenido completo. Para las solicitudes a la Messages API, la API mantiene el contenido exportado solo en memoria hasta que lo entrega al destino. Claude Managed Agents no cumple los requisitos de la retención cero de datos, y su retención de datos sigue siendo la misma cuando usas OpenTelemetry.

Límites de contenido

Con Contenido completo, cada span contiene hasta 0,75 MB de contenido de forma predeterminada. Este límite admite una ventana de contexto de 200k tokens de texto en inglés y se mantiene por debajo del límite de solicitud de 1 MB de muchas plataformas de observabilidad y proxies. Si seleccionas una plataforma asociada como Proveedor, la Console establece un límite que la plataforma acepta.

Cuando el contenido supera el límite, el SDK o la API lo acorta y establece anthropic.content.truncated en true. En los spans de solicitud se eliminan primero la indicación del sistema y los mensajes más antiguos, y en los spans de herramienta se eliminan bloques desde el final del resultado. Las imágenes y los documentos aparecen solo como su tipo.

Cambia el límite en estos casos:

  • Tu plataforma de observabilidad acepta payloads más grandes: Aumenta o elimina el límite para conservar completos los prompts y las respuestas largos. Una ventana de contexto completa de 1M tokens necesita unos 4 MB.
  • Tu plataforma de observabilidad o un proxy situado delante de ella rechaza las solicitudes grandes: Reduce el límite.

En el SDK, configura traces.max_content_bytes. En la Console, configura Modo de contenido en Contenido completo cuando agregues un destino y, a continuación, configura Tamaño máximo del contenido en MB en Configuración avanzada.

Trazas de ejemplo y cómo leerlas

Una solicitud a la Messages API

Bajo el span de la API de una solicitud que crea un mensajeVista previa disponible con enlaces a la referencia de la API — presiona Tab hasta que el foco entre a la tarjeta y Escape para volver., la API agrega un span por cada solicitud al modelo y un span de herramienta por cada uso de una herramienta de servidor o de una herramienta de conector MCP que ejecuta la API.

En este ejemplo, tu aplicación llama al ejecutor de herramientas, el asistente del SDK que ejecuta tus herramientas y envía sus resultados de vuelta a Claude. Cada solicitud que envía el ejecutor de herramientas tiene un span de cliente del SDK y un span de servidor de la API. Los spans aparecen en el siguiente orden:

  1. Tu aplicación inicia el span answer_question y llama dentro de él al ejecutor de herramientas de Messages (mostrado como el span anthropic.messages.tool_runner).
  2. El ejecutor de herramientas envía la primera solicitud (mostrada como el primer span de cliente anthropic.messages.create y los spans que dependen de él). En esta solicitud, la API ejecuta la herramienta de búsqueda web entre dos solicitudes al modelo.
  3. En la segunda solicitud al modelo, el modelo pide usar la herramienta personalizada get_weather, por lo que la primera solicitud termina.
  4. El ejecutor de herramientas ejecuta get_weather (mostrado como el span anthropic.custom_tool_use get_weather).
  5. El ejecutor de herramientas envía la segunda solicitud con el resultado de la herramienta (mostrada como el segundo span de cliente anthropic.messages.create y los spans que dependen de él).
  6. En la segunda solicitud, el modelo da la respuesta final.
answer_question
tu código
Inicia la traza.anthropic.messages.tool_runnerSDKComienza con su padre y dura la mayor parte de él.anthropic.messages.createCLIENTSDKComienza con su padre y dura aproximadamente la mitad de él.
pide usar una herramienta
anthropic.messages.createSERVERAPIComienza con su padre y termina con su padre.anthropic.model_requestAPIComienza con su padre y dura aproximadamente un tercio de él.anthropic.tool_use web_searchAPIComienza después del span anterior y dura una parte corta de su padre.
la API ejecuta la herramienta
anthropic.model_requestAPIComienza después del span anterior y termina con su padre.
anthropic.custom_tool_use get_weatherSDKComienza después del span anterior y dura una parte corta de su padre.
ejecuta tu herramienta
anthropic.messages.createCLIENTSDKComienza después del span anterior y termina con su padre.
respuesta final
anthropic.messages.createSERVERAPIComienza con su padre y termina con su padre.anthropic.model_requestAPIComienza con su padre y termina con su padre.

El SDK de tu aplicación emite el span anthropic.messages.tool_runner, el span anthropic.custom_tool_use y el span de cliente de cada solicitud. Para obtener estos spans, configura el trazado del SDK.

Cada solicitud tiene su uso de tokens en varios de sus spans. Para contar cada token una sola vez, consulta Recuento de tokens.

Con Contenido completo, el span de servidor anthropic.messages.create contiene el prompt y la respuesta. La indicación del sistema está en gen_ai.system_instructions, los mensajes de la solicitud en gen_ai.input.messages y la respuesta en gen_ai.output.messages.

Para cada span y sus atributos, consulta la referencia de spans de OpenTelemetry.

Una sesión de Managed Agents

Una sesión tiene un span por cada solicitud a la Sessions API y un span de turno por cada turno del agente. Un turno iniciado por una solicitud es hijo del span de esa solicitud. Un turno contiene un span por cada solicitud al modelo y por cada herramienta que ejecuta la API, excepto en los casos enumerados en la referencia de spans de herramientas. También contiene un span por cada evaluación de resultado.

Este ejemplo sigue una solicitud de chat, en la que tu aplicación envía un mensaje a una sesión y ejecuta una herramienta personalizada. La traza tiene spans tanto de tu aplicación como de la API, en el siguiente orden:

  1. Tu aplicación recibe una solicitud POST /chat de un usuario.
  2. Tu aplicación inicia el ejecutor de herramientas de sesión del SDK, que lista y hace streaming de los eventos de la sesión (se muestran como los spans anthropic.sessions.events.stream y anthropic.sessions.events.list).
  3. Tu aplicación envía el mensaje del usuario a la sesión llamando a sessions.events.send.
  4. Comienza un turno que incluye solicitudes al modelo, un uso de la herramienta bash y un turno en otro hilo (se muestran como el primer span anthropic.session.turn y los spans debajo de él).
  5. El modelo pide usar la herramienta personalizada list_issues, por lo que el turno termina con el motivo de detención requires_action.
  6. El ejecutor de herramientas de sesión ejecuta list_issues (se muestra como el span anthropic.custom_tool_use list_issues) y envía su resultado llamando a sessions.events.send.
  7. Comienza un segundo turno con el resultado de la herramienta (se muestra como el último span anthropic.session.turn).
POST /chatSERVER
tu código
Inicia la traza.anthropic.sessions.events.streamCLIENTSDKEmpieza con su padre y termina con su padre.anthropic.sessions.events.streamSERVERAPIEmpieza con su padre y termina con su padre.anthropic.sessions.events.listCLIENTSDKEmpieza mientras se ejecuta el span anterior y dura una parte corta de su padre.anthropic.sessions.events.listSERVERAPIEmpieza al principio de su padre y dura la mayor parte de él.anthropic.sessions.events.sendCLIENTSDKEmpieza después del span anterior y dura una parte corta de su padre.
envía un mensaje del usuario
anthropic.sessions.events.sendSERVERAPIEmpieza al principio de su padre y dura la mayor parte de él.anthropic.session.turnAPIEmpieza en la última parte de su padre y continúa después del final de su padre.
motivo de detención requires_action
anthropic.model_requestAPIEmpieza al principio de su padre y dura una parte corta de él.anthropic.tool_use bashAPIEmpieza después del span anterior y dura una parte corta de su padre.gen_ai.tool.name = bashanthropic.session.turnAPIEmpieza después del span anterior y dura una parte corta de su padre.
en otro hilo
anthropic.model_requestAPIEmpieza al principio de su padre y dura la mayor parte de él.
anthropic.model_requestAPIEmpieza después del span anterior y termina con su padre.
anthropic.custom_tool_use list_issuesSDKEmpieza después del span anterior y dura una parte corta de su padre.
ejecuta tu herramienta
list_issues
tu código
Empieza al principio de su padre y dura la mayor parte de él.
anthropic.sessions.events.sendCLIENTSDKEmpieza después del span anterior y dura una parte corta de su padre.
envía el resultado de la herramienta
anthropic.sessions.events.sendSERVERAPIEmpieza al principio de su padre y dura la mayor parte de él.anthropic.session.turnAPIEmpieza en la última parte de su padre y continúa después del final de su padre.anthropic.model_requestAPIEmpieza al principio de su padre y dura la mayor parte de él.

El SDK en tu aplicación emite el span anthropic.custom_tool_use y el span de cliente de cada solicitud. Para obtener estos spans, configura el trazado del SDK.

Los spans de una sesión pueden estar en varias trazas, por ejemplo cuando envías una solicitud posterior desde una nueva traza raíz. Con multiagente activado, una sesión también puede tener varios hilos. Para encontrar los spans que necesitas, agrúpalos por un ID.

  • Un hilo: Agrupa los spans por gen_ai.conversation.id, que contiene el ID del hilo de la sesión. Ordénalos por hora de inicio para leer el hilo como una transcripción.
  • Una sesión completa, con todos sus hilos: Agrupa los spans por anthropic.session.id, a través de las trazas.

Con Contenido completo, puedes leer el contenido de una sesión a partir de sus spans.

  • Para leer el contenido de un turno, usa su span de turno. La indicación del sistema está en gen_ai.system_instructions en el primer span de turno de un hilo, la entrada en gen_ai.input.messages (tus mensajes y resultados de herramientas, eventos system.message y mensajes de otros hilos), y la salida en gen_ai.output.messages (los mensajes del agente, usos de herramientas y resultados de herramientas).
  • Para ver los argumentos y el resultado de un uso de herramienta, lee su span de herramienta. Los argumentos están en gen_ai.tool.call.arguments, y el resultado está en anthropic.tool_result.content.

Para cada span y sus atributos, consulta la referencia de spans de OpenTelemetry.

Recuento de tokens

Para contar cada token una sola vez, suma los spans de una sola fuente por cada solicitud. Cuando una solicitud a la Messages API tiene tanto un span del SDK como un span de la API, suma sus spans de la API. Ambos se llaman anthropic.messages.create, así que distínguelos por su tipo: el span del SDK es CLIENT y su hijo, el span de la API, es SERVER.

Para cada fuente, suma solo los siguientes spans, porque algunos atributos de uso se repiten en más de un nivel de los spans de la API:

  • Spans del SDK: Suma los spans anthropic.messages.create. Si una solicitud tiene compactaciones, suma también los atributos anthropic.usage.compaction.input_tokens y anthropic.usage.compaction.output_tokens del span, porque los atributos gen_ai.usage.* no incluyen los tokens de compactación. Si un modelo de respaldo atendió una solicitud, su span tiene el uso solo del modelo que atendió la respuesta.
  • Spans de la API de una solicitud a la Messages API: Suma los spans anthropic.messages.create o sus spans anthropic.model_request, no ambos. Si una solicitud tiene compactaciones, suma también sus spans anthropic.compaction. No sumes además los atributos anthropic.usage.compaction.* del span anthropic.messages.create, porque contienen los mismos tokens.
  • Spans de la API de una sesión de Managed Agents: Suma los spans anthropic.model_request y anthropic.session.outcome_evaluation.

Los spans pueden llegar más de una vez, por ejemplo cuando se reintenta una entrega. Si tu plataforma de observabilidad no elimina duplicados, cuenta cada span una sola vez por su ID de traza y su ID de span.

gen_ai.usage.input_tokens ya incluye los tokens leídos y escritos en la caché de prompts, así que no le sumes los atributos de caché. Para todos los atributos de uso, consulta Uso de tokens.

Disponibilidad

OpenTelemetry está en beta en todos los modelos.

Compatibilidad con la API

EstadoBeta
Plataformas en la nube
  • Todas las plataformas compatibles
EstadoBeta
Plataformas en la nube
  • Todas las plataformas compatibles

¿Te resultó útil esta página?