[Artículo] Los conceptos fundamentales de 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.

OpenTelemetry fournit	OpenTelemetry ne fournit pas
une spécification, des API et des SDK pour une dizaine de langages	une base de données de télémétrie
le protocole OTLP	des tableaux de bord ou un moteur d'alertes
le Collector (réception, traitement, export)	un outil d'analyse : c'est le rôle de Grafana, Jaeger, Elastic, Datadog, Dynatrace…
les conventions sémantiques (noms communs des attributs)

Les quatre signaux #

Les signaux OpenTelemetry — Tous les signaux d'un même service portent la même ressource, ce qui permet de les relier.

Signal	Répond à	Statut de la spécification
Traces	par où est passée cette requête et où a-t-elle perdu du temps ?	stable
Métriques	combien, à quelle vitesse, est-ce normal ?	stable
Logs	que s'est-il passé exactement à cet instant ?	stable (modèle de données et SDK)
Profils	quelle fonction consomme le CPU ou la mémoire ?	en développement (alpha)

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 #

API, SDK et exportateurs — Une bibliothèque instrumentée avec l'API ne coûte rien tant que l'application n'installe pas de 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 #

Notion	Décrit	Exemples
Ressource	l'entité qui produit la télémétrie : identique pour tous les signaux d'un processus	`service.name`, `service.version`, `deployment.environment.name`, `host.name`, `k8s.pod.name`
Instrumentation scope	la bibliothèque qui a produit une donnée	`opentelemetry.instrumentation.flask` 0.48b0, ou le nom de votre module
Attributs	le contexte propre à une donnée	`http.request.method`, `http.response.status_code`, `db.system.name`

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é #

Niveau	Signification	En production
Development / Experimental	peut changer ou disparaître sans préavis	à éviter, ou isoler
Alpha	fonctionnel, API encore susceptible de changer	pour les pionniers
Beta	proche de la stabilité, changements rares	avec prudence
Stable	compatibilité garantie	oui

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.

Los conceptos fundamentales de OpenTelemetry