Tous les articles
IA & dev

Claude OpenTelemetry : tracer ses appels à l'API Claude dans une application Java

Par Elouan Laurent
Opérateur devant un mur d'écrans de supervision, image de l'observabilité des appels LLM

Qu'est-ce que l'export OpenTelemetry de l'API Claude ?

Depuis le 14 octobre 2026, Anthropic propose en bêta l'export OpenTelemetry de l'API Claude. Chaque requête Messages API et chaque session Managed Agents peut produire des traces dans votre propre outil d'observabilité. Par défaut, ces traces ne contiennent pas le texte des prompts.

OpenTelemetry est le standard ouvert de traçage que lisent Datadog, Grafana, Honeycomb ou un Collector maison. Une trace suit une requête de bout en bout. Un span en est une étape : un appel au modèle, l'exécution d'un outil.

Les spans viennent de deux sources, décrites dans la documentation d'Anthropic :

  • le SDK, dans votre application. Python, TypeScript, C#, Go, Java, PHP et Ruby sont concernés. Aucun droit particulier n'est requis.
  • l'API, côté Anthropic. Vous déclarez une destination dans la Claude Console, avec le rôle admin. Cela marche pour n'importe quel client, SDK ou non, mais la doc ne le prévoit que sur Claude Platform et Claude Platform on AWS.

Les deux utilisent les conventions sémantiques GenAI d'OpenTelemetry. Un outil qui les connaît reconnaît donc les spans sans réglage.

Ne confondez pas avec la télémétrie de Claude Code, qui occupe presque toute la recherche « claude opentelemetry ». Ici, il s'agit de vos propres appels à l'API. Le même jour, Anthropic a aussi ouvert les déploiements planifiés de Managed Agents sur Claude Platform on AWS.

Sauf mention contraire, les faits qui suivent viennent de la documentation d'Anthropic, relevée le 15 octobre 2026. Je n'ai rien mesuré.

Ce qu'un span contient : des tokens et des durées, pas des euros

Un span d'appel au modèle porte le modèle demandé et le modèle qui a répondu. Il porte aussi les tokens d'entrée, de sortie, de cache et de réflexion, le stop_reason et le statut. Sur un appel en streaming, le span du SDK mesure le délai avant le premier morceau de réponse.

Pour un CTO, c'est la matière d'un tableau de bord de coût et de latence par fonctionnalité. Mais aucun attribut ne donne de montant en dollars. Le coût se calcule : tokens multipliés par la grille de prix, comme la grille de prix de Claude Haiku 5.5.

Deux pièges de comptage figurent dans la doc :

  • Ne comptez qu'une source par requête. Le span du SDK (CLIENT) et celui de l'API (SERVER) portent le même nom, et chacun porte les tokens de la requête.
  • N'additionnez pas le cache aux tokens d'entrée. gen_ai.usage.input_tokens inclut déjà les lectures et écritures de cache.

Enfin, les spans ne sont pas un relevé comptable. Leur livraison est « best effort » : un span peut se perdre. Pour suivre l'usage de chaque clé d'API, la doc renvoie à l'Usage API, qui compte aussi les requêtes sans span.

Brancher le SDK Java dans une application Spring Boot

Le support arrive avec com.anthropic:anthropic-java 2.72.0, publié le 14 octobre. La note de version est claire. Si votre application a enregistré un tracer provider global, le SDK l'utilise dès la mise à jour, sans changement de code.

Un tracer provider est l'objet OpenTelemetry qui crée les spans et les passe à l'exporteur. Le cas le plus simple est l'agent Java d'OpenTelemetry. D'après sa documentation, l'agent enregistre lui-même l'instance globale. Le SDK d'Anthropic la trouve donc seul.

Avec l'agent, un réglage compte. Le client Java d'Anthropic s'appuie sur OkHttp, que l'agent instrumente déjà. La doc du SDK conseille alors de couper la propagation du SDK (propagation(false)), pour ne pas envoyer deux fois le contexte de trace.

Sans agent, Spring Boot crée le SDK OpenTelemetry comme un bean. Dans le code de son auto-configuration (version 4.1.0), ce SDK n'est pas enregistré en global. J'en déduis que le SDK d'Anthropic ne le verra pas tout seul. Il faut lui passer le tracer provider :

@Configuration
class ClaudeConfig {

    @Bean
    AnthropicClient anthropicClient(OpenTelemetry openTelemetry) {
        var envOptions = OpenTelemetryOptions.fromEnv();
        return AnthropicOkHttpClient.builder()
            .fromEnv()
            .openTelemetry(envOptions.toBuilder()
                .tracerProvider(openTelemetry.getTracerProvider())
                .build())
            .build();
    }
}

Ce bloc reprend les méthodes de la doc et du code du SDK 2.72.0. Je ne l'ai ni compilé ni exécuté.

Il a une limite. Le SDK lit le propagateur sur l'instance globale. Sans elle, il n'envoie pas d'en-tête traceparent, et les spans de l'API restent dans leurs propres traces au lieu de s'emboîter sous les vôtres.

