Utiliser OpenTelemetry avec l'API Claude

Avec OpenTelemetry, l'API Claude peut émettre un span (segment) pour chaque requête au modèle et chaque utilisation d'outil qu'elle exécute. Vous pouvez consulter ces spans dans votre plateforme d'observabilité sans modifier votre code.

L'API émet des spans pour vos requêtes à l'API Messages et vos sessions Managed Agents. Pour les recevoir, ajoutez une destination (destination) dans la Claude Console. Une destination indique à l'API le point de terminaison OTLP de votre plateforme d'observabilité et la manière de s'y authentifier.

Ce dont vous avez besoin

• Le rôle d'administrateur dans une organisation de la Claude Console, pour ajouter et modifier des destinations. Avec le rôle de développeur, vous pouvez les consulter. Si votre organisation est sur Claude Platform on AWS, connectez-vous à la Console via la console AWS, comme le décrit Connexion.
• Un point de terminaison OTLP/HTTP qui accepte l'encodage protobuf sur une URL HTTPS sur le port 443. Si vous exécutez votre propre OpenTelemetry Collector, son récepteur OTLP/HTTP écoute par défaut sur le port 4318. Configurez le récepteur pour accepter HTTPS sur le port 443, ou placez un équilibreur de charge ou un proxy inverse devant le Collector.
• Des identifiants pour le point de terminaison, comme une clé API.

1. Ajouter une destination

1. Dans la Console, ouvrez la page des paramètres OpenTelemetry de votre organisation et cliquez sur Add destination.

2. Configurez la destination :

   Champ	Ce qu'il faut saisir
   Provider	Votre plateforme d'observabilité, ou Custom si elle ne figure pas dans la liste. Si vous choisissez une plateforme de la liste, la Console vous demande ses informations, comme une clé API, à la place de OTLP endpoint URL, Request headers et OTLP traces endpoint URL.
   Name	Facultatif. Par exemple, « Plateforme d'observabilité d'Acme ».
   OTLP endpoint URL	L'URL HTTPS de base du point de terminaison OTLP/HTTP de votre plateforme d'observabilité, avec un nom d'hôte, et non une adresse IP. Elle peut comporter un préfixe de chemin, par exemple https://gateway.example.com/otlp. N'ajoutez pas /v1/traces, car l'API l'ajoute. Si vous définissez une OTLP traces endpoint URL, l'API utilise cette URL à la place.
   Request headers	Les en-têtes que l'API envoie avec chaque requête, par exemple l'en-tête de clé API de votre plateforme d'observabilité. Placez les identifiants uniquement dans les valeurs des en-têtes. Après l'enregistrement, la Console n'affiche plus les valeurs.
   Content mode	Metadata only ou Full content. Consultez en quoi les modes de contenu diffèrent.
   Workspaces	Les espaces de travail dont la destination reçoit les spans : All, Selected ou All except. Consultez Choisir les espaces de travail d'une destination.
   OTLP traces endpoint URL	Facultatif, sous Advanced settings. L'URL complète du point de terminaison des traces de votre plateforme d'observabilité, par exemple https://gateway.example.com/custom/traces. Définissez-la lorsque la plateforme reçoit les traces à une URL autre que l'URL du point de terminaison OTLP suivie de /v1/traces. Elle doit avoir le même hôte que l'URL du point de terminaison OTLP.
   Maximum content size in MB	Facultatif, sous Advanced settings lorsque le mode de contenu est Full content. La quantité maximale de contenu que l'API envoie dans chaque span. La Console la renseigne en fonction du Provider que vous choisissez. Modifiez-la pour l'adapter à ce que votre plateforme d'observabilité accepte. Laissez-le vide pour envoyer autant de contenu que l'API le permet. Consultez Limites de contenu.

3. Cliquez sur Add destination pour enregistrer.

4. Cliquez sur Test dans le menu More actions de la destination. Un message indique si le span de test a été livré à votre collecteur ou pourquoi la livraison a échoué (voir Erreurs de livraison).

5. Vérifiez que le span anthropic.test est bien arrivé dans votre plateforme d'observabilité.

Admin API et CLI

Vous pouvez également ajouter une destination via l'Admin API au lieu de la Console. Connectez-vous à la CLI en tant qu'administrateur, ou utilisez une clé Admin API dans ANTHROPIC_API_KEY. Sur Claude Platform on AWS, envoyez plutôt les requêtes à https://aws-external-anthropic.{region}.api.aws, signées avec vos identifiants AWS comme dans Effectuer des requêtes. Dans ce cas, votre politique IAM détermine qui peut gérer les destinations. Une requête ne peut inclure que les espaces de travail de votre compte AWS dans cette région.

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)

Une requête de création accepte les paramètres de la Console à l'exception de Provider ; saisissez donc vous-même l'URL du point de terminaison et les en-têtes de votre plateforme d'observabilité. Définissez traces.max_content_bytes, en octets, pour l'adapter à ce que votre plateforme d'observabilité accepte (consultez Limites de contenu). Pour lister, modifier ou supprimer des destinations, ou pour ajouter ou retirer un espace de travail, utilisez les autres méthodes de l'API des destinations de télémétrie.

2. Choisir les espaces de travail d'une destination

Une destination reçoit les spans des espaces de travail qu'elle couvre. Choisissez-les lorsque vous ajoutez la destination. Pour Workspaces, sélectionnez l'une des options suivantes :

• All : tous les espaces de travail de l'organisation, y compris le Default Workspace et les espaces de travail créés ultérieurement.
• Selected : uniquement les espaces de travail que vous sélectionnez.
• All except : comme All, mais sans les espaces de travail que vous sélectionnez.

