RousselTMLEARNING

Artículo · OpenTelemetry: del descubrimiento a la experiencia

Las convenciones semánticas (semconv)

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 #

Avant et après les conventions
Les outils d'analyse peuvent reconnaître une requête HTTP ou une requête SQL sans configuration.

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 #

AttributExempleRemarque
service.namecheckoutobligatoire
service.version1.4.0relier un incident à une version
service.namespaceshopregrouper des services
service.instance.iduuid du processusdistinguer les instances
deployment.environment.nameproductionremplace deployment.environment
host.name, container.id, k8s.pod.name, k8s.namespace.nameajoutés par les détecteurs de ressource et k8sattributes

HTTP (stable) #

AttributExemple
http.request.methodGET
http.route/users/{id}
http.response.status_code503
url.full (client) / url.path (serveur)https://api/users/42
server.address, server.portapi.example.com, 443
error.type503, 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 #

DomaineAttributs clésMaturité
Bases de donnéesdb.system.name, db.namespace, db.collection.name, db.operation.name, db.query.text (paramètres masqués)stable pour les attributs de base
Messageriemessaging.system, messaging.destination.name, messaging.operation.type (send, receive, process)en cours de stabilisation
RPC / gRPCrpc.system, rpc.service, rpc.methoden développement
GenAIgen_ai.operation.name, gen_ai.request.model, gen_ai.usage.input_tokensen développement (voir OpenInference)
Exceptionsexception.type, exception.message, exception.stacktracestable

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
Cycle d'un registre de conventions
Le registre versionné devient la référence commune des équipes.

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.

📄 Les conventions sémantiques OpenTelemetry (semconv) : nommer la télémétrie →

Mi seguimiento

  • ⏱ Duración estimada : ≈ 6 min

Inicia sesión para seguir tu progreso y tomar notas. Iniciar sesión

💬 Debates recientes del curso

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...

Apoyar

♥ APOYAR

Apoya RousselTM Learning

Los cursos, artículos, prácticas y certificados siguen siendo gratuitos y sin publicidad intrusiva. Una contribución libre, por el importe que elijas, financia el alojamiento, los entornos de prácticas y nuevos contenidos.

Contribuir con PayPal Importe libre · tarjeta o cuenta PayPalMás información
QR code PayPal
O escanea este código QR con tu teléfono

¡Gracias, cada contribución cuenta!