OpenTelemetry

Configurer les SDK avec un fichier YAML déclaratif

Utilisez un seul fichier YAML avec OTEL_CONFIG_FILE à la place de dizaines de variables d'environnement, lorsque votre SDK le prend en charge.

10 min Intermédiaire

Les variables d’environnement fonctionnent bien pour une poignée de paramètres, mais elles deviennent difficiles à manier lorsque vous avez besoin de plusieurs exporters, de processors personnalisés ou de règles d’échantillonnage. La configuration déclarative les remplace par un seul fichier YAML qui décrit l’ensemble du SDK : la resource, les propagators, et les providers de tracer, de meter et de logger. Le schéma a atteint une version stable en 2026, ce qui signifie que vous pouvez vous appuyer dessus en toute sécurité. La prise en charge dans chaque SDK reste toutefois inégale ; lisez donc la section sur l’état d’avancement avant de l’adopter.

L’activer

Enregistrez un fichier et faites pointer le SDK vers lui avec une seule variable d’environnement :

export OTEL_CONFIG_FILE=/etc/otel/otel-config.yaml

Lorsque OTEL_CONFIG_FILE est défini, un SDK qui prend en charge la configuration déclarative se construit à partir du fichier. Les autres variables OTEL_* sont alors ignorées, sauf si le fichier les référence, comme décrit plus bas.

Un exemple complet

otel-config.yaml :

file_format: "1.2"

resource:
  attributes_list: ${OTEL_RESOURCE_ATTRIBUTES}
  detection/development:
    detectors:
      - service:
      - host:
      - process:
      - container:

propagator:
  composite:
    - tracecontext:
    - baggage:

