Bonnes Pratiques OpenTelemetry (OTel) : Le Guide de l'Observabilité Moderne

Publié le : 05/06/2024 à 11:00 Mis à jour le : 24/07/2026 à 10:18 Vues : 734

1. Adopter les Conventions Sémantiques (Semantic Conventions)

Les Conventions Sémantiques (souvent abrégées en SemConv) sont le dictionnaire commun de l'observabilité. Elles définissent un ensemble de noms de champs (attributs) et de valeurs standardisés pour décrire vos traces, métriques et logs. Adopter ces conventions est sans doute la bonne pratique la plus importante pour garantir que vos données de télémétrie soient cohérentes, exploitables et interopérables.

1.1. Qu'est-ce que SemConv concrètement ?

Imaginez que chaque équipe nomme l'identifiant d'un conteneur différemment : container_id, container.id, ou cid. Il devient impossible pour un outil d'analyse de regrouper ou de filtrer les données de manière fiable. Les conventions sémantiques résolvent ce problème en imposant un nom unique et standardisé : container.id.

Ces standards couvrent une vaste gamme de domaines technologiques :

• Systèmes : host.name, os.type, process.pid...
• Réseau : http.request.method, network.protocol.version, client.address...
• Bases de données : db.system (ex: 'postgresql'), db.statement, db.user...
• Messagerie : messaging.system (ex: 'rabbitmq'), messaging.destination.name...

1.2. Pourquoi est-ce si important de les utiliser ?

• Interopérabilité : Vos données peuvent être envoyées à n'importe quel backend compatible OTel (Jaeger, Prometheus, Dynatrace...) sans modification majeure. Les tableaux de bord et les alertes préconfigurés fonctionneront 'out-of-the-box'.
• Corrélation automatique : Les outils d'analyse peuvent automatiquement lier les traces, métriques et logs si les attributs comme service.name ou host.name sont cohérents.
• Facilité d'analyse : Les équipes n'ont pas à apprendre des conventions de nommage spécifiques à chaque application ou langage. La recherche et le filtrage deviennent intuitifs et unifiés.
• Pérennité : En vous basant sur un standard ouvert, vous évitez d'être dépendant d'un fournisseur (vendor lock-in) et vous vous assurez que votre instrumentation restera pertinente à l'avenir.

Pour une compréhension approfondie du protocole et des spécifications, consultez la session : Le protocole OTLP et les spécifications.

1.3. Exemples et Bonnes Pratiques

• Utilisez les clés standardisées : Avant de créer un attribut, vérifiez toujours si une convention sémantique existe déjà pour la donnée que vous souhaitez tracer (ex: http.request.method, db.system, service.name, host.arch).
• Préfixez vos attributs personnalisés : Si un standard n'existe pas, préfixez vos attributs avec un espace de nom propre à votre organisation ou application (ex: my_app.feature.name, ecommerce.order.id). Cela évite les conflits futurs.
• Enrichissez avec le contexte métier : N'hésitez pas à ajouter des attributs métier pertinents (ex: customer.id, cart.id), mais soyez extrêmement vigilant à ne jamais inclure de données sensibles en clair (voir la section sur le RGPD).

Exemple d'ajout d'attributs dans une Span (pseudo-code Java) :

Span span = tracer.spanBuilder("processOrder").startSpan();
try (Scope scope = span.makeCurrent()) {
    span.setAttribute("ecommerce.order.id", "ORD-12345");
    span.setAttribute("customer.type", "premium");
    // ... votre logique métier ...
} finally {
    span.end();
}

Apprenez l'instrumentation dans les sessions : Auto-instrumentation et Instrumentation manuelle.

2. Architecture

Le OpenTelemetry Collector est un composant essentiel de votre pipeline d'observabilité. Il agit comme un proxy puissant et agnostique, capable de recevoir, traiter et exporter des données de télémétrie. Ne jamais envoyer vos données directement de votre application vers votre backend de stockage.

Comprenez son rôle central ici : Le rôle du Collector et l'architecture du pipeline.

2.1 Patterns de Déploiement

• Agent (Sidecar/DaemonSet) : Déployé sur chaque hôte ou à côté de chaque application. Idéal pour la collecte de métadonnées locales (IP, Hostname, labels Kubernetes) et le prétraitement léger. Il réduit la charge sur l'application en déchargeant l'exportation et le batching.
• Gateway (Centralisé) : Un cluster de collecteurs centraux pour l'agrégation, le filtrage avancé (PII), l'échantillonnage, la mise en cache et l'exportation vers plusieurs destinations simultanément. Il offre une résilience accrue et une gestion centralisée des politiques.

2.2 Composants Clés du Collector

Le Collector est configuré via un fichier YAML et se compose de :

