Usa OpenTelemetry con la Claude API

Con OpenTelemetry, la Claude API puede emitir un span (intervalo) por cada solicitud al modelo y por cada uso de herramienta que ejecuta. Puedes ver estos spans en tu plataforma de observabilidad sin cambiar tu código.

La API emite spans para tus solicitudes a la Messages API y tus sesiones de Managed Agents. Para recibirlos, agrega un destino en la Claude Console. Un destino le indica a la API el endpoint OTLP de tu plataforma de observabilidad y cómo autenticarse con él.

Qué necesitas

• El rol de administrador en una organización de la Claude Console, para agregar y cambiar destinos. Con el rol de desarrollador, puedes verlos. Si tu organización está en Claude Platform on AWS, inicia sesión en la Console a través de la AWS Console, como se describe en Iniciar sesión.
• Un endpoint OTLP/HTTP que acepte codificación protobuf en una URL HTTPS en el puerto 443. Si ejecutas tu propio OpenTelemetry Collector, su receptor OTLP/HTTP escucha en el puerto 4318 de forma predeterminada. Configura el receptor para que acepte HTTPS en el puerto 443, o coloca un balanceador de carga o un proxy inverso delante del Collector.
• Credenciales para el endpoint, como una clave de API.

1. Agrega un destino

1. En la Console, abre la página de configuración de OpenTelemetry de tu organización y haz clic en Add destination.

2. Configura el destino:

   Campo	Qué ingresar
   Provider	Tu plataforma de observabilidad, o Custom si no aparece en la lista. Si eliges una plataforma de la lista, la Console te pide sus datos, como una clave de API, en lugar de OTLP endpoint URL, Request headers y OTLP traces endpoint URL.
   Name	Opcional. Por ejemplo, "Plataforma de observabilidad de Acme".
   OTLP endpoint URL	La URL HTTPS base del endpoint OTLP/HTTP de tu plataforma de observabilidad, con un nombre de host, no una dirección IP. Puede tener un prefijo de ruta, por ejemplo https://gateway.example.com/otlp. No agregues /v1/traces, porque la API lo agrega. Si estableces una OTLP traces endpoint URL, la API usa esa URL en su lugar.
   Request headers	Los encabezados que la API envía con cada solicitud, por ejemplo el encabezado de clave de API de tu plataforma de observabilidad. Coloca las credenciales solo en los valores de los encabezados. Después de guardar, la Console no vuelve a mostrar los valores.
   Content mode	Metadata only o Full content. Consulta en qué se diferencian los modos de contenido.
   Workspaces	Los espacios de trabajo cuyos spans recibe el destino: All, Selected o All except. Consulta Elige los espacios de trabajo de un destino.
   OTLP traces endpoint URL	Opcional, en Advanced settings. La URL completa del endpoint de trazas de tu plataforma de observabilidad, por ejemplo https://gateway.example.com/custom/traces. Establécela cuando la plataforma reciba trazas en una URL distinta de la OTLP endpoint URL más /v1/traces. Debe tener el mismo host que la OTLP endpoint URL.
   Maximum content size in MB	Opcional, en Advanced settings cuando el modo de contenido es Full content. La cantidad máxima de contenido que la API envía en cada span. La Console la completa según el Provider que elijas. Cámbiala para que se ajuste a lo que acepta tu plataforma de observabilidad. Déjalo vacío para enviar tanto como la API permita. Consulta Límites de contenido.

3. Haz clic en Add destination para guardar.

4. Haz clic en Test en el menú More actions del destino. Verás un mensaje que indica que el span de prueba se entregó a tu colector, o cómo falló la entrega (consulta Errores de entrega).

5. Comprueba que el span anthropic.test haya llegado a tu plataforma de observabilidad.

Admin API y CLI

