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.
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 SDKInstala el SDK y registra un tracer provider.
Agrega un destino en la Claude Console.
Consulta los spans y sus atributos.
| 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ón | Código | Console | Ambos |
| Permiso requerido | Ninguno | Administrador | Administrador |
| Cobertura | Cualquier cliente | Cualquier cliente | |
| Compatibilidad con plataformas en la nube | Cualquiera | Claude Platform | Claude Platform |
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_onlyen 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 (
contenten 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:
- Tu aplicación inicia el span
answer_questiony llama dentro de él al ejecutor de herramientas de Messages (mostrado como el spananthropic.messages.tool_runner). - El ejecutor de herramientas envía la primera solicitud (mostrada como el primer span de cliente
anthropic.messages.createy los spans que dependen de él). En esta solicitud, la API ejecuta la herramienta de búsqueda web entre dos solicitudes al modelo. - En la segunda solicitud al modelo, el modelo pide usar la herramienta personalizada
get_weather, por lo que la primera solicitud termina. - El ejecutor de herramientas ejecuta
get_weather(mostrado como el spananthropic.custom_tool_use get_weather). - El ejecutor de herramientas envía la segunda solicitud con el resultado de la herramienta (mostrada como el segundo span de cliente
anthropic.messages.createy los spans que dependen de él). - En la segunda solicitud, el modelo da la respuesta final.
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:
- Tu aplicación recibe una solicitud
POST /chatde un usuario. - 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.streamyanthropic.sessions.events.list). - Tu aplicación envía el mensaje del usuario a la sesión llamando a
sessions.events.send. - Comienza un turno que incluye solicitudes al modelo, un uso de la herramienta
bashy un turno en otro hilo (se muestran como el primer spananthropic.session.turny los spans debajo de él). - El modelo pide usar la herramienta personalizada
list_issues, por lo que el turno termina con el motivo de detenciónrequires_action. - El ejecutor de herramientas de sesión ejecuta
list_issues(se muestra como el spananthropic.custom_tool_use list_issues) y envía su resultado llamando asessions.events.send. - Comienza un segundo turno con el resultado de la herramienta (se muestra como el último span
anthropic.session.turn).
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_instructionsen el primer span de turno de un hilo, la entrada engen_ai.input.messages(tus mensajes y resultados de herramientas, eventossystem.messagey mensajes de otros hilos), y la salida engen_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á enanthropic.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 atributosanthropic.usage.compaction.input_tokensyanthropic.usage.compaction.output_tokensdel span, porque los atributosgen_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.createo sus spansanthropic.model_request, no ambos. Si una solicitud tiene compactaciones, suma también sus spansanthropic.compaction. No sumes además los atributosanthropic.usage.compaction.*del spananthropic.messages.create, porque contienen los mismos tokens. - Spans de la API de una sesión de Managed Agents: Suma los spans
anthropic.model_requestyanthropic.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
¿Te resultó útil esta página?