Usa OpenTelemetry con el Claude SDK

Con OpenTelemetry, el Claude SDK puede emitir un span (intervalo) por cada solicitud que envía y por cada uso de herramienta que ejecuta el tool runner. Puedes ver estos spans en tu plataforma de observabilidad, anidados en tus propias trazas.

El SDK emite spans en tu aplicación. El exportador de OpenTelemetry de tu aplicación los envía a tu plataforma de observabilidad.

1. Instala el SDK

Instala o actualiza a la versión más reciente del SDK de Claude:

pip install --upgrade anthropic

pip install opentelemetry-sdk

2. Registra un tracer provider

Un tracer provider (proveedor de trazadores) es el objeto de OpenTelemetry que crea spans y los pasa a tu exportador. El SDK usa el tracer provider que registra tu aplicación, por lo que tus llamadas al SDK no cambian. Regístralo antes de la primera llamada que quieras trazar.

El siguiente ejemplo registra un tracer provider que imprime cada span en la consola y luego hace una llamada. Úsalo para ver spans antes de conectar una plataforma de observabilidad:

from anthropic import Anthropic
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor

# Registra un proveedor de trazas (tracer provider) que imprime cada span en la consola.
provider = TracerProvider()
provider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))
trace.set_tracer_provider(provider)

client = Anthropic()

message = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message.content)

La consola muestra un span anthropic.messages.create.

3. Envía spans a tu plataforma de observabilidad

Reemplaza el exportador de consola por un exportador OTLP que apunte a tu plataforma de observabilidad. Para la configuración en tu lenguaje, consulta la documentación de OpenTelemetry sobre exportadores de Python, exportadores de TypeScript, exportadores de .NET, exportadores de Go, configuración del SDK de Java, exportadores de PHP, o exportadores de Ruby.

4. Configura el SDK

Usa las siguientes opciones para decidir qué se incluye en tus spans y a dónde se envían. Puedes establecer una opción en tu código o, si tiene una, con la variable de entorno que aparece bajo su nombre.

El siguiente ejemplo muestra cómo usar cada opción:

# Usa un proveedor de trazas específico y registra el contenido.
# Configurar open_telemetry anula todas las variables de entorno ANTHROPIC_OPEN_TELEMETRY*.
client = Anthropic(
    open_telemetry={"tracer_provider": provider, "traces": {"content_mode": "content"}}
)

# Desactiva los spans para un cliente.
quiet_client = Anthropic(open_telemetry=False)

# Establece un ID de conversación con with_options(), que devuelve una copia del cliente.
# with_options() reemplaza toda la opción, así que parte de client.open_telemetry.
message = client.with_options(
    open_telemetry={**client.open_telemetry, "conversation_id": "conv_42"}
).messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)

Próximos pasos

Trazado de un stream

El span anthropic.messages.create de un stream termina cuando tu código ha leído todo el stream o lo ha cerrado, así que cierra cualquier stream que dejes de leer antes de tiempo. En el modo de contenido, el span incluye la respuesta del modelo solo cuando lees el stream con messages.stream().

Los spans que inicias mientras lees un stream son hermanos del span del SDK, no sus hijos. Para agruparlos con la solicitud, inicia tu propio span que abarque tanto la llamada como el bucle de lectura.

Trazado de un sandbox autoalojado de Managed Agents

En un sandbox autoalojado de Managed Agents, tu sandbox ejecuta las herramientas, por lo que los spans de herramientas provienen del SDK en lugar de la API. El worker de entorno de los SDK de Python, TypeScript y Go emite un span por cada herramienta que ejecuta y por cada solicitud que envía. Los agrupa bajo un span anthropic.environment.work por cada elemento de trabajo.

Para obtener estos spans:

1. En el proceso que ejecuta el worker, configura el rastreo del SDK como en los pasos 1 a 4.
2. Permite el tráfico de red desde el sandbox hacia tu plataforma de observabilidad o tu OpenTelemetry Collector.

Cuando el worker envía un resultado de herramienta, el span de la API de esa solicitud queda anidado bajo su span del SDK. Para las solicitudes que el worker envía a Claude Platform on AWS, los spans de la API están en sus propias trazas.

Contexto de traza y baggage

Con cada solicitud, el SDK usa el propagador de tu aplicación para enviar el contexto de traza a la API en encabezados como traceparent. Si ese propagador también escribe baggage, el SDK envía además tu baggage. Para enviar el contexto de traza sin baggage, registra solo el propagador de contexto de traza W3C.

Para que el SDK no envíe estos encabezados, por ejemplo cuando la instrumentación de tu cliente HTTP ya los envía, desactiva la propagación del SDK:

client = Anthropic(open_telemetry={"propagation": False})

Mientras el SDK llama a una herramienta MCP, el span de herramienta del SDK es el span actual. Algunas bibliotecas cliente de MCP envían el contexto de traza al servidor MCP en _meta, de modo que un servidor que lo lea puede agregar sus spans a tu traza bajo ese span de herramienta. Lo hacen el paquete mcp de Python a partir de la versión 2.0 y el paquete ModelContextProtocol de C#. Los SDK de MCP para TypeScript, Go, Java, Ruby y PHP no lo hacen por sí solos.

Solución de problemas

Compatibility