También puedes agregar un destino con la Admin API en lugar de la Console. Inicia sesión en la CLI como administrador, o usa una clave de Admin API en ANTHROPIC_API_KEY. En Claude Platform on AWS, envía las solicitudes a https://aws-external-anthropic.{region}.api.aws en su lugar, firmadas con tus credenciales de AWS como en Realizar solicitudes. Allí, tu política de IAM decide quién puede administrar destinos. Una solicitud solo puede incluir los espacios de trabajo de tu cuenta de AWS en esa región.

client = anthropic.Anthropic()

destination = client.beta.organization.telemetry_destinations.create(
    endpoint_url="https://gateway.example.com/otlp",
    headers={"authorization": "Bearer YOUR_OBSERVABILITY_API_KEY"},
    traces={"content_mode": "metadata_only"},
    workspaces={"type": "all"},
)

print(destination.id)

Una solicitud de creación acepta la configuración de la Console excepto Provider, así que ingresa tú mismo la URL del endpoint y los encabezados de tu plataforma de observabilidad. Establece traces.max_content_bytes, en bytes, para ajustarlo a lo que acepta tu plataforma de observabilidad (consulta Límites de contenido). Para listar, cambiar o eliminar destinos, o para agregar o quitar un espacio de trabajo, usa los demás métodos de la API de destinos de telemetría.

2. Elige los espacios de trabajo de un destino

Un destino recibe los spans de los espacios de trabajo que abarca. Elígelos cuando agregues el destino. En Workspaces, selecciona una de las siguientes opciones:

• All: Todos los espacios de trabajo de la organización, incluido el Default Workspace y los espacios de trabajo que se creen más adelante.
• Selected: Solo los espacios de trabajo que selecciones.
• All except: Como All, pero sin los espacios de trabajo que selecciones.

Para Selected o All except, selecciona los espacios de trabajo en el cuadro de búsqueda que aparece debajo de las opciones. Para cambiar más adelante los espacios de trabajo de un destino, abre su menú More actions en la página de configuración de OpenTelemetry mientras el filtro Workspace muestra All. Haz clic en Edit y luego elige otra opción de Workspaces o cambia los espacios de trabajo en el cuadro de búsqueda.

Si tienes el rol de desarrollador en la organización y el rol de Workspace Admin en un espacio de trabajo, puedes agregar ese espacio de trabajo a un destino Selected o quitarlo de él. Configura el filtro Workspace en ese espacio de trabajo y, luego, abre el menú More actions del destino. En Claude Platform on AWS, la Console no tiene el rol de Workspace Admin. Allí, es tu política de IAM la que decide quién puede agregar un espacio de trabajo a un destino o quitarlo de él.

La API envía los spans a cada destino habilitado que cubra el espacio de trabajo en el que se ejecuta la solicitud o la sesión.

3. Comprueba que llegan los spans

1. En la Console, selecciona un espacio de trabajo que el destino cubra y envía una solicitud a la Messages API en el playground. También puedes enviar una solicitud a la Messages API desde tu aplicación o iniciar una sesión de Managed Agents en ese espacio de trabajo. Para iniciar una sesión, puedes seguir los pasos de Primeros pasos con Claude Managed Agents.
2. En la Console, en la página de configuración de OpenTelemetry, comprueba que la columna Delivery del destino muestre Healthy. Esto puede tardar alrededor de un minuto.
3. En tu plataforma de observabilidad, filtra por service.name = claude-platform para encontrar los spans de la solicitud.

Si la columna muestra Failing, mantén el puntero sobre ella para ver el último error. Para encontrar la causa probable, consulta Errores de entrega.

4. Conecta los spans de la API con tus propias trazas

De forma predeterminada, los spans de la API de una solicitud a la Messages API o de una sesión de Managed Agents están en sus propias trazas. Conéctalos con las trazas de tu aplicación para que queden anidados bajo tus propios spans.

La API lee el contexto de traza de cada solicitud desde el encabezado traceparent de W3C. Si el indicador de muestreo del encabezado está desactivado, la API no emite el span de la solicitud ni los spans que dependen de él. Claude Platform on AWS aún no admite este encabezado. Los spans de las solicitudes que le envías siempre inician sus propias trazas, incluso cuando el indicador de muestreo está desactivado.

