Les SDK OpenTelemetry partagent un ensemble commun de variables d’environnement ; la même configuration fonctionne donc pour Java, Python, Node.js, .NET et d’autres. C’est la manière la plus courante de configurer une application, et elle convient parfaitement aux conteneurs et à Kubernetes, puisque la plateforme définit l’environnement. Ce guide couvre les variables que vous utiliserez le plus.

Chaque SDK de langage implémente la spécification à son propre rythme ; vérifiez donc les variables moins courantes dans la documentation de votre langage.

L’essentiel

export OTEL_SERVICE_NAME=checkout
export OTEL_RESOURCE_ATTRIBUTES=service.version=1.4.2,deployment.environment.name=staging
export OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf

• OTEL_SERVICE_NAME définit service.name, l’attribut le plus important, car les backends regroupent tout selon celui-ci. S’il n’est pas défini, vous obtenez un nom unknown_service. Il a priorité sur service.name dans OTEL_RESOURCE_ATTRIBUTES.
• OTEL_RESOURCE_ATTRIBUTES est une liste séparée par des virgules de paires key=value décrivant le service, comme sa version et son environnement.
• OTEL_EXPORTER_OTLP_ENDPOINT est la destination de la télémétrie. Faites-le pointer vers un Collector.
• OTEL_EXPORTER_OTLP_PROTOCOL vaut grpc, http/protobuf ou http/json.

Endpoints et protocoles : le port doit correspondre

Les valeurs par défaut sont http://localhost:4318 pour HTTP et http://localhost:4317 pour gRPC. Pour les protocoles HTTP, le SDK ajoute v1/traces, v1/metrics et v1/logs à l’endpoint de base. Si vous définissez un endpoint par signal, comme OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, il est utilisé tel quel, sans rien ajouter.

L’erreur la plus courante est l’incohérence : envoyer du gRPC vers le port 4318 ou du HTTP vers le port 4317. Choisissez le protocole et le port ensemble. Le protocole par défaut dans la spécification est http/protobuf, mais certains SDK utilisent gRPC par défaut ; définissez-le donc explicitement.

Sélection de l’exporter

export OTEL_TRACES_EXPORTER=otlp      # par défaut
export OTEL_METRICS_EXPORTER=otlp     # par défaut
export OTEL_LOGS_EXPORTER=otlp        # par défaut

Les valeurs incluent otlp, console (affiche dans le terminal, pratique pour déboguer) et none pour désactiver un signal. Certains langages en prennent en charge d’autres, comme prometheus pour les métriques ou zipkin pour les traces.

Options de l’exporter OTLP

export OTEL_EXPORTER_OTLP_HEADERS="authorization=Bearer abc123,x-tenant=team-a"
export OTEL_EXPORTER_OTLP_TIMEOUT=10000       # millisecondes dans la plupart des SDK
export OTEL_EXPORTER_OTLP_COMPRESSION=gzip
export OTEL_EXPORTER_OTLP_CERTIFICATE=/etc/ssl/ca.pem
export OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE=/etc/ssl/client.pem
export OTEL_EXPORTER_OTLP_CLIENT_KEY=/etc/ssl/client.key

Chacune de ces variables possède des variantes par signal, comme OTEL_EXPORTER_OTLP_TRACES_TIMEOUT ou OTEL_EXPORTER_OTLP_METRICS_ENDPOINT, qui ont priorité sur la variable de base. HEADERS est une liste séparée par des virgules de paires key=value, et toutes les valeurs sont des chaînes. Utilisez un endpoint https:// pour TLS, et les variables de certificat pour les autorités de certification privées ou le TLS mutuel.

Propagation et échantillonnage

export OTEL_PROPAGATORS=tracecontext,baggage    # par défaut
export OTEL_TRACES_SAMPLER=parentbased_traceidratio
export OTEL_TRACES_SAMPLER_ARG=0.1

• OTEL_PROPAGATORS détermine quels en-têtes transportent le contexte de trace entre les services. La valeur par défaut est tracecontext,baggage (W3C). Tous les services d’un chemin de requête doivent utiliser des propagators compatibles, sinon les traces se brisent à la frontière. N’ajoutez b3 ou d’autres que lorsque vous devez interopérer avec des systèmes plus anciens.
• OTEL_TRACES_SAMPLER vaut par défaut parentbased_always_on, qui enregistre tout et suit la décision de l’appelant. Pour l’échantillonnage en tête (head sampling), parentbased_traceidratio avec OTEL_TRACES_SAMPLER_ARG=0.1 conserve environ dix pour cent des nouvelles traces tout en respectant la décision d’un parent. Le guide sur l’échantillonnage explique quand échantillonner plutôt dans le Collector.

Batching et limites

Les paramètres de batch contrôlent l’utilisation de la mémoire et la fréquence d’export. Valeurs par défaut de la spécification :

Variable	Valeur par défaut
OTEL_BSP_SCHEDULE_DELAY	5000 ms
OTEL_BSP_MAX_QUEUE_SIZE	2048
OTEL_BSP_MAX_EXPORT_BATCH_SIZE	512
OTEL_BSP_EXPORT_TIMEOUT	30000 ms
OTEL_BLRP_SCHEDULE_DELAY	1000 ms
OTEL_METRIC_EXPORT_INTERVAL	60000 ms
OTEL_ATTRIBUTE_COUNT_LIMIT	128
OTEL_SPAN_EVENT_COUNT_LIMIT	128

BSP est le batch processor de spans et BLRP le batch processor d’enregistrements de logs. Augmentez la taille de la file d’attente si vous constatez des spans perdus sous charge, et réduisez l’intervalle des métriques pendant les tests (par exemple 10000) pour ne pas attendre une minute pour obtenir un point de données.

Interrupteurs opérationnels

export OTEL_SDK_DISABLED=true     # désactive la télémétrie sans retirer l'instrumentation
export OTEL_LOG_LEVEL=debug       # niveau de log de diagnostic du SDK lui-même (info par défaut)

OTEL_SDK_DISABLED est un interrupteur d’urgence rapide. Les logs de debug sont verbeux ; ne les laissez pas activés en production.

Mise en place dans Docker Compose et Kubernetes

Compose :

services:
  checkout:
    image: myorg/checkout:1.4.2
    environment:
      OTEL_SERVICE_NAME: checkout
      OTEL_RESOURCE_ATTRIBUTES: service.version=1.4.2,deployment.environment.name=staging
      OTEL_EXPORTER_OTLP_ENDPOINT: http://otel-collector:4318
      OTEL_EXPORTER_OTLP_PROTOCOL: http/protobuf
      OTEL_TRACES_SAMPLER: parentbased_traceidratio
      OTEL_TRACES_SAMPLER_ARG: "0.25"

Kubernetes :

env:
  - name: OTEL_SERVICE_NAME
    value: checkout
  - name: OTEL_EXPORTER_OTLP_ENDPOINT
    value: http://otel-collector.observability.svc.cluster.local:4318
  - name: OTEL_RESOURCE_ATTRIBUTES
    value: k8s.pod.name=$(POD_NAME),deployment.environment.name=staging
  - name: POD_NAME
    valueFrom:
      fieldRef:
        fieldPath: metadata.name

Le guide sur l’Operator montre comment injecter automatiquement ces variables, avec une ressource Instrumentation, afin que les équipes applicatives n’aient pas à les définir à la main.

Ordre de priorité et pièges

• La configuration dans le code l’emporte généralement sur les variables d’environnement, et les variables par signal l’emportent sur les variables générales.
• Une variable non reconnue par votre SDK est silencieusement ignorée. Consultez la page de configuration du langage lorsqu’un paramètre semble n’avoir aucun effet.
• Ne mettez pas de secrets dans OTEL_RESOURCE_ATTRIBUTES. Cela devient une étiquette sur chaque élément de télémétrie.
• Lorsqu’un endpoint contient un chemin (par exemple derrière un proxy), utilisez les variables d’endpoint par signal afin que rien ne soit ajouté.
• Gardez la liste des variables en un seul endroit par service (un fichier Compose ou un fichier de values Helm), afin que les changements soient relus.

Pour la liste complète, consultez la spécification des variables d’environnement du SDK et la configuration de l’exporter OTLP.