Utiliser OpenTelemetry avec le SDK Claude

Avec OpenTelemetry, le SDK Claude peut émettre un span (segment) pour chaque requête qu'il envoie et pour chaque utilisation d'outil exécutée par le tool runner. Vous pouvez consulter ces spans dans votre plateforme d'observabilité, imbriqués dans vos propres traces.

Le SDK émet des spans dans votre application. L'exportateur OpenTelemetry de votre application les envoie à votre plateforme d'observabilité.

1. Installer le SDK

Installez la dernière version du Claude SDK ou mettez-le à niveau :

pip install --upgrade anthropic

pip install opentelemetry-sdk

2. Enregistrer un tracer provider

Un tracer provider (fournisseur de traceur) est l'objet OpenTelemetry qui crée les spans et les transmet à votre exportateur. Le SDK utilise le tracer provider que votre application enregistre, de sorte que vos appels au SDK restent les mêmes. Enregistrez-le avant le premier appel que vous souhaitez tracer.

L'exemple suivant enregistre un tracer provider qui affiche chaque span dans la console, puis effectue un appel. Utilisez-le pour voir les spans avant de connecter une plateforme d'observabilité :

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

# Enregistre un fournisseur de traceur qui affiche chaque span dans la console.
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 console affiche un span anthropic.messages.create.

3. Envoyer les spans à votre plateforme d'observabilité

Remplacez l'exportateur console par un exportateur OTLP qui pointe vers votre plateforme d'observabilité. Pour la configuration dans votre langage, consultez la documentation OpenTelemetry sur les exportateurs Python, les exportateurs TypeScript, les exportateurs .NET, les exportateurs Go, la configuration du SDK Java, les exportateurs PHP, ou les exportateurs Ruby.

4. Configurer le SDK

Utilisez les options suivantes pour décider de ce qui figure dans vos spans et de l'endroit où ils sont envoyés. Vous pouvez définir une option dans votre code ou, si elle en a une, avec la variable d'environnement indiquée sous son nom.

L'exemple suivant montre comment utiliser chaque option :

# Utilisez un fournisseur de traceur spécifique et enregistrez le contenu.
# Définir open_telemetry remplace toutes les variables d'environnement ANTHROPIC_OPEN_TELEMETRY*.
client = Anthropic(
    open_telemetry={"tracer_provider": provider, "traces": {"content_mode": "content"}}
)

# Désactivez les spans pour un client.
quiet_client = Anthropic(open_telemetry=False)

# Définissez un ID de conversation avec with_options(), qui renvoie une copie du client.
# with_options() remplace l'option entière, partez donc 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"}],
)

Étapes suivantes

Traçage d'un stream

Le span anthropic.messages.create d'un stream se termine lorsque votre code a lu l'intégralité du stream ou l'a fermé ; fermez donc un stream dont vous arrêtez la lecture prématurément. En mode contenu, le span contient la réponse du modèle uniquement lorsque vous lisez le stream avec messages.stream().

Les spans que vous démarrez pendant la lecture d'un stream sont des frères du span du SDK, et non ses enfants. Pour les regrouper avec la requête, démarrez votre propre span autour de l'appel et de la boucle de lecture.

Traçage d'un sandbox auto-hébergé Managed Agents

Dans un sandbox auto-hébergé Managed Agents, c'est votre sandbox qui exécute les outils ; les spans d'outils proviennent donc du SDK et non de l'API. Le worker d'environnement des SDK Python, TypeScript et Go émet un span pour chaque outil qu'il exécute et pour chaque requête qu'il envoie. Il les regroupe sous un span anthropic.environment.work pour chaque élément de travail.

Pour obtenir ces spans :

1. Dans le processus qui exécute le worker, configurez le traçage du SDK comme indiqué aux étapes 1 à 4.
2. Autorisez le trafic réseau du sandbox vers votre plateforme d'observabilité ou votre OpenTelemetry Collector.

Lorsque le worker envoie un résultat d'outil, le span de l'API de cette requête est imbriqué sous son span du SDK. Pour les requêtes que le worker envoie à Claude Platform on AWS, les spans de l'API se trouvent plutôt dans leurs propres traces.

Contexte de trace et baggage

À chaque requête, le SDK utilise le propagateur de votre application pour envoyer le contexte de trace à l'API dans des en-têtes comme traceparent. Si ce propagateur écrit aussi le baggage, le SDK envoie également votre baggage. Pour envoyer le contexte de trace sans baggage, enregistrez uniquement le propagateur de contexte de trace W3C.

Pour que le SDK n'envoie pas ces en-têtes, par exemple lorsque l'instrumentation de votre client HTTP les envoie déjà, désactivez la propagation du SDK :

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

Pendant que le SDK appelle un outil MCP, le span d'outil du SDK est le span courant. Certaines bibliothèques clientes MCP envoient le contexte de trace au serveur MCP dans _meta, si bien qu'un serveur qui le lit peut ajouter ses spans à votre trace sous ce span d'outil. C'est le cas du package Python mcp à partir de la version 2.0 et du package C# ModelContextProtocol. Les SDK MCP pour TypeScript, Go, Java, Ruby et PHP ne le font pas d'eux-mêmes.

Dépannage

Compatibility