Pour Selected ou All except, sélectionnez les espaces de travail dans la zone de recherche qui apparaît sous les options. Pour modifier ultérieurement les espaces de travail d'une destination, ouvrez son menu More actions sur la page des paramètres OpenTelemetry pendant que le filtre Workspace affiche All. Cliquez sur Edit, puis choisissez une autre option Workspaces ou modifiez les espaces de travail dans la zone de recherche.

Si vous avez le rôle de développeur dans l'organisation et le rôle Workspace Admin dans un espace de travail, vous pouvez ajouter cet espace de travail à une destination Selected, ou l'en retirer. Réglez le filtre Workspace sur cet espace de travail, puis ouvrez le menu More actions de la destination. Sur Claude Platform on AWS, la Console ne propose pas de rôle Workspace Admin. Dans ce cas, c'est votre politique IAM qui détermine qui peut ajouter un espace de travail à une destination ou l'en retirer.

L'API envoie les spans à chaque destination activée qui couvre l'espace de travail dans lequel la requête ou la session s'exécute.

3. Vérifier que les spans arrivent

1. Dans la Console, sélectionnez un espace de travail couvert par la destination et envoyez une requête à l'API Messages dans le playground. Vous pouvez également envoyer une requête à l'API Messages depuis votre application ou démarrer une session Managed Agents dans cet espace de travail. Pour démarrer une session, vous pouvez suivre les étapes de Premiers pas avec Claude Managed Agents.
2. Dans la Console, sur la page des paramètres OpenTelemetry, vérifiez que la colonne Delivery de la destination affiche Healthy. Cela peut prendre environ une minute.
3. Dans votre plateforme d'observabilité, filtrez sur service.name = claude-platform pour trouver les spans de la requête.

Si la colonne affiche Failing, maintenez le pointeur dessus pour voir la dernière erreur. Pour trouver la cause probable, consultez Erreurs de livraison.

4. Connecter les spans de l'API à vos propres traces

Par défaut, les spans de l'API d'une requête à l'API Messages ou d'une session Managed Agents se trouvent dans leurs propres traces. Connectez-les aux traces de votre application, afin qu'ils s'imbriquent sous vos propres spans.

L'API lit le contexte de trace de chaque requête à partir de l'en-tête traceparent W3C. Si l'indicateur d'échantillonnage de l'en-tête est désactivé, l'API n'émet pas le span de la requête ni les spans situés sous celui-ci. Claude Platform on AWS ne prend pas encore en charge cet en-tête. Les spans des requêtes que vous lui envoyez démarrent toujours leurs propres traces, même lorsque l'indicateur d'échantillonnage est désactivé.

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",
}
# Copie le contexte de trace du span actif dans les en-têtes de la requête.
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"}],
            },
        ],
    },
)

L'API Messages transmet également la trace à votre serveur MCP lorsque vous le connectez avec le connecteur MCP, afin qu'il puisse placer ses propres spans sous les spans de l'API. Chaque requête et notification que l'API envoie à votre serveur MCP comporte un traceparent W3C dans params._meta. Dans une requête tools/call, il fait référence au span anthropic.mcp_tool_use de cette utilisation d'outil. Dans les autres messages, il fait référence au span anthropic.messages.create. Pour une requête que l'API ne trace pas, comme une requête dont l'en-tête traceparent a l'indicateur d'échantillonnage désactivé, l'API n'envoie aucun traceparent.

Étapes suivantes

Livraison et état de santé

Les règles suivantes s'appliquent aux spans que l'API envoie à vos destinations.

• Au moins une fois : une destination peut recevoir le même span plus d'une fois. Pour supprimer les doublons, utilisez l'ID de trace et l'ID de span.
• Au mieux : un span peut être perdu avant la livraison. L'API ne peut pas renvoyer un span perdu.
• Compression : l'API compresse la première requête de chaque livraison avec gzip et définit l'en-tête Content-Encoding: gzip. Si votre point de terminaison répond à cette requête par une réponse 400 ou 415, l'API renvoie immédiatement les mêmes spans sans compression.
• Nouvelles tentatives : l'API retente une livraison plus tard, un nombre limité de fois, après un délai d'expiration, un échec de connexion, TLS ou DNS, ou une réponse 408, 429 ou 5xx. Elle ne retente pas les autres échecs.
• Délais d'expiration : pour chaque requête, votre point de terminaison doit terminer la négociation TLS en 5 secondes et envoyer les en-têtes de réponse en 5 secondes. Chaque livraison expire après 10 secondes au total, y compris le renvoi sans compression.
• User agent : chaque requête comporte l'en-tête User-Agent: Claude-Platform.

La colonne Delivery affiche l'état de chaque destination. L'état peut avoir jusqu'à une minute de retard.

L'API désactive une destination lorsque :

• Le point de terminaison envoie une redirection 3xx.
• Le nom d'hôte du point de terminaison se résout en une adresse IP qui n'est pas publique.
• Toutes les livraisons échouent pendant 24 heures.

L'API n'envoie pas de spans à une destination désactivée. Pour relancer l'export, corrigez la cause. Ensuite, avec le filtre Workspace de la page des paramètres OpenTelemetry affichant All, cliquez sur Enable dans le menu More actions de la destination. L'export reprend en une minute environ.

Pour modifier une destination, ouvrez son menu More actions pendant que le filtre Workspace affiche All. Cliquez ensuite sur Edit, Disable, Enable ou Delete. Si vous modifiez l'hôte de l'OTLP endpoint URL, saisissez à nouveau les valeurs des en-têtes. Si la destination possède une OTLP traces endpoint URL, attribuez-lui le même nouvel hôte, ou effacez-la.

Limites

Dépannage

Erreurs de livraison

Lorsqu'une livraison échoue, la colonne Delivery affiche Failing. Maintenez le pointeur dessus pour voir l'erreur, puis identifiez la cause probable :

Compatibility