from opentelemetry import trace

tracer = trace.get_tracer("my-service")

with tracer.start_as_current_span("summarize_issues"):
    client.beta.sessions.events.send(
        session.id,
        events=[
            {
                "type": "user.message",
                "content": [{"type": "text", "text": "Summarize the open issues"}],
            },
        ],
    )

import os
import httpx2
from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator

headers = {
    "x-api-key": os.environ["ANTHROPIC_API_KEY"],
    "anthropic-version": "2023-06-01",
    "anthropic-beta": "managed-agents-2026-04-01",
    "content-type": "application/json",
}
# Copia el contexto de traza del span activo en los encabezados de la solicitud.
TraceContextTextMapPropagator().inject(headers)

httpx2.post(
    f"https://api.anthropic.com/v1/sessions/{os.environ['SESSION_ID']}/events",
    headers=headers,
    json={
        "events": [
            {
                "type": "user.message",
                "content": [{"type": "text", "text": "Summarize the open issues"}],
            },
        ],
    },
)

La Messages API también transmite la traza a tu servidor MCP cuando lo conectas con el conector MCP, para que pueda colocar sus propios spans bajo los spans de la API. Cada solicitud y notificación que la API envía a tu servidor MCP tiene un traceparent de W3C en params._meta. En una solicitud tools/call, este hace referencia al span anthropic.mcp_tool_use de ese uso de herramientas. En los demás mensajes, hace referencia al span anthropic.messages.create. Para una solicitud que la API no rastrea, como una cuyo encabezado traceparent tiene el indicador de muestreo desactivado, la API no envía ningún traceparent.

Próximos pasos

Entrega y estado

Las siguientes reglas se aplican a los spans que la API envía a tus destinos.

• Al menos una vez: Un destino puede recibir el mismo span más de una vez. Para eliminar duplicados, usa el ID de traza y el ID de span.
• Mejor esfuerzo: Un span puede perderse antes de la entrega. La API no puede volver a enviar un span perdido.
• Compresión: La API comprime con gzip la primera solicitud de cada entrega y establece el encabezado Content-Encoding: gzip. Si tu endpoint responde a esa solicitud con una respuesta 400 o 415, la API vuelve a enviar de inmediato los mismos spans sin compresión.
• Reintentos: La API vuelve a intentar una entrega más tarde, un número limitado de veces, después de un tiempo de espera agotado, un fallo de conexión, TLS o DNS, o una respuesta 408, 429 o 5xx. No reintenta otros fallos.
• Tiempos de espera: Para cada solicitud, tu endpoint debe completar el handshake TLS en 5 segundos y enviar los encabezados de respuesta en 5 segundos. Cada entrega agota su tiempo de espera después de 10 segundos en total, incluido el reenvío sin compresión.
• User agent: Cada solicitud tiene el encabezado User-Agent: Claude-Platform.

La columna Delivery muestra el estado de cada destino. El estado puede tener hasta un minuto de retraso.

La API deshabilita un destino cuando:

• El endpoint envía una redirección 3xx.
• El nombre de host del endpoint se resuelve en una dirección IP que no es pública.
• Todas las entregas fallan durante 24 horas.

La API no envía spans a un destino deshabilitado. Para reanudar la exportación, corrige la causa. Luego, con el filtro Workspace de la página de configuración de OpenTelemetry mostrando All, haz clic en Enable en el menú More actions del destino. La exportación se reanuda en aproximadamente un minuto.

Para cambiar un destino, abre su menú More actions mientras el filtro Workspace muestra All. Luego haz clic en Edit, Disable, Enable o Delete. Si cambias el host de la OTLP endpoint URL, vuelve a ingresar los valores de los encabezados. Si el destino tiene una OTLP traces endpoint URL, asígnale el mismo host nuevo o déjala vacía.

Límites

Solución de problemas

Errores de entrega

Cuando una entrega falla, la columna Delivery muestra Failing. Mantén el puntero sobre este estado para ver el error y, a continuación, busca la causa probable:

Compatibility