AdministraciónOpenTelemetry

OpenTelemetry para la Claude API

Copy page



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. 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. Para las solicitudes a Claude Platform on AWS, los spans de la API están en sus propias trazas.

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:

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.

• Metadata only (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.
• Full content (content en el SDK): La mayor visibilidad. Los spans incluyen los prompts y las respuestas del modelo, además de todo lo que incluye Metadata only.

Con Full content, 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 Content.

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 Full content. 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 Full content, cada span contiene hasta 0,75 MB de contenido de forma predeterminada. Este límite admite una ventana de contexto de 200k tokens con texto en inglés, sin superar el límite de solicitud de 1 MB de muchas plataformas de observabilidad y proxies. Si eliges una plataforma de socios como Provider, la Console establece un límite que acepta la plataforma.

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 Content mode en Full content cuando agregues un destino y, a continuación, configura Maximum content size in MB en Advanced settings.

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 mensaje, 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 tool runner, el asistente del SDK que ejecuta tus herramientas y envía sus resultados de vuelta a Claude. Cada solicitud que envía el tool runner 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 tool runner de Messages (mostrado como el span anthropic.messages.tool_runner).
2. El tool runner 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 tool runner ejecuta get_weather (mostrado como el span anthropic.custom_tool_use get_weather).
5. El tool runner 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.

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 Full content, 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).

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.