tracer_provider:
  sampler:
    parent_based:
      root:
        always_on:
  processors:
    - batch:
        exporter:
          otlp_http:
            endpoint: ${OTEL_EXPORTER_OTLP_ENDPOINT:-http://localhost:4318}/v1/traces

meter_provider:
  readers:
    - periodic:
        exporter:
          otlp_http:
            endpoint: ${OTEL_EXPORTER_OTLP_ENDPOINT:-http://localhost:4318}/v1/metrics

logger_provider:
  processors:
    - batch:
        exporter:
          otlp_http:
            endpoint: ${OTEL_EXPORTER_OTLP_ENDPOINT:-http://localhost:4318}/v1/logs

Utilisez la valeur de file_format que précise la documentation de votre SDK, car les SDK adoptent les nouvelles versions du schéma à des moments différents. Comment lire le fichier :

resource décrit le service. attributes_list prend la chaîne habituelle key=value,key=value, et les detectors ajoutent automatiquement des informations sur l’hôte, le processus et le conteneur. Les propriétés se terminant par /development sont encore expérimentales et peuvent ne pas exister dans tous les SDK.
propagator liste les propagators de contexte, ici le contexte de trace W3C et le baggage.
tracer_provider contient le sampler et les span processors. Ici, un batch processor envoie les spans via un exporter OTLP HTTP.
meter_provider contient les metric readers. Un reader periodic exporte à intervalle régulier.
logger_provider fait de même pour les logs.
otlp_http vs otlp_grpc : changez le nom de l’exporter et l’endpoint (http://localhost:4317 pour gRPC) pour changer de protocole.

Substitution de variables d’environnement

Dans le fichier, ${VAR} lit une variable d’environnement et ${VAR:-default} fournit une valeur par défaut lorsqu’elle n’est pas définie. Les variables d’environnement sont par ailleurs ignorées, et c’est voulu : rien ne change de comportement à moins que le fichier ne le demande. Il est ainsi facile de voir ce qui est configurable par environnement :

resource:
  attributes_list: ${OTEL_RESOURCE_ATTRIBUTES}

tracer_provider:
  processors:
    - batch:
        exporter:
          otlp_http:
            endpoint: ${OTEL_EXPORTER_OTLP_TRACES_ENDPOINT:-http://localhost:4318/v1/traces}

Le même fichier fonctionne alors en développement (valeurs par défaut) et en production (la plateforme définit les variables).

Destinations par signal et configurations plus riches

La configuration déclarative brille pour ce que les variables d’environnement expriment mal, comme envoyer les mêmes spans à deux endroits ou régler un processor :

tracer_provider:
  processors:
    - batch:
        schedule_delay: 2000
        max_queue_size: 4096
        exporter:
          otlp_http:
            endpoint: http://collector:4318/v1/traces
    - simple:
        exporter:
          console:

Ici, les spans vont vers un Collector par lots et s’affichent aussi dans la console, ce qui est utile pour le débogage en local. Consultez la documentation de votre SDK pour connaître les noms de propriétés exacts qu’il prend en charge, car les processors, samplers et exporters disponibles dépendent de l’implémentation.

Quels langages la prennent en charge

La spécification et le schéma sont stables, mais chaque langage les implémente selon son propre calendrier :

Disponible : C++, Go, Java, JavaScript et PHP disposent d’implémentations, et l’agent Java documente sa propre mise en place.
En développement : .NET et Python.
La documentation décrit encore la prise en charge à travers les implémentations comme expérimentale ; traitez donc cette fonctionnalité comme une fonctionnalité à tester pour votre langage avant de dépendre d’elle.
Le Collector lui-même utilise l’implémentation Go pour configurer sa télémétrie interne.

Si votre langage n’est pas prêt, continuez à utiliser les variables d’environnement. Les deux modèles sont volontairement compatibles : les noms de variables montrés dans les exemples de substitution sont les mêmes que ceux que vous utiliseriez sans fichier.

Choisir entre les deux

Utilisez les variables d’environnement quand	Utilisez un fichier déclaratif quand
Vous définissez quelques options par service	Vous avez besoin de plusieurs exporters ou processors
Votre plateforme injecte déjà l’environnement (Operator, Helm)	Vous voulez que toute la configuration du SDK soit relue dans un seul fichier
La prise en charge déclarative de votre langage est absente ou immature	Vous voulez le même format de configuration pour plusieurs langages

Un hybride raisonnable consiste à monter un fichier partagé depuis un ConfigMap et à laisser les variables d’environnement ne fournir que les valeurs propres à chaque environnement via la substitution ${...}.

Livrer le fichier

Docker Compose :

services:
  checkout:
    image: myorg/checkout:1.4.2
    environment:
      OTEL_CONFIG_FILE: /etc/otel/otel-config.yaml
      OTEL_EXPORTER_OTLP_ENDPOINT: http://otel-collector:4318
      OTEL_RESOURCE_ATTRIBUTES: service.version=1.4.2,deployment.environment.name=staging
    volumes:
      - ./otel-config.yaml:/etc/otel/otel-config.yaml:ro

Kubernetes : placez le fichier dans un ConfigMap, montez-le et définissez OTEL_CONFIG_FILE dans le Deployment. Une modification du ConfigMap dans Git se déploie alors comme n’importe quelle autre modification, mais les SDK lisent le fichier au démarrage ; redémarrez donc les pods pour la prendre en compte.

Pièges

Une erreur dans le fichier peut empêcher le SDK de démarrer ses providers. Testez-le dans un environnement de pré-production, et surveillez la sortie de log du SDK au démarrage (OTEL_LOG_LEVEL=debug temporairement).
Ne mettez pas de secrets directement dans le fichier. Utilisez ${VAR} et injectez la valeur depuis un Secret.
La reconfiguration dynamique à l’exécution ne fait pas encore partie de cette spécification. Modifier le fichier exige un redémarrage.
Certaines variables d’environnement sont prévues pour être dépréciées car elles interopèrent mal, même si déprécié ne signifie pas supprimé.

Pour le schéma complet et les notes par langage, consultez la documentation sur la configuration déclarative.

RackMint