Conventions GenAI : comment figer une spec sans version publiée
Les conventions GenAI n’ont aucune version à citer. Alors quelle version suit votre télémétrie, et comment un lecteur le saurait-il ?
EN 30 SECONDES
Figer, c’est verrouiller votre installation sur une version exacte. Pour les conventions GenAI, sans version publiée, cela veut dire la base v1.44.0 plus un commit complet de semantic-conventions-genai, inscrits sur chaque signal, et les simples renommages traités dans le Collector.
À RETENIR · 3
- Figez les conventions de base sur la v1.44.0 et le dépôt GenAI à un SHA de commit complet, et inscrivez les deux sur chaque ressource.
- Traitez les simples renommages dans le Collector. Un changement de type ou de dimensions d’une métrique, comme la #374, demande de toucher à l’instrumentation.
- Changez de SHA délibérément : lisez les changements cassants annoncés, faites coexister anciens et nouveaux noms, puis passez au nouveau SHA.
Sur cette page
Trier chaque champ avant de figer
EN BREF Figez la base en v1.44.0 et le dépôt GenAI à un commit complet, inscrivez les deux sur chaque signal, et n’en changez que délibérément.
LES MOTS À CONNAÎTRE
- Figer (pin)
- Verrouiller votre installation sur une version exacte, ici un SHA de commit git complet : l’identifiant unique d’un instantané du code.
- Ressource
- Dans OpenTelemetry, les attributs qui décrivent ce qui envoie la télémétrie, comme service.name. Ils accompagnent chaque span, métrique et journal.
- Collector
- L’OpenTelemetry Collector, un service qui reçoit la télémétrie en route vers votre backend et peut la renommer ou la remodeler.
- Dimension
- Un libellé qui sert à regrouper les chiffres d’une métrique, par exemple texte, image ou audio.
Figer une spec sans version publiée paraît étrange, jusqu’à ce qu’on pense à Git. Figer (pin) Verrouiller votre installation sur une version exacte, ici un SHA de commit git complet : l’identifiant unique d’un instantané du code. Voir le glossaire sur un SHA de commit, c’est choisir un instantané exact : une version sans l’étiquette.
Avant de figer, rangez chaque champ émis dans l’une de quatre cases. N’inventez jamais de clé gen_ai.* pour une donnée que la spec ne couvre pas.
Dans la section suivante : Alors, comment figer une spec qui n’a pas de version ?
Six étapes pour figer, puis changer de version
EN BREF Deux versions inscrites sur chaque signal, et une règle du Collector par simple renommage. C’est la procédure que je mettrais dans le dépôt.
LE GEL, ÉTAPE PAR ÉTAPE
Étape 1. Figer la base. Figez les conventions de base sur la v1.44.0, la version dont dépend le manifest GenAI. Elle contient les attributs stables error.type et server.*.
- Figer la base Figez les conventions de base sur la v1.44.0, la version dont dépend le manifest GenAI. Elle contient les attributs stables error.type et server.*.
- Figer le dépôt GenAI Figez semantic-conventions-genai à un SHA complet. Il n’existe aucun tag, et l’URL de schéma est provisoire (-dev).
- Marquer la ressource Inscrivez les deux sur la ressource, par exemple com.acme.semconv.core et com.acme.semconv.genai_commit.
- Figer la bibliothèque Figez aussi la bibliothèque d’instrumentation, et lisez ce que font vraiment ses options d’activation.
- Renommer dans le Collector Chaque simple renommage reçoit une règle, versionnée avec le SHA figé. Les changements de type ou de dimensions repassent par l’instrumentation.
- Changer de SHA, délibérément Lisez les nouveaux fragments changelog.d cassants, faites coexister anciens et nouveaux noms un temps, puis déplacez le SHA.
Pour l’étape 4, la base v1.41.0 et son correctif v1.41.1 avaient un plan de transition. Une bibliothèque qui envoyait déjà d’anciens noms GenAI devait les garder par défaut. Elle ne devait passer aux nouveaux que si gen_ai_latest_experimental figurait parmi les valeurs d’OTEL_SEMCONV_STABILITY_OPT_IN.
ATTENTION
Je n’ai pas retrouvé ce texte dans le nouveau dépôt, au commit consulté. Vérifiez donc ce que votre bibliothèque documente, au lieu de le supposer.
L’étape 5 est celle qui me tient le plus à cœur. Prenez un parc comme les 46 agents que j’ai fait tourner chez Integra : un renommage dans le code des agents, ce sont de nombreux changements séparés. Dans le Collector L’OpenTelemetry Collector, un service qui reçoit la télémétrie en route vers votre backend et peut la renommer ou la remodeler. Voir le glossaire, c’est un seul changement relu, et les tableaux de bord gardent leurs requêtes.
EN CLAIR
Cela ne marche que pour un vrai renommage, comme le champ de cache de la #440. La #374 a remplacé un histogramme par des compteurs et des histogrammes par opération, avec une nouvelle Dimension Un libellé qui sert à regrouper les chiffres d’une métrique, par exemple texte, image ou audio. Voir le glossaire de modalité. Aucune règle du Collector ne peut inventer une dimension jamais envoyée.
Il faut alors reprendre l’instrumentation, puis vérifier que les totaux concordent toujours. La version inscrite sur la Ressource Dans OpenTelemetry, les attributs qui décrivent ce qui envoie la télémétrie, comme service.name. Ils accompagnent chaque span, métrique et journal. Voir le glossaire dit quels spans datent d’avant.
« ne devrait pas servir en production » (« SHOULD NOT be used in production »)
C’est ce que dit la définition de maturité pour le statut Development, dont les réglages peuvent souvent casser. Si vous l’utilisez quand même, et la plupart d’entre nous le feront, cette méthode est le prix à payer pour bien faire.
OBJET OBTENU
Figer, inscrire, renommer une fois
Sources, consultées le 7 octobre 2026 : semantic-conventions-genai, manifest, README de la base v1.41.0, spans, niveaux de maturité.
FAQ
Selon OpenTelemetry, les réglages d’un composant Development peuvent souvent casser. Un tel composant ne devrait pas servir en production (« SHOULD NOT »). Les équipes s’en servent quand même : à ma connaissance, rien d’autre ne donne aux agents un vocabulaire commun.
NIVEAU TERMINÉ
Ce que vous savez maintenant
- Quels sont les quatre genres de champs, et où va chacun avant de figer.
- Pourquoi une règle du Collector peut corriger un renommage, mais pas une nouvelle dimension.
Vérifiez par vous-même
Touchez ou cliquez une question pour voir la réponse.
Votre rapport de coûts interroge encore gen_ai.usage.cache_creation.input_tokens, que la #440 a renommé en gen_ai.usage.cache_write.input_tokens. Une règle du Collector suffit-elle ?
Oui, pour ce simple renommage : une règle, versionnée avec le SHA figé, ramène la nouvelle clé vers l’ancienne. La #374 était différente, car elle a changé le type et les dimensions d’une métrique.
Vous avez fini tous les niveaux publiés de cette série. Retour à la carte de la série
Ingénieur web3 x IA, ancien CTO d’Integra. Auteur nommé (1 sur 5) d’ERC-3643, premier auteur d’ERC-6960, co-auteur d’ERC-7410 et co-auteur d’ERC-8203, encore à l’état de brouillon.
Un projet à livrer ou un poste à pourvoir ?
Parlons de votre besoinSuivre les notes techniques
Recevez les nouveaux articles sur l’IA en production et les smart contracts par email.