• Receivers : Points d'entrée pour les données (OTLP, Prometheus, Jaeger, Kafka...). Ils définissent comment le Collector reçoit les données.
• Processors : Transforment, filtrent, enrichissent les données (batch, attributes, resourcedetection, memory_limiter, tail_sampling...). Ils sont exécutés séquentiellement.
• Exporters : Envoient les données vers les backends (OTLP, Prometheus, Jaeger, Loki, Dynatrace...). Ils définissent où les données sont envoyées.

Explorez les receivers : Les Receivers et les exporters : Les Exporters. Pour les processeurs, la session Les Processors est essentielle.

2.3 Exemple de Configuration (collector.yaml)

Voici un exemple de configuration pour un collecteur agissant comme agent, avec détection de ressources et envoi par lot. Ce collecteur enverrait ensuite les données à un Gateway Collector ou directement à un backend.

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317 # Écoute sur tous les interfaces pour gRPC
      http:
        endpoint: 0.0.0.0:4318 # Écoute sur tous les interfaces pour HTTP

processors:
  batch:
    send_batch_size: 1000 # Nombre d'éléments à envoyer par lot
    timeout: 10s        # Délai maximal avant d'envoyer un lot incomplet
  resourcedetection:
    detectors: [env, system, k8s, host] # Détecte les ressources de l'environnement, du système, Kubernetes et de l'hôte
    timeout: 2s
    override: true # Écrase les attributs existants si déjà définis par l'instrumentation
    # Configuration spécifique pour Kubernetes
    k8s:
      kubeconfig: ~/.kube/config # Chemin vers le fichier kubeconfig (si nécessaire)
      node_from_env_var: KUBERNETES_NODE_NAME # Variable d'environnement pour le nom du nœud
      extract:
        metadata:
          - k8s.pod.name
          - k8s.namespace.name
          - k8s.deployment.name

exporters:
  otlp:
    endpoint: my-otel-gateway:4317 # Vers un Gateway Collector ou directement le backend final
    tls:
      insecure: true # ATTENTION: À désactiver en production avec un certificat valide pour TLS

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [resourcedetection, batch, memory_limiter]
      exporters: [otlp]
    metrics:
      receivers: [otlp]
      processors: [resourcedetection, batch, memory_limiter]
      exporters: [otlp]
    logs:
      receivers: [otlp]
      processors: [resourcedetection, batch, memory_limiter]
      exporters: [otlp]

3. Stratégies d'Échantillonnage (Sampling)

Le traçage complet peut générer des volumes de données massifs, impactant les performances de votre application (overhead d'instrumentation) et les coûts de stockage de votre backend d'observabilité. L'échantillonnage est crucial pour maîtriser ces volumes tout en conservant une visibilité pertinente pour le diagnostic.

3.1 Types d'Échantillonnage

• Head Sampling (Échantillonnage en amont) : La décision de conserver ou non une trace est prise au début de la trace, sans connaître son issue finale.
  • Probabilistic Sampling : Conserve un pourcentage fixe de traces (ex: 1 trace sur 100). Simple mais peut manquer des traces importantes (erreurs).
  • AlwaysOn/AlwaysOff : Conserve toutes les traces ou aucune. Utile pour le debug ou des environnements de test à très haut volume où l'on ne veut rien conserver.
• Tail Sampling (Échantillonnage en aval) : La décision est prise après la complétion de la trace, permettant de baser la décision sur des attributs finaux (ex: conserver 100% des traces en erreur ou lentes, et seulement un faible pourcentage des succès). C'est la méthode la plus recommandée pour la production car elle garantit la visibilité sur les problèmes.

3.2 Configuration du Tail Sampling (Exemple)

Le Tail Sampling est configuré sur le Gateway Collector, car il nécessite une vue complète de la trace. Voici un extrait de configuration du processeur tail_sampling :

processors:
  tail_sampling:
    decision_wait: 10s # Temps d'attente pour la complétion d'une trace avant de prendre une décision
    num_traces: 100000 # Nombre maximal de traces à conserver en mémoire en attente de décision
    expected_new_traces_per_sec: 100 # Estimation du débit de traces pour allouer les ressources
    policies:
      - name: keep-error-traces
        type: status_code
        status_code: [ERROR, UNSET] # Conserve toutes les traces avec un statut d'erreur ou non défini
        latency: 0s
        parent_error_only: false
        rate_limiting_duration: 0s
      - name: keep-slow-traces
        type: latency
        latency: 500ms # Conserve toutes les traces dont la durée dépasse 500ms
        rate_limiting_duration: 0s
      - name: probabilistic-sampling
        type: probabilistic
        hash_balancing_field: "service.name" # Utilise le nom du service pour une répartition équilibrée
        sampling_percentage: 5 # Conserve 5% des traces restantes (celles qui ne sont ni en erreur, ni lentes)

4. Enrichissement via Resource Detection

Une trace, métrique ou log sans contexte est difficile à analyser. Le processeur resourcedetection enrichit automatiquement vos données avec des attributs décrivant la ressource qui les a générées (application, hôte, conteneur, cloud). Ces attributs sont essentiels pour la corrélation et le filtrage.

4.1 Importance des Attributs de Ressource

• Corrélation : Permet de lier facilement les données de télémétrie à l'infrastructure sous-jacente (ex: voir toutes les traces d'un service sur un hôte spécifique).
• Filtrage : Facilite la recherche et le filtrage par environnement, cluster, namespace, région cloud, etc.
• Contexte : Fournit des informations vitales pour le diagnostic des problèmes et la compréhension de l'environnement d'exécution.

