Les conventions sémantiques (semconv)

1. Le rôle des conventions #

Un vocabulaire commun pour toute la télémétrie.

Le problème #

Les conventions sémantiques (semantic conventions, « semconv ») définissent les noms, types, unités et valeurs autorisées des attributs, des spans, des métriques et des événements. Elles permettent à un backend d'afficher automatiquement une carte des services, de détecter une requête SQL lente ou de calculer un taux d'erreur HTTP, quel que soit le langage ou la bibliothèque.

Les règles de nommage #

• Espaces de noms en minuscules séparés par des points : http.request.method, db.collection.name.
• Des mots séparés par _ dans un même segment : http.response.status_code.
• Des unités UCUM explicites dans la métrique (s, By, {request}), jamais dans le nom.
• Les attributs propres à votre domaine dans votre espace de noms : shop.cart.items, jamais dans http.*.

2. Les conventions à connaître #

Ressource, HTTP, bases, messagerie, GenAI.

Ressource #

HTTP (stable) #

Nom de span : {méthode} {route}, par exemple GET /users/{id}, jamais l'URL complète (cardinalité). Métriques : http.server.request.duration et http.client.request.duration, histogrammes en secondes.

Bases de données, messagerie, GenAI #

3. Stabilité et migration #

Les conventions évoluent : s'y préparer.

Versions et schema URL #

Les conventions sont versionnées (v1.26, v1.30…). Chaque instrumentation déclare la version qu'elle suit via une schema URL (https://opentelemetry.io/schemas/1.26.0). Lors de la stabilisation des conventions HTTP, de nombreux attributs ont été renommés (http.method → http.request.method, http.status_code → http.response.status_code).

# Pendant une migration : émettre les anciens ET les nouveaux attributs
export OTEL_SEMCONV_STABILITY_OPT_IN=http/dup     # puis "http" quand les tableaux de bord sont migrés
export OTEL_SEMCONV_STABILITY_OPT_IN=database/dup

Erreur Courante : Une mise à jour d'instrumentation peut renommer des attributs et casser des tableaux de bord ou des alertes. Lisez les notes de version et utilisez le mode dup pendant la transition.

Normaliser dans le Collector #

processors:
  transform/semconv:
    trace_statements:
      - context: span
        statements:
          - set(attributes["http.response.status_code"], attributes["http.status_code"]) where attributes["http.status_code"] != nil
          - delete_key(attributes, "http.status_code")

4. Vos propres conventions #

Étendre sans diverger.

Conventions maison #

• Réutilisez d'abord un attribut standard s'il existe.
• Créez un espace de noms propre à l'entreprise ou au domaine (shop., acme.).
• Documentez chaque attribut (type, unité, exemples, cardinalité attendue) dans un registre versionné.
• Interdisez les attributs à forte cardinalité sur les métriques (identifiants d'utilisateur, URL complètes).

OTel Weaver est l'outil du projet pour décrire un registre de conventions en YAML, le valider, générer de la documentation et des constantes de code, et vérifier que la télémétrie réellement émise respecte le registre.

weaver registry check -r ./mon-registre          # valider le registre
weaver registry generate -r ./mon-registre markdown docs/   # générer la documentation

Vérifier ses données #

Bonne Pratique : Ajoutez à la CI un test qui démarre l'application avec l'exportateur console ou un Collector de test et vérifie la présence de service.name, service.version et des attributs attendus.