AdministrationOpenTelemetry

OpenTelemetry pour l'API Claude

Copy page



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. 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. Pour les requêtes vers Claude Platform on AWS, les spans de l'API se trouvent plutôt dans leurs propres traces.

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 :

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.

• Metadata only (metadata_only dans 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.
• Full content (content dans 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 Metadata only.

Avec Full content, 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 Full content. 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 Full content, chaque span contient par défaut jusqu'à 0,75 Mo de contenu. Cela convient à une fenêtre de contexte de 200k tokens remplie de texte en anglais, tout en restant sous la limite de requête de 1 Mo de nombreuses plateformes d'observabilité et proxys. Si vous choisissez une plateforme partenaire comme Provider, la Console définit une limite qu'accepte 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 Content mode sur Full content lorsque vous ajoutez une destination, puis définissez Maximum content size in MB sous Advanced settings.

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 message, 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 le tool runner, l'utilitaire du SDK qui exécute vos outils et renvoie leurs résultats à Claude. Chaque requête envoyée par le tool runner possède un span client provenant du SDK et un span serveur provenant de l'API. Les spans apparaissent dans l'ordre suivant :

1. Votre application démarre le span answer_question et appelle le tool runner de Messages à l'intérieur de celui-ci (représenté par le span anthropic.messages.tool_runner).
2. Le tool runner envoie la première requête (représentée par le premier span client anthropic.messages.create et 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.
3. 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.
4. Le tool runner exécute get_weather (représenté par le span anthropic.custom_tool_use get_weather).
5. Le tool runner envoie la seconde requête avec le résultat de l'outil (représentée par le second span client anthropic.messages.create et les spans situés sous celui-ci).
6. 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 Full content, 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 :

1. Votre application reçoit une requête POST /chat d'un utilisateur.
2. Votre application démarre le session tool runner du SDK, qui liste et diffuse en streaming les événements de la session (représentés par les spans anthropic.sessions.events.stream et anthropic.sessions.events.list).
3. Votre application envoie le message de l'utilisateur à la session en appelant sessions.events.send.
4. Un tour démarre et comprend des requêtes au modèle, une utilisation de l'outil bash et un tour sur un autre thread (représentés par le premier span anthropic.session.turn et les spans situés en dessous).
5. Le modèle demande à utiliser l'outil personnalisé list_issues, de sorte que le tour se termine avec la raison d'arrêt requires_action.
6. Le session tool runner exécute list_issues (représenté par le span anthropic.custom_tool_use list_issues) et envoie son résultat en appelant sessions.events.send.
7. 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 multiagent activé, une session peut également comporter plusieurs threads. Pour trouver les spans dont vous avez besoin, regroupez-les par un ID.

• Un seul thread : regroupez les spans par gen_ai.conversation.id, qui contient l'ID du thread de la session. Triez-les par heure de début pour lire le thread comme une transcription.
• Une session entière, avec tous ses threads : 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_instructions sur le premier span de tour d'un thread, l'entrée dans gen_ai.input.messages (vos messages et résultats d'outils, les événements system.message et les messages provenant d'autres threads), et la sortie dans gen_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 dans anthropic.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 attributs anthropic.usage.compaction.input_tokens et anthropic.usage.compaction.output_tokens du span, car les attributs gen_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 spans anthropic.model_request, mais pas les deux. Si une requête comporte des compactions, ajoutez également ses spans anthropic.compaction. N'ajoutez pas en plus les attributs anthropic.usage.compaction.* du span anthropic.messages.create, car ils contiennent les mêmes tokens.
• Spans de l'API d'une session Managed Agents : additionnez les spans anthropic.model_request et anthropic.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.