4.2 Configuration du Processeur

Activez le processeur resourcedetection dans vos collecteurs (souvent les agents) pour injecter automatiquement des attributs. Les détecteurs disponibles incluent env (variables d'environnement), system (informations OS), k8s (Kubernetes), host (nom d'hôte).

• Le nom du Cloud Provider (AWS, Azure, GCP).
• Le nom du cluster et du namespace Kubernetes.
• La version du service (service.version) pour faciliter le Release Monitoring.

processors:
  resourcedetection:
    detectors: [env, system, k8s, host] # Liste des détecteurs à activer
    timeout: 5s # Délai maximal pour la détection
    override: true # Écrase les attributs de ressource existants si déjà définis par l'instrumentation
    # Configuration spécifique pour Kubernetes
    k8s:
      kubeconfig: ~/.kube/config # Chemin vers le fichier kubeconfig (si nécessaire)
      node_from_env_var: KUBERNETES_NODE_NAME # Variable d'environnement pour le nom du nœud
      extract:
        metadata:
          - k8s.pod.name
          - k8s.namespace.name
          - k8s.deployment.name

4. Stabilité et Évolution des Conventions Sémantiques

Les conventions sémantiques sont un standard vivant qui évolue avec la technologie. Il est important de comprendre leur cycle de vie pour garantir la pérennité de votre instrumentation.

4.1 Niveaux de Stabilité

Les attributs SemConv ont différents niveaux de maturité :

• Stable : L'attribut est considéré comme final. Son nom ne changera pas, bien que de nouvelles valeurs puissent être ajoutées à ses énumérations. C'est le cas pour la plupart des attributs HTTP, système et de service.
• Expérimental : L'attribut est en cours de développement. Son nom, son type ou sa signification peuvent changer dans les futures versions. Utilisez-les avec prudence en production.
• Déprécié : L'attribut ne doit plus être utilisé et sera supprimé dans une future version. Il est généralement remplacé par un nouvel attribut plus adapté.

Il est crucial de suivre les mises à jour des SDK et du Collector OpenTelemetry pour s'aligner sur les dernières conventions stables.

4.2 Où trouver la liste officielle ?

La source de vérité pour toutes les conventions sémantiques est la documentation officielle d'OpenTelemetry. Gardez ce lien dans vos favoris et consultez-le régulièrement :

Consulter la documentation SemConv

Cette documentation est organisée par domaine (HTTP, base de données, messagerie, etc.) et précise le niveau de stabilité de chaque attribut.

5. Gérer la Cardinalité : Attributs de Ressource vs Attributs de Span

La cardinalité est l'un des défis majeurs de l'observabilité. Elle représente le nombre de valeurs uniques pour un label ou un attribut donné. Une cardinalité élevée peut faire exploser vos coûts de stockage et ralentir vos requêtes. Comprendre la différence entre les attributs de Ressource et les attributs de Span/Log/Métrique est la clé pour la maîtriser.

5.1 Attributs de Ressource : Le Contexte Stable

Un attribut de ressource décrit l'entité qui produit la télémétrie. Il est stable et partagé par tous les signaux (traces, métriques, logs) émis par une instance d'application. Pensez-y comme à l'étiquette d'identité de votre processus.

• Quand l'utiliser ? Pour tout ce qui ne change pas pendant la durée de vie de l'application.
• Exemples : service.name, service.version, host.name, k8s.pod.name, cloud.region.
• Impact sur la cardinalité : Faible. Le nombre de pods, de services ou de versions est généralement limité.

5.2 Attributs de Span/Log/Métrique : Le Contexte Dynamique

Un attribut de span (ou de log/métrique) décrit une opération ou un événement spécifique. Il est dynamique et change à chaque requête ou transaction.

• Quand l'utiliser ? Pour tout ce qui est propre à une seule exécution.
• Exemples : http.request.method, http.route, db.statement, customer.id.
• Impact sur la cardinalité : Potentiellement très élevé. C'est ici que se cache le danger.

5.3 La Règle d'Or pour Maîtriser la Cardinalité

Pour éviter les problèmes, suivez cette règle simple :