Autre détail : d'après sa documentation, Spring Boot n'échantillonne par défaut que 10 % des requêtes. J'en déduis que les spans du SDK, créés par ce tracer provider, suivent ce taux. Pour compter des tokens, relevez management.tracing.sampling.probability ou prenez les spans de l'API.

Dernier point de dépendances : vérifiez la version d'opentelemetry-api. La doc signale qu'une version antérieure à 1.57.0, tirée par une autre bibliothèque, empêche le SDK Java d'utiliser votre tracer provider.

Et si vous passez par Spring AI ?

Spring AI émet déjà ses propres observations via Micrometer. D'après sa documentation d'observabilité, chaque appel à un ChatModel produit une observation gen_ai.client.operation avec les tokens. La métrique gen_ai.client.token.usage les mesure aussi, appel par appel. Le contenu des prompts n'est pas exporté par défaut.

En revanche, Spring AI 2.0.1 embarque le SDK d'Anthropic en version 2.52.0. Le jalon 2.1.0-M1 embarque la 2.64.0. Aucune n'a le support OpenTelemetry natif, arrivé en 2.72.0.

Forcer une version plus récente du SDK sous Spring AI n'est pas documenté. Je ne l'ai pas testé. La voie sûre reste la destination côté API : elle trace n'importe quel client, Spring AI compris.

Attention aux doublons. Avec la destination active, un même appel apparaît deux fois : dans l'observation Spring AI et dans le span de l'API. Pour vos tableaux de coût, ne sommez les tokens que d'une des deux sources.

Déclarer la destination dans la Claude Console

Côté API, il n'y a pas de code à écrire. La configuration se fait dans la Console :

  1. Prérequis : le rôle admin de l'organisation, et un endpoint OTLP/HTTP en protobuf, en HTTPS sur le port 443.
  2. Collector maison : son récepteur OTLP/HTTP écoute par défaut sur le port 4318. Placez un reverse proxy devant, ou configurez-le en HTTPS sur 443.
  3. Ajout : dans les réglages OpenTelemetry de l'organisation, saisissez l'URL, les en-têtes d'authentification et le mode de contenu.
  4. Périmètre : choisissez les workspaces couverts (tous, une sélection, ou tous sauf certains).
  5. Test : le bouton Test envoie un span anthropic.test. Dans votre outil, les spans de l'API portent service.name = claude-platform.

Une organisation a droit à 10 destinations au plus. L'API désactive une destination dont toutes les livraisons échouent pendant 24 heures. Le même réglage existe dans l'Admin API, encore en bêta.

Le contenu des prompts dans vos traces : défaut prudent, choix à assumer

Chaque destination et chaque client SDK a un mode de contenu. Metadata only est le défaut : identifiants, durées, statut, tokens, noms et descriptions de vos outils. Full content ajoute les prompts et les réponses du modèle, limités par défaut à 0,75 Mo par span.

Le mode complet sert à comprendre pourquoi un appel a échoué ou traîné, et à construire des évaluations sur du trafic réel. Mais il change la nature de vos traces. D'après Anthropic, une fois livrées, les données sont conservées par le service choisi, hors d'Anthropic, selon ses propres règles d'accès et de conservation.

En mode complet, si vos utilisateurs écrivent des noms, des e-mails ou des dossiers clients, ces données partent dans votre outil d'observabilité. Le RGPD demande des données « limitées à ce qui est nécessaire au regard des finalités » et une conservation limitée. Mes réglages par défaut :

  • Metadata only en production. Le contenu complet seulement sur un workspace de recette, avec des données de test.
  • Une durée de rétention courte côté outil d'observabilité, et un contrat de sous-traitance avec ce fournisseur.
  • Aucune donnée personnelle dans conversationId. La doc précise que cet identifiant est exporté dans les deux modes.

Que faire cette semaine ?

Mon avis : cette bêta répond à une vraie question de CTO. Combien coûte chaque fonctionnalité qui appelle Claude, et où passe le temps ? La bonne nouvelle : la destination côté API ne demande aucune ligne de code.

Trois actions :

  1. Ajouter une destination en Metadata only vers votre outil actuel, sur un seul workspace, et vérifier le span de test.
  2. Construire un tableau de bord par modèle à partir des tokens, en ne sommant qu'une source par requête. Gardez l'Usage API comme référence pour la facture.
  3. Passer le SDK Java en 2.72.0 sur une branche, avec une version épinglée : en bêta, les noms de spans et d'attributs peuvent changer.

Si votre application passe par Spring AI, gardez la destination côté API en attendant une version qui embarque le SDK 2.72.0. Pour suivre ce qui bouge de ce côté, voyez le jalon Spring AI 2.1.

Vous voulez savoir ce que coûte chaque fonctionnalité de votre application qui appelle Claude ? Je développe en Java / Spring Boot depuis 2015. Réserver un appel découverte de 30 minutes pour poser vos traces et votre premier tableau de bord.

À lire ensuite