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
Instrumenter ses applications pour Jaeger avec OpenTelemetry
Envoyer des traces à Jaeger avec OpenTelemetry : auto-instrumentation (Java, Python, Node.js), SD...
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...
Variables d'environnement de Grafana Alloy : GOMEMLIMIT, sys.env et OTEL_RESOURCE_ATTRIBUTES
Quelles variables Grafana Alloy lit-il vraiment ? GOMEMLIMIT, HTTP_PROXY, sys.env, OTEL_RESOURCE_...
OpenTelemetry Collector : les Processors (transformer, filtrer et protéger la télémétrie)
Maîtriser les processors du Collector OpenTelemetry : batch, memory_limiter, attributes, resource...
La télémétrie dans ClickHouse : schéma, SQL, vues matérialisées et rétention
La télémétrie dans ClickHouse : tables otel_logs, otel_traces, otel_metrics_* et hyperdx_sessions...
OpenTelemetry Collector, Grafana Alloy et Bindplane : comparer trois approches des pipelines de télémétrie
Comparatif détaillé de trois façons de gérer des pipelines de télémétrie : l'OpenTelemetry Collec...
Les métriques OpenTelemetry : instruments, temporalité, histogrammes et exemplars
Maîtriser le signal métrique : MeterProvider, instruments synchrones et asynchrones (Counter, UpD...
Les logs avec OpenTelemetry : modèle de données, appenders, corrélation et collecte
Maîtriser le signal log : modèle de données LogRecord, Logs Bridge API et appenders (Logback, Log...
Les profils, le quatrième signal d'OpenTelemetry : profilage continu et corrélation avec les traces
Comprendre le nouveau signal profile d'OpenTelemetry : profilage continu, flame graphs, modèle de...