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 danshttp.*.
2. Les conventions à connaître #
Ressource, HTTP, bases, messagerie, GenAI.
Ressource #
| Attribut | Exemple | Remarque |
|---|---|---|
service.name | checkout | obligatoire |
service.version | 1.4.0 | relier un incident à une version |
service.namespace | shop | regrouper des services |
service.instance.id | uuid du processus | distinguer les instances |
deployment.environment.name | production | remplace deployment.environment |
host.name, container.id, k8s.pod.name, k8s.namespace.name | ajoutés par les détecteurs de ressource et k8sattributes |
HTTP (stable) #
| Attribut | Exemple |
|---|---|
http.request.method | GET |
http.route | /users/{id} |
http.response.status_code | 503 |
url.full (client) / url.path (serveur) | https://api/users/42 |
server.address, server.port | api.example.com, 443 |
error.type | 503, timeout, java.net.UnknownHostException |
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 #
| Domaine | Attributs clés | Maturité |
|---|---|---|
| Bases de données | db.system.name, db.namespace, db.collection.name, db.operation.name, db.query.text (paramètres masqués) | stable pour les attributs de base |
| Messagerie | messaging.system, messaging.destination.name, messaging.operation.type (send, receive, process) | en cours de stabilisation |
| RPC / gRPC | rpc.system, rpc.service, rpc.method | en développement |
| GenAI | gen_ai.operation.name, gen_ai.request.model, gen_ai.usage.input_tokens | en développement (voir OpenInference) |
| Exceptions | exception.type, exception.message, exception.stacktrace | stable |
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/dupErreur 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 documentationVé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 deservice.name,service.versionet des attributs attendus.
Mon suivi
Connectez-vous pour suivre votre progression et prendre des notes. Se connecter
💬 Discussions récentes de la formation
- Quels attributs utiliser pour nommer mes spans HTTP (semconv) ?✓ résolu · 1 réponse(s)
- OpenTelemetry Collector : mes traces arrivent mais pas mes métriques✓ résolu · 2 réponse(s)
Poser une question sur cette leçon →Voir toutes les discussions de la formation
Articles recommandés
OpenInference : les conventions OpenTelemetry pour tracer les applications d'IA
Guide détaillé d'OpenInference : conventions sémantiques et instrumentations OpenTelemetry pour L...
Bonnes Pratiques OpenTelemetry (OTel) : Le Guide de l'Observabilité Moderne
Maîtrisez OpenTelemetry grâce à nos conseils d'experts : implémentation du Collector, respect des...
OpenTelemetry : Instrumentation Automatique vs Manuelle
Comprenez les différences entre l'instrumentation automatique et manuelle avec OpenTelemetry, leu...
Les concepts fondamentaux d'OpenTelemetry : signaux, ressources, contexte et maturité
Le vocabulaire indispensable d'OpenTelemetry : les quatre signaux, API et SDK, ressource et instr...
Les traces OpenTelemetry en profondeur : spans, statuts, événements, liens et échantillonnage
Maîtriser le signal trace : anatomie d'une trace distribuée, span et SpanKind, attributs, statut ...
OTLP expliqué : comprendre le protocole OpenTelemetry
Découvrez le protocole OTLP expliqué simplement. Comprendre les différences entre gRPC et HTTP po...
Corréler traces, métriques, logs et profils avec OpenTelemetry
Relier les quatre signaux pour diagnostiquer vite : ressource commune, trace_id dans les logs, ex...
OpenTelemetry Collector : les Exporters (envoyer la télémétrie vers les backends)
Configurer les exporters du Collector OpenTelemetry : OTLP gRPC/HTTP, Prometheus, prometheusremot...
Collector OpenTelemetry : connecteurs, extensions et observabilité du Collector
Aller plus loin avec le Collector : connecteurs (spanmetrics, servicegraph, count, routing, failo...