Traçage OpenTelemetry pour l’API Claude
Tracez vos requêtes à l’API Messages, vos utilisations d’outils et vos sessions Managed Agents avec des spans OpenTelemetry provenant du SDK Claude et de l’API Claude.
L’API Claude et le SDK peuvent tracer vos requêtes à l’API Messages, vos utilisations d’outils et vos sessions Managed Agents avec OpenTelemetry (OTel). Vous pouvez consulter ces traces dans la plateforme d’observabilité dont vous disposez déjà. Utilisez-les pour déboguer les requêtes en échec ou lentes, suivre la consommation de tokens et la « latency » (latence), et construire des évaluations à partir du trafic réel. Vous pouvez également voir chaque requête dans les propres traces de votre application, reliée à l’utilisateur ou à la fonctionnalité qui l’a envoyée.
OpenTelemetry est un standard indépendant des fournisseurs que la plupart des plateformes d’observabilité prennent en charge. Une trace (trace) est l’enregistrement complet d’une requête à travers votre système. Un span (segment) est une étape d’une trace, comme une requête au modèle ou une utilisation d’outil. L’API et le SDK utilisent des attributs issus des conventions sémantiques GenAI, de sorte que les plateformes qui prennent en charge ces conventions peuvent reconnaître les spans sans configuration supplémentaire.
Premiers pas
Vous pouvez configurer le traçage du SDK, le traçage de l’API, ou les deux. Configurez les deux pour voir les spans du SDK et de l’API d’une requête dans une même trace, comme dans les exemples de traces.
Claude Code
Laissez Claude Code configurer cette fonctionnalité pour vous
Configure le traçage OpenTelemetry avec l'API Claude et le SDK ClaudeInstallez le SDK et enregistrez un fournisseur de traceurs.
Ajoutez une destination dans la Claude Console.
Consultez les spans et leurs attributs.
| Requêtes à l’API MessagesAperçu disponible avec des liens vers la référence de l’API, appuyez sur Tab jusqu’à ce que le focus entre dans la carte, et sur Échap pour revenir. | | | |
| Requêtes à l’API Sessions | | | |
| Utilisation des tokens (voir Comptage des tokens) | | | |
| Chaque exécution du modèle au sein d’une requête | | | |
| Tours de Managed Agents | | | |
| Outils serveur, exécutés par l’API | | | |
| Outils client, exécutés par l’exécuteur d’outils | | | |
| Outils dans un sandbox auto-hébergé | | | |
| Autres requêtes API, comme le téléversement de fichiers | | | |
| Configuration | Code | Console | Les deux |
| Autorisation requise | Aucune | Administrateur | Administrateur |
| Couverture | Tout client | Tout client | |
| Prise en charge des plateformes cloud | Toutes | Claude Platform | Claude Platform |
Pour Claude Code, l’Agent SDK ou Cowork, consultez Surveillance de Claude Code, Observabilité de l’Agent SDK ou Surveillance de l’activité de Cowork.
Envoyer des traces vers une plateforme partenaire
Envoyez des traces vers toute plateforme d’observabilité acceptant OTLP, y compris ces partenaires :
Plateforme unifiée d’observabilité et d’évaluation pour l’IA.
Plateforme d’observabilité active pour les agents.
Plan de contrôle de l’IA unifié pour l’observabilité et l’évaluation.
Observabilité et sécurité propulsées par l’IA.
Observabilité conçue pour l’ère de l’IA.
Observabilité fondée sur l’open source.
Plateforme d’observabilité ouverte entièrement gérée.
Plateforme d’observabilité pour la nouvelle forme du logiciel.
Plateforme open source d’observabilité et d’évaluation d’agents.
Plateforme d’ingénierie d’agents LangSmith.
Plateforme d’observabilité intelligente.
Plateforme tout-en-un pour créer des produits à succès.
Observabilité IA et généraliste, prête pour la production.
Déboguez votre code défaillant et vos agents au comportement erratique.
Plan de contrôle agentique avec observabilité et gouvernance intégrées.
Observez, évaluez et sécurisez vos agents.
Modes de contenu
Chaque destination et chaque client du SDK possède un mode de contenu, qui détermine si les spans incluent les prompts et les réponses du modèle. Définissez-le lorsque vous ajoutez une destination ou configurez le SDK.
- Métadonnées uniquement (
metadata_onlydans le SDK) : la valeur par défaut. Les spans incluent les identifiants, la chronologie, le statut, le nombre de tokens et le texte que vous choisissez, comme les noms et descriptions de vos agents et outils et les noms de vos serveurs MCP. - Contenu complet (
contentdans le SDK) : la visibilité la plus complète. Les spans incluent les prompts et les réponses du modèle, ainsi que tout ce que contient le mode Métadonnées uniquement.
Avec Contenu complet, vous pouvez également voir pourquoi une exécution a échoué ou a été lente, lire des conversations complètes et construire des évaluations à partir de traces réelles. Dans la référence des spans OpenTelemetry, les attributs qui contiennent des prompts et des réponses sont marqués Contenu.
Si votre organisation a une restriction de traitement des données HIPAA, FERPA ou K-12 avec Anthropic, les destinations n’exportent que les métadonnées, quel que soit leur mode de contenu. Les spans du SDK ne sont pas concernés.
Avec la conservation zéro des données, vous pouvez toujours utiliser Contenu complet. Pour les requêtes de l’API Messages, l’API conserve le contenu exporté uniquement en mémoire jusqu’à ce qu’elle le transmette à la destination. Claude Managed Agents n’est pas éligible à la conservation zéro des données, et sa conservation des données reste la même lorsque vous utilisez OpenTelemetry.
Limites de contenu
Avec Contenu complet, chaque span contient par défaut jusqu’à 0,75 Mo de contenu. Cela convient à une fenêtre de contexte de 200k tokens de texte en anglais et reste en dessous de la limite de requête de 1 Mo de nombreuses plateformes d’observabilité et de nombreux proxys. Si vous sélectionnez une plateforme partenaire comme Fournisseur, la Console définit une limite acceptée par cette plateforme.
Lorsque le contenu dépasse la limite, le SDK ou l’API le raccourcit et définit anthropic.content.truncated sur true. Sur les spans de requête, l’invite système et les messages les plus anciens sont supprimés en premier, et sur les spans d’outil, des blocs sont supprimés en partant de la fin du résultat. Les images et les documents n’apparaissent que sous la forme de leur type.
Modifiez la limite dans les cas suivants :
- Votre plateforme d’observabilité accepte des charges utiles plus volumineuses : Augmentez ou supprimez la limite pour conserver intégralement les prompts et les réponses longs. Une fenêtre de contexte de 1M tokens entièrement remplie nécessite environ 4 Mo.
- Votre plateforme d’observabilité ou un proxy placé devant elle rejette les requêtes volumineuses : Réduisez la limite.
Dans le SDK, définissez traces.max_content_bytes. Dans la Console, définissez Mode de contenu sur Contenu complet lorsque vous ajoutez une destination, puis définissez Taille maximale du contenu en Mo sous Paramètres avancés.
Exemples de traces et comment les lire
Une requête à l’API Messages
Sous le span de l’API d’une requête qui crée un messageAperçu disponible avec des liens vers la référence de l’API, appuyez sur Tab jusqu’à ce que le focus entre dans la carte, et sur Échap pour revenir., l’API ajoute un span pour chaque requête au modèle et un span d’outil pour chaque utilisation d’un outil serveur ou d’un outil de connecteur MCP exécutée par l’API.
Dans cet exemple, votre application appelle l’exécuteur d’outils, l’utilitaire du SDK qui exécute vos outils et renvoie leurs résultats à Claude. Chaque requête envoyée par l’exécuteur d’outils possède un span client provenant du SDK et un span serveur provenant de l’API. Les spans apparaissent dans l’ordre suivant :
- Votre application démarre le span
answer_questionet appelle l’exécuteur d’outils de Messages à l’intérieur de celui-ci (représenté par le spananthropic.messages.tool_runner). - L’exécuteur d’outils envoie la première requête (représentée par le premier span client
anthropic.messages.createet les spans situés sous celui-ci). Dans cette requête, l’API exécute l’outil de recherche web entre deux requêtes au modèle. - Dans la seconde requête au modèle, le modèle demande à utiliser l’outil personnalisé
get_weather; la première requête se termine donc. - L’exécuteur d’outils exécute
get_weather(représenté par le spananthropic.custom_tool_use get_weather). - L’exécuteur d’outils envoie la seconde requête avec le résultat de l’outil (représentée par le second span client
anthropic.messages.createet les spans situés sous celui-ci). - Dans la seconde requête, le modèle donne la réponse finale.
Le SDK de votre application émet le span anthropic.messages.tool_runner, le span anthropic.custom_tool_use et le span client de chaque requête. Pour obtenir ces spans, configurez le traçage du SDK.
Chaque requête porte son utilisation de tokens sur plusieurs de ses spans. Pour compter chaque token une seule fois, consultez Comptage des tokens.
Avec Contenu complet, le span serveur anthropic.messages.create contient le prompt et la réponse. L’invite système se trouve dans gen_ai.system_instructions, les messages de la requête dans gen_ai.input.messages et la réponse dans gen_ai.output.messages.
Pour chaque span et ses attributs, consultez la référence des spans OpenTelemetry.
Une session Managed Agents
Une session comporte un span pour chaque requête de l’API Sessions et un span de tour pour chaque tour de l’agent. Un tour démarré par une requête est un enfant du span de cette requête. Un tour contient un span pour chaque requête au modèle et pour chaque outil que l’API exécute, sauf dans les cas répertoriés dans la référence des spans d’outils. Il contient également un span pour chaque évaluation de résultat.
Cet exemple suit une requête de chat, dans laquelle votre application envoie un message à une session et exécute un outil personnalisé. La trace comporte des spans provenant à la fois de votre application et de l’API, dans l’ordre suivant :
- Votre application reçoit une requête
POST /chatd’un utilisateur. - Votre application démarre l’exécuteur d’outils de session du SDK, qui liste et diffuse en streaming les événements de la session (représentés par les spans
anthropic.sessions.events.streametanthropic.sessions.events.list). - Votre application envoie le message de l’utilisateur à la session en appelant
sessions.events.send. - Un tour démarre et comprend des requêtes au modèle, une utilisation de l’outil
bashet un tour sur un autre fil (représentés par le premier spananthropic.session.turnet les spans situés en dessous). - Le modèle demande à utiliser l’outil personnalisé
list_issues, de sorte que le tour se termine avec la raison d’arrêtrequires_action. - L’exécuteur d’outils de session exécute
list_issues(représenté par le spananthropic.custom_tool_use list_issues) et envoie son résultat en appelantsessions.events.send. - Un second tour démarre avec le résultat de l’outil (représenté par le dernier span
anthropic.session.turn).
Le SDK de votre application émet le span anthropic.custom_tool_use et le span client de chaque requête. Pour obtenir ces spans, configurez le traçage du SDK.
Les spans d’une session peuvent se trouver dans plusieurs traces, par exemple lorsque vous envoyez une requête ultérieure depuis une nouvelle trace racine. Avec le mode multi-agents activé, une session peut également comporter plusieurs fils. Pour trouver les spans dont vous avez besoin, regroupez-les par un ID.
- Un seul fil : regroupez les spans par
gen_ai.conversation.id, qui contient l’ID du fil de la session. Triez-les par heure de début pour lire le fil comme une transcription. - Une session entière, avec tous ses fils : regroupez les spans par
anthropic.session.id, à travers les traces.
Avec Contenu complet, vous pouvez lire le contenu d’une session à partir de ses spans.
- Pour lire le contenu d’un tour, utilisez son span de tour. L’invite système se trouve dans
gen_ai.system_instructionssur le premier span de tour d’un fil, l’entrée dansgen_ai.input.messages(vos messages et résultats d’outils, les événementssystem.messageet les messages provenant d’autres fils), et la sortie dansgen_ai.output.messages(les messages de l’agent, les utilisations d’outils et les résultats d’outils). - Pour voir les arguments et le résultat d’une utilisation d’outil, lisez son span d’outil. Les arguments se trouvent dans
gen_ai.tool.call.arguments, et le résultat dansanthropic.tool_result.content.
Pour chaque span et ses attributs, consultez la référence des spans OpenTelemetry.
Comptage des tokens
Pour compter chaque token une seule fois, additionnez les spans d’une seule source pour chaque requête. Lorsqu’une requête de l’API Messages comporte à la fois un span du SDK et un span de l’API, additionnez ses spans de l’API. Les deux sont nommés anthropic.messages.create ; distinguez-les donc par leur type : le span du SDK est CLIENT et son enfant, le span de l’API, est SERVER.
Pour chaque source, additionnez uniquement les spans suivants, car certains attributs d’utilisation se répètent sur plus d’un niveau des spans de l’API :
- Spans du SDK : additionnez les spans
anthropic.messages.create. Si une requête comporte des compactions, ajoutez également les attributsanthropic.usage.compaction.input_tokensetanthropic.usage.compaction.output_tokensdu span, car les attributsgen_ai.usage.*n’incluent pas les tokens de compaction. Si un modèle de repli a traité une requête, son span contient l’utilisation du seul modèle qui a fourni la réponse. - Spans de l’API d’une requête de l’API Messages : additionnez soit les spans
anthropic.messages.create, soit leurs spansanthropic.model_request, mais pas les deux. Si une requête comporte des compactions, ajoutez également ses spansanthropic.compaction. N’ajoutez pas en plus les attributsanthropic.usage.compaction.*du spananthropic.messages.create, car ils contiennent les mêmes tokens. - Spans de l’API d’une session Managed Agents : additionnez les spans
anthropic.model_requestetanthropic.session.outcome_evaluation.
Les spans peuvent arriver plus d’une fois, par exemple lorsqu’une livraison est relancée. Si votre plateforme d’observabilité ne supprime pas les doublons, comptez chaque span une seule fois à l’aide de son ID de trace et de son ID de span.
gen_ai.usage.input_tokens inclut déjà les tokens lus depuis le cache de prompts et écrits dans celui-ci ; n’y ajoutez donc pas les attributs de cache. Pour tous les attributs d’utilisation, consultez Utilisation des tokens.
Disponibilité
OpenTelemetry est en bêta sur tous les modèles.
Prise en charge de l’API
Cette page vous a-t-elle été utile ?