Aller au contenu

TechniquePratique6 min de lecture

Module 2 : les conventions OpenTelemetry GenAI

Le vocabulaire standard qui décrit un appel à un LLM : les attributs gen_ai.*, ce que contient un span, les métriques à émettre par défaut et les précautions à prendre avec un standard qui bouge encore.

Pour : ingénieurs et SREPrérequis : Avoir lu le module 1 du parcours.

Imaginons deux équipes d’une même entreprise (scénario illustratif). L’une appelle Mistral et note le modèle utilisé dans un champ model. L’autre appelle un autre fournisseur et le note dans llm_name. Le jour où la direction demande la consommation totale par modèle, il faut d’abord traduire l’un dans l’autre, puis réécrire les tableaux de bord. Les conventions sémantiques servent à éviter ce genre de chantier.

OpenTelemetry, le standard ouvert de collecte, produit trois types de données. La trace raconte le trajet d’une requête, comme le suivi d’un colis : elle se découpe en spans, des étapes chronométrées emboîtées les unes dans les autres, qui portent chacune des attributs (des paires clé et valeur) et des événements datés. La métrique est un compteur ou une mesure suivie dans le temps (une série temporelle) : un compteur qui ne fait que monter, une jauge qui monte et descend ou un histogramme qui range les valeurs par tranches. Elle s’exporte en OTLP (le protocole d’OpenTelemetry) et reste compatible avec le remote write de Prometheus. Le journal (log) est un message structuré, relié aux traces par deux identifiants, trace_id et span_id.

La quatrième notion est celle qui nous occupe ici : les conventions sémantiques. C’est un vocabulaire commun, comme le format normalisé d’une adresse postale. Il existe des familles pour le web (http.*), les bases de données (db.*), les files de messages (messaging.*) et l’IA générative (gen_ai.*). C’est ce vocabulaire qui rend une instrumentation portable d’un outil à l’autre.

Voici les attributs qui décrivent un appel à un modèle. Ils répondent à des questions simples : qui fournit le modèle, quelle opération, quel modèle, avec quels réglages, combien de jetons et pourquoi la génération s’est arrêtée. La température, par exemple, règle la part de hasard dans la réponse : plus elle est basse, plus le modèle s’en tient aux mots les plus probables.

AttributDescriptionExemple
gen_ai.provider.namefournisseur du modèlevaleurs connues : openai, anthropic, mistral_ai, azure.ai.openai, etc. ; une valeur personnalisée est autorisée quand aucune ne s’applique (le kit utilise ollama)
gen_ai.operation.nametype d’opérationchat, embeddings, text_completion
gen_ai.request.modelmodèle demandémistral:7b
gen_ai.request.temperaturetempérature demandée0.7
gen_ai.usage.input_tokensjetons du prompt245
gen_ai.usage.output_tokensjetons générés128
gen_ai.response.finish_reasonsraison de finstop, length, tool_call

Voici ce qu’on doit trouver dans un span de production :

span chat mistral:7b
trace_id 5b8efff798038103d269b633813fc60c
duration 1.847s
attributes
gen_ai.provider.name = ollama
gen_ai.request.model = mistral:7b
gen_ai.operation.name = chat
gen_ai.usage.input_tokens = 245
gen_ai.usage.output_tokens = 128
app.tenant.id = acme-corp
app.feature = support-chat
app.quality.score = 0.78
events
[t+0.000s] request.start
[t+0.182s] first_token_received

La valeur ollama ne figure pas dans la liste des valeurs connues de gen_ai.provider.name. La convention impose une valeur connue quand l’une d’elles s’applique et autorise sinon une valeur personnalisée : c’est le cas d’un modèle servi localement par Ollama.

Les trois derniers attributs ne sont pas standard : ce sont des extensions maison. Placez-les dans votre propre espace de noms (app.*, ou le nom de votre organisation) plutôt que dans gen_ai.*, pour ne pas entrer en collision avec une future version de la convention. Le kit de labs range les siennes sous mttl.* (mttl.tenant.id, mttl.feature, mttl.quality.score).

L’événement first_token_received donne le temps au premier jeton. En streaming, quand la réponse s’affiche mot après mot, c’est la latence que l’utilisateur perçoit. La convention le mesure aussi sous forme de métrique, ci-dessous.

Trois métriques sont standard ; les trois autres sont des extensions du kit, rangées sous mttl.*.

MétriqueTypeContenu
gen_ai.client.token.usagehistogramme (standard)jetons consommés par opération, par type entrée ou sortie ; en cours de remplacement, voir l’encadré plus haut
gen_ai.client.operation.durationhistogramme (standard)durée d’une opération LLM, y compris en échec avec l’attribut error.type
gen_ai.client.operation.time_to_first_chunkhistogramme (standard)temps jusqu’au premier fragment reçu en streaming
coût estimé (mttl.client.cost dans le kit)compteur (extension)euros, calculés à partir des jetons et d’une grille de prix datée que vous fournissez ; sans grille, la métrique n’est pas émise
erreurs (mttl.client.errors dans le kit)compteur (extension)délais dépassés, refus, erreurs du fournisseur
score qualité (mttl.quality.score dans le kit)histogramme (extension)score de 0 à 1 issu de l’évaluation

Découpez toujours ces métriques par modèle, par client et par fonctionnalité. Ce sont les trois questions que poseront la finance, le produit et l’exploitation : quel modèle coûte le plus, quel client consomme le plus, quelle fonctionnalité se dégrade.

Pour les équipes techniques : les bornes des histogrammes de durée

Pour les histogrammes de durée, donnez des bornes adaptées aux secondes : la convention en recommande (0,01 ; 0,02 ; 0,04 … 81,92 s). Sans elles, le SDK Python applique des bornes par défaut pensées pour des millisecondes et les quantiles calculés n’ont plus de sens.

Chaque type de donnée a son usage. La trace sert à diagnostiquer une requête précise : quel document a été récupéré, quel prompt est parti, quel outil a été appelé. La métrique sert à agréger et à alerter : le coût par heure, la latence p95, le score moyen. L’événement (ou le journal) porte le contenu volumineux ou sensible, comme le prompt et la réponse, à condition que vous ayez explicitement activé sa capture ; on lui donne alors une rétention plus courte et on masque les données sensibles.

Les conventions GenAI donnent aux fournisseurs et aux frameworks un vocabulaire commun. Comme elles bougent encore, je recommande de faire la traduction entre versions dans le Collector, jamais dans les tableaux de bord. Avant d’ouvrir le lab, notez les attributs maison dont votre application aura besoin et choisissez leur espace de noms. Vérifiez aussi que chaque métrique LLM que vous prévoyez se découpe au minimum par modèle, client et fonctionnalité.

Révisé le 2 octobre 2026 : déplacement des conventions GenAI dans le dépôt semantic-conventions-genai (version 1.42) et refonte en cours des métriques de jetons signalés, métrique standard du temps au premier fragment, valeurs connues de gen_ai.provider.name, noms des extensions du kit, coût du kit émis seulement avec une grille de prix fournie par l’utilisateur.

Révisé le 4 octobre 2026 : historique des conventions remplacé par un renvoi au §2 de l’article Observer un système LLM ; règle de capture du contenu alignée sur les conventions GenAI (désactivée par défaut, opt-in, hors des attributs indexés en production), vérifiée sur le dépôt semantic-conventions-genai ; ollama présenté comme valeur personnalisée autorisée de gen_ai.provider.name.