Les concepts fondamentaux d'OpenTelemetry

1. Une seule norme pour la télémétrie #

D'où vient OpenTelemetry et ce qu'il standardise.

Origines #

OpenTelemetry (OTel) naît en 2019 de la fusion de deux projets concurrents, OpenTracing et OpenCensus. Hébergé par la CNCF, il est devenu le deuxième projet le plus actif de la fondation après Kubernetes. Il ne stocke ni n'affiche rien : il standardise la production et le transport de la télémétrie, que l'on envoie ensuite vers le backend de son choix.

Les quatre signaux #

Le baggage complète ces signaux : des paires clé-valeur propagées d'un service à l'autre (identifiant de client, de locataire) que chaque service peut lire et ajouter à sa télémétrie.

2. Les briques #

API, SDK, ressource, scope et contexte.

API et SDK #

Cette séparation permet aux auteurs de bibliothèques (frameworks web, clients HTTP, pilotes de bases) d'instrumenter leur code une fois pour toutes, sans imposer de backend ni de dépendance lourde à leurs utilisateurs.

Ressource et instrumentation scope #

Erreur Courante : Sans service.name, les SDK utilisent unknown_service : vos données deviennent introuvables. C'est le premier attribut à définir.

Contexte et propagation #

Le contexte transporte l'identifiant de trace et de span actifs à l'intérieur d'un processus ; la propagation le transmet d'un processus à l'autre (en-tête HTTP traceparent, métadonnées gRPC, en-têtes de messages Kafka). C'est ce qui permet d'assembler une trace distribuée et de relier les logs et les métriques à la trace qui les a produits.

3. Configurer #

Variables d'environnement et configuration déclarative.

Variables OTEL_* #

Tous les SDK partagent les mêmes variables d'environnement : une application se configure de la même façon quel que soit son langage.

export OTEL_SERVICE_NAME=checkout
export OTEL_RESOURCE_ATTRIBUTES=service.version=1.4.0,deployment.environment.name=production
export OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_TRACES_EXPORTER=otlp OTEL_METRICS_EXPORTER=otlp OTEL_LOGS_EXPORTER=otlp
export OTEL_TRACES_SAMPLER=parentbased_traceidratio OTEL_TRACES_SAMPLER_ARG=0.2
export OTEL_PROPAGATORS=tracecontext,baggage

Bonne Pratique : En développement, OTEL_TRACES_EXPORTER=console affiche les spans dans le terminal : le moyen le plus rapide de vérifier une instrumentation.

Configuration déclarative #

Pour les cas complexes (plusieurs exportateurs, vues de métriques, échantillonneurs composés), OpenTelemetry définit un fichier de configuration YAML commun à tous les SDK, désigné par une variable d'environnement (OTEL_CONFIG_FILE, anciennement OTEL_EXPERIMENTAL_CONFIG_FILE). Sa prise en charge varie selon les langages : vérifiez la documentation de votre SDK.

4. Lire la maturité #

Ne pas confondre stable et expérimental.

Niveaux de stabilité #

La maturité se lit par signal, par langage et par composant : les traces Java sont stables depuis longtemps, les logs d'un autre langage peuvent être encore en bêta, un receiver du Collector peut être en alpha. Les pages « Status » de opentelemetry.io et le fichier metadata.yaml de chaque composant du Collector font foi.

À savoir : Les numéros de version des paquets d'instrumentation se terminant par b0 (Python) ou -alpha (Java) signalent des conventions sémantiques encore non stables pour cette bibliothèque.