Module 2 : les conventions OpenTelemetry GenAI

OpenTelemetry en quatre notions

Notion	Rôle
Traces	décomposent une opération en spans hiérarchiques, chacun portant des attributs et des événements
Métriques	séries temporelles (compteur, jauge, histogramme), exportées en OTLP, compatibles avec le remote write Prometheus
Logs	journaux structurés, corrélés aux traces par trace_id et span_id
Conventions sémantiques	vocabulaire standardisé : http.*, db.*, messaging.*, gen_ai.* ; c’est ce qui rend une instrumentation portable

Les attributs GenAI essentiels

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

Un standard qui bouge

Les conventions GenAI ont toutes le statut Development et changent encore ; leur historique (renommages d’attributs, dépôt séparé, refonte des métriques de jetons) est raconté une seule fois, au §2 de l’article Observer un système LLM. Ce qu’il faut retenir pour les labs : le kit suit la version publiée (gen_ai.provider.name, histogramme gen_ai.client.token.usage) ; en production, faites la traduction entre versions dans le Collector (le kit en donne un exemple, transform/genai_compat) et n’exposez jamais les attributs bruts dans vos alertes.

Anatomie d’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_received

La valeur ollama n’est 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, ce qui 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, l’indicateur de latence perçue en streaming ; la convention le mesure aussi en métrique (ci-dessous).

Les métriques à émettre par défaut

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

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.

Labellisez toujours par modèle, client et fonctionnalité. Ce sont les trois axes de découpage que demanderont la finance, le produit et l’exploitation.

Traces, métriques ou événements ?

• La trace sert au diagnostic d’une requête : quel document, quel prompt, quel appel d’outil.
• La métrique sert à l’agrégat et à l’alerte : coût par heure, p95, score moyen.
• L’événement (ou le log) porte le contenu volumineux ou sensible, comme le prompt et la réponse, quand vous avez explicitement activé sa capture : rétention plus courte et masquage.

Données personnelles : la capture du contenu

La capture des prompts et des réponses est désactivée par défaut et ne s’active que par un choix explicite (opt-in) : les conventions GenAI demandent aux instrumentations de ne pas les capturer par défaut et classent gen_ai.system_instructions, gen_ai.input.messages et gen_ai.output.messages au niveau Opt-In. Sur les spans, elles réservent ces attributs aux cas où le volume reste maîtrisé et où le stockage respecte la réglementation (en préproduction, par exemple) ; en production, elles recommandent de stocker le contenu à part et de ne garder dans le span qu’une référence. Une fois la capture activée, placez donc le contenu hors des attributs indexés des spans (événement gen_ai.client.inference.operation.details, journal dédié ou stockage externe), masquez les données sensibles dans le Collector et donnez au contenu une rétention plus courte qu’aux métadonnées. Le détail de la règle est au §2 de l’article Observer un système LLM.

En résumé

Les conventions GenAI donnent un vocabulaire commun aux fournisseurs et aux frameworks. Elles bougent encore, donc la traduction entre versions se fait dans le Collector et jamais dans les tableaux de bord. Vos propres attributs vont dans votre espace de noms. Enfin, toute métrique LLM 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.

Marquer comme lue