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 en quatre notions
Section intitulée « OpenTelemetry en quatre notions »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.
Les attributs GenAI de base
Section intitulée « Les attributs GenAI de base »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.
| Attribut | Description | Exemple |
|---|---|---|
gen_ai.provider.name | fournisseur du modèle | valeurs 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.name | type d’opération | chat, embeddings, text_completion |
gen_ai.request.model | modèle demandé | mistral:7b |
gen_ai.request.temperature | température demandée | 0.7 |
gen_ai.usage.input_tokens | jetons du prompt | 245 |
gen_ai.usage.output_tokens | jetons générés | 128 |
gen_ai.response.finish_reasons | raison de fin | stop, length, tool_call |
Ce que contient un span GenAI
Section intitulée « Ce que contient un span GenAI »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_receivedLa 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.
Les métriques à émettre par défaut
Section intitulée « Les métriques à émettre par défaut »Trois métriques sont standard ; les trois autres sont des extensions du kit, rangées sous mttl.*.
| Métrique | Type | Contenu |
|---|---|---|
gen_ai.client.token.usage | histogramme (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.duration | histogramme (standard) | durée d’une opération LLM, y compris en échec avec l’attribut error.type |
gen_ai.client.operation.time_to_first_chunk | histogramme (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.
Trace, métrique ou événement : où mettre quoi
Section intitulée « Trace, métrique ou événement : où mettre quoi »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.
Avant le lab 1
Section intitulée « Avant le lab 1 »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.