Este artículo está disponible en francés.
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.
Mi seguimiento
Inicia sesión para seguir tu progreso y tomar notas. Iniciar sesión
💬 Debates recientes del curso
- Quels attributs utiliser pour nommer mes spans HTTP (semconv) ?✓ resuelto · 1 respuesta(s)
- OpenTelemetry Collector : mes traces arrivent mais pas mes métriques✓ resuelto · 2 respuesta(s)
Hacer una pregunta sobre esta lección →Ver todos los debates del curso
Artículos recomendados
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 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...
Les concepts fondamentaux d'OpenTelemetry : signaux, ressources, contexte et maturité
Le vocabulaire indispensable d'OpenTelemetry : les quatre signaux, API et SDK, ressource et instr...
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...
Grafana Alloy vs OpenTelemetry Collector : Lequel choisir ?
Comparaison détaillée entre Grafana Alloy et l'OpenTelemetry Collector. Découvrez les avantages, ...