Ne mettez jamais d'attributs à cardinalité infinie ou non bornée.

Par exemple, évitez d'utiliser comme attributs :

• Des identifiants uniques par requête : request_id, session_id.
• Des URLs complètes avec des paramètres variables : /users/123, /users/456... Utilisez plutôt des routes paramétrées comme /users/{userId}. L'instrumentation automatique gère souvent cela pour vous, mais soyez vigilant avec l'instrumentation manuelle.
• Des timestamps précis à la nanoseconde.

Si vous avez besoin de tracer ces informations, placez-les dans les événements (Events) d'une span, qui sont conçus pour le diagnostic ponctuel et n'impactent pas (ou peu) l'indexation et la cardinalité globale.

6. Sécurité et Performance (gRPC vs HTTP)

Les conventions sémantiques sont un standard vivant qui évolue avec la technologie. Il est important de comprendre leur cycle de vie pour garantir la pérennité de votre instrumentation.

6.1 gRPC : Le Choix Privilégié

• Privilégiez le protocole gRPC pour la communication entre vos microservices et le collecteur, ainsi qu'entre les collecteurs eux-mêmes.
• Performance : gRPC utilise HTTP/2, le multiplexage et la compression binaire (Protobuf), le rendant significativement plus performant et utilisant moins de bande passante que HTTP/JSON classique.
• Streaming : Supporte le streaming bidirectionnel, idéal pour les flux de données massifs et continus.
• Génération de code : Les stubs clients et serveurs sont générés automatiquement, simplifiant l'intégration.

6.2 Sécurisation des Communications

• Utilisez toujours TLS (Transport Layer Security) pour chiffrer les communications entre vos applications, les collecteurs et les backends. Cela protège vos données en transit contre l'interception.
• Configurez des certificats valides et évitez insecure: true en production.
• Mettez en place une authentification (ex: mTLS, API Keys) pour contrôler l'accès à vos collecteurs et backends.

7. Conformité RGPD et Gestion des Données Sensibles

La collecte de données d'observabilité peut involontairement inclure des informations personnellement identifiables (PII) ou sensibles. La conformité au RGPD (Règlement Général sur la Protection des Données) est primordiale pour éviter les sanctions et protéger la vie privée des utilisateurs.

7.1 Minimisation des Données (Data Minimization)

• Collectez uniquement ce qui est nécessaire : Avant d'instrumenter, définissez clairement les données dont vous avez besoin pour l'observabilité et évitez de collecter des informations superflues (ex: ne pas tracer les requêtes GET avec des paramètres sensibles dans l'URL si ce n'est pas indispensable).
• Filtrez à la source : Utilisez les processeurs du Collector pour supprimer les attributs non essentiels ou les logs verbeux dès l'ingestion.

7.2 Masquage et Obfuscation des PII

Les informations personnellement identifiables (PII) ne doivent jamais être stockées en clair dans votre système d'observabilité. Le Collector OpenTelemetry offre des processeurs puissants pour gérer cela.

• Utilisez le processeur attributes du Collector pour masquer, supprimer ou hacher les champs contenant des PII (adresses IP, noms d'utilisateur, emails, numéros de carte de crédit, etc.).
• Exemple de configuration pour masquer des données sensibles :

processors:
  attributes:
    actions:
      # Supprime l'en-tête X-Forwarded-For qui peut contenir des IPs
      - key: http.request.header.x-forwarded-for
        action: delete
      # Hashe l'adresse IP du client pour l'anonymiser
      - key: client.ip
        action: hash
      # Masque l'email de l'utilisateur avec un jeton générique
      - key: user.email
        action: mask_with_token
        token: "[REDACTED_EMAIL]"
      # Remplace les numéros de carte de crédit par un pattern
      - key: credit_card.number
        action: replace_all_matches
        regex: "\\d{13,16}"
        new_value: "[CARD_NUMBER_REDACTED]"

Pour plus de détails sur la transformation et le filtrage des signaux, consultez la session : Les Processors : Transformer et filtrer les signaux.

7.3 Rétention des Données

• Définissez des politiques de rétention claires et documentées pour vos données de télémétrie. Les données d'observabilité n'ont pas toutes la même durée de vie légale ou opérationnelle.
• Configurez votre backend de stockage pour archiver ou supprimer automatiquement les données après la période nécessaire, conformément à vos politiques internes et aux exigences légales.

7.4 Contrôle d'Accès (RBAC) et Audit

• Assurez-vous que votre backend d'observabilité dispose d'un contrôle d'accès granulaire (RBAC - Role-Based Access Control) pour limiter qui peut voir quelles données.
• Les équipes ne devraient avoir accès qu'aux données pertinentes pour leur périmètre et leur rôle.
• Mettez en place des journaux d'audit pour suivre qui accède à quelles données sensibles au sein de votre plateforme d'observabilité.