TechniqueDécouverte7 min de lecture (+1 technique)
OpenTelemetry de bout en bout
Ce qu'est OpenTelemetry et le trajet d'une étape de trace, de l'application jusqu'au stockage, raconté comme celui d'une lettre. L'explication pour tous, puis une instrumentation Python et une configuration minimale du Collector pour les équipes techniques.
Pour : ingénieurs et SRE · architectes · managers d’équipePrérequis : Avoir lu L'observabilité en 10 minutes ou savoir ce que sont une métrique, un log et une trace. La partie repliée suppose de savoir lire un fichier YAML.
Reprenons le paiement trop lent de L’observabilité en 10 minutes. Dans la trace, une ligne saute aux yeux : l’appel à la banque prend presque quatre secondes. Mais cette ligne ne s’est pas écrite toute seule. Quelque chose l’a produite dans le service payment, l’a emballée, l’a envoyée, l’a triée puis rangée quelque part où l’on a pu la retrouver.
Cette page suit ce trajet, du début à la fin, pour une seule étape de trace : celle de l’appel à la banque. Le standard qui organise tout ce chemin s’appelle OpenTelemetry.
Le trajet d’une lettre
Section intitulée « Le trajet d’une lettre »Pensez à une lettre. Quelqu’un l’écrit. Le bureau de poste la met sous enveloppe, la regroupe avec d’autres et la confie à un transporteur. L’enveloppe a un format standard, que tous les centres de tri savent lire. Le centre de tri vérifie, écarte ce qui ne doit pas partir et oriente chaque lettre vers la bonne boîte. Enfin, la lettre arrive dans une boîte où on la range et où on la relit.
Une étape de trace fait exactement ce chemin. Dans le vocabulaire du métier, cette étape s’appelle un span : un morceau de trace, avec une heure de début, une heure de fin et quelques informations attachées. Voici les correspondances, que la suite de la page détaille une à une :
- écrire la lettre, c’est l’instrumentation, le code qui crée le span ;
- le bureau de poste, c’est le SDK, la bibliothèque qui prépare l’envoi ;
- le format d’enveloppe, c’est OTLP, le protocole de transport ;
- le centre de tri, c’est le Collector ;
- la boîte aux lettres, c’est le stockage, avec son interface de consultation.
Ce qu’est OpenTelemetry
Section intitulée « Ce qu’est OpenTelemetry »OpenTelemetry, souvent abrégé OTel, est un projet open source de la CNCF, la fondation qui héberge aussi Kubernetes et Prometheus. Il est né de la fusion de deux projets antérieurs, OpenTracing et OpenCensus (présentation officielle).
Le point qui surprend le plus souvent : OpenTelemetry n’est pas un outil de stockage ni de visualisation. Il produit et transporte les traces, les métriques et les logs, comme la poste achemine le courrier sans fabriquer les boîtes aux lettres. Le stockage reste au choix : Prometheus, Thanos, Mimir ou VictoriaMetrics pour les métriques, Tempo ou Jaeger pour les traces, Loki ou Elasticsearch pour les logs, ou une solution commerciale.
Le projet regroupe six briques. La spécification est le texte qui dit comment tout doit fonctionner, langage par langage. L’API est l’ensemble des fonctions que le code appelle pour créer un span ou une métrique. Le SDK est la bibliothèque qui met cette API en œuvre : elle échantillonne, regroupe et exporte. OTLP est le protocole de transport commun à tous les signaux. Le Collector est un programme autonome qui reçoit, transforme et réexpédie traces, métriques et logs. Les conventions sémantiques, enfin, sont la liste des noms d’attributs standard et de leur signification.
Le trajet d’un span
Section intitulée « Le trajet d’un span »Voici le chemin complet, tel qu’il apparaît dans la configuration présentée plus bas.
flowchart LR
A["Application<br/>service payment"] -->|"API"| S["SDK<br/>échantillonnage, lots"]
S -->|"OTLP"| R
subgraph COL["Collector"]
R["Receiver<br/>otlp"] --> P["Processors<br/>memory_limiter, batch"] --> E["Exporters"]
end
E -->|"OTLP"| B[("Stockage<br/>des traces")]
E --> D["debug<br/>console"]
1. L’instrumentation crée le span
Section intitulée « 1. L’instrumentation crée le span »Instrumenter, c’est ajouter au programme le code qui produit les traces, les métriques et les logs. On peut le faire de deux façons.
L’instrumentation automatique, dite zero-code, ne demande aucune modification du code. Un agent ou un lanceur se glisse autour des bibliothèques connues (le serveur web, le client HTTP, le pilote de base de données) et crée les spans tout seul. C’est, à mon avis, la meilleure façon de commencer.
L’instrumentation manuelle consiste à appeler l’API dans son propre code. Elle sert à ajouter ce que l’automatique ne peut pas deviner : une étape métier comme l’autorisation du paiement, une information comme le type de carte.
En pratique, on combine les deux. L’automatique donne le squelette de la trace. Le manuel lui donne du sens.
2. Le SDK prépare l’envoi
Section intitulée « 2. Le SDK prépare l’envoi »Le SDK reçoit les spans terminés. Il décide d’abord s’il les garde : c’est l’échantillonnage (sampling), qui permet de ne conserver qu’une partie des traces quand le volume est grand. Il les regroupe ensuite par lots, pour limiter le nombre d’envois. Il y ajoute les attributs de ressource, qui disent quel service les a produits (on y revient plus bas). Puis il les confie à un exportateur, le composant chargé de les envoyer.
3. OTLP transporte
Section intitulée « 3. OTLP transporte »OTLP (OpenTelemetry Protocol) est le format de transport, l’enveloppe standard. Il fonctionne sur gRPC, un protocole d’échange entre programmes (port 4317 par défaut), ou sur HTTP (port 4318) (configuration du Collector). La même enveloppe transporte métriques, logs et traces.
4. Le Collector contrôle
Section intitulée « 4. Le Collector contrôle »Le Collector est le centre de tri. C’est un programme qui se place entre les applications et les stockages. Il a trois sortes de composants.
Les receivers reçoivent les données : le receiver otlp écoute sur les ports 4317 et 4318. Les processors les transforment, dans l’ordre où ils sont listés. Par exemple, memory_limiter refuse des données quand la mémoire approche de sa limite, pour que le Collector ne tombe pas. batch regroupe les données avant l’envoi. Les exporters, enfin, envoient les données vers un ou plusieurs stockages.
Un pipeline relie des receivers, des processors et des exporters pour un type de signal. On écrit un pipeline pour les traces, un autre pour les métriques.
Le Collector n’est pas obligatoire : un SDK peut exporter directement vers un stockage. Je recommande pourtant de l’utiliser dès le départ. C’est l’endroit unique où l’on protège, filtre et oriente les données sans toucher aux applications.
5. Le stockage conserve et affiche
Section intitulée « 5. Le stockage conserve et affiche »Le stockage range les spans par identifiant de trace, le numéro commun à toutes les étapes d’une même requête. L’interface reconstruit ensuite la cascade vue dans la page précédente. L’explorateur de traces montre à quoi ressemble ce résultat.
Qui écrit et dans quelle langue ?
Section intitulée « Qui écrit et dans quelle langue ? »Deux notions reviennent partout. Elles sont simples, mais elles font toute la différence au moment de chercher.
La ressource, c’est l’adresse de l’expéditeur au dos de l’enveloppe. Elle décrit qui émet et elle est attachée une fois pour toutes à tout ce que le service produit : son nom (service.name="payment"), sa version (service.version="1.4.2"), son environnement (deployment.environment.name="dev"). Sans service.name, impossible de savoir quel service a émis un span.
Les conventions sémantiques, c’est la langue commune. Elles fixent le nom et le sens des attributs courants, ces informations attachées à un span (conventions sémantiques). Une requête HTTP porte http.request.method et http.response.status_code. Une route porte http.route. Tout le monde utilise les mêmes noms, quel que soit le langage de programmation.
L’intérêt est concret. Si un service Java et un service Python suivent les conventions, une seule requête retrouve toutes les erreurs HTTP 500 des deux. Si chacun invente ses noms (status, httpCode, code_retour), il faut une requête par équipe.
Ces conventions évoluent encore et certains noms ont changé ces dernières années. Je recommande de fixer la version suivie et de la réviser à chaque montée de version des SDK.
Un exemple minimal
Section intitulée « Un exemple minimal »L’exemple qui suit instrumente un service Python et fait tourner un Collector qui affiche les données reçues dans sa console. Il est replié ci-dessous, pour les équipes qui veulent l’essayer.
Pour les équipes techniques : instrumenter un service Python et configurer le Collector
Instrumenter sans toucher au code. Les commandes viennent de la documentation Python zero-code d’OpenTelemetry. app.py est votre application.
pip install opentelemetry-distro opentelemetry-exporter-otlpopentelemetry-bootstrap -a install
export OTEL_SERVICE_NAME=paymentexport OTEL_RESOURCE_ATTRIBUTES=service.version=1.4.2,deployment.environment.name=devexport OTEL_TRACES_EXPORTER=otlpexport OTEL_METRICS_EXPORTER=otlpexport OTEL_EXPORTER_OTLP_PROTOCOL=grpcexport OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
opentelemetry-instrument python app.pyopentelemetry-bootstrap détecte les bibliothèques installées et ajoute les instrumentations correspondantes. opentelemetry-instrument lance l’application avec ces instrumentations actives. La ressource vient ici des variables OTEL_SERVICE_NAME et OTEL_RESOURCE_ATTRIBUTES.
Ajouter un span métier à la main. Pour voir l’étape « autorisation » dans la trace, avec le type de carte, quelques lignes suffisent :
from opentelemetry import trace
tracer = trace.get_tracer("payment")
def authorize(order): with tracer.start_as_current_span("authorize_payment") as span: span.set_attribute("app.payment.card_type", order.card_type) return call_bank(order)Ce span devient l’enfant du span HTTP créé automatiquement. Le préfixe app. signale un attribut propre à l’application, hors conventions standard.
Configurer le Collector.
receivers: otlp: protocols: grpc: endpoint: 0.0.0.0:4317 http: endpoint: 0.0.0.0:4318
processors: memory_limiter: check_interval: 1s limit_percentage: 80 spike_limit_percentage: 20 batch: {}
exporters: debug: verbosity: detailed # Vers un stockage de traces qui accepte OTLP (Tempo, Jaeger, etc.). otlp_grpc/traces: endpoint: traces-backend:4317 tls: insecure: true # lab uniquement, jamais en production
service: pipelines: traces: receivers: [otlp] processors: [memory_limiter, batch] exporters: [debug, otlp_grpc/traces] metrics: receivers: [otlp] processors: [memory_limiter, batch] exporters: [debug]Pour lire ce fichier :
memory_limitervient en premier : il doit refuser les données avant tout autre traitement.batchvient en dernier, après les processors qui filtrent ou transforment.- L’exportateur
debugaffiche chaque span dans la console du Collector. C’est le moyen le plus simple de vérifier que les données arrivent. - Les versions récentes du Collector nomment l’exportateur OTLP gRPC
otlp_grpcet l’exportateur OTLP HTTPotlp_http. Les anciens nomsotlpetotlphttprestent acceptés comme alias dépréciés : certaines configurations du site les emploient encore. Vérifiez le nom attendu par votre version.
L’adresse 0.0.0.0 écoute sur toutes les interfaces. La documentation du Collector l’utilise par commodité et recommande localhost quand tous les clients sont locaux.
Par où commencer ?
Section intitulée « Par où commencer ? »Si vous partez de zéro, je recommande cet ordre. Lancez l’instrumentation automatique sur un service important, le paiement par exemple, sans toucher au code. Faites passer ses données par un Collector dès le premier jour, avec l’exportateur debug pour vérifier que tout arrive. Donnez à chaque service un nom clair dans sa ressource. Ajoutez ensuite à la main les deux ou trois étapes métier qui comptent. Enfin, écrivez quelque part la version des conventions que vous suivez et désignez qui possède la configuration du Collector.
Pour aller plus loin
Section intitulée « Pour aller plus loin »- Pipeline du Collector animé : activer et désactiver les processors pour voir leur effet.
- Échantillonnage en queue : garder toutes les traces en erreur sans tout stocker.
- Coût du Collector : estimer ce que chaque traitement fait gagner en volume.
- Architecture cliquable : une stack complète, brique par brique.
- SLO et alerting : transformer ces signaux en objectifs et en alertes utiles.
- Le glossaire définit Collector, span, trace et convention sémantique.
- OpenTelemetry, What is OpenTelemetry? : origine du projet, briques et indépendance vis-à-vis des stockages.
- OpenTelemetry, Python zero-code instrumentation : commandes d’installation et de lancement.
- OpenTelemetry, Collector configuration : receivers, processors, exporters, pipelines, ports 4317 et 4318.
- OpenTelemetry, Semantic conventions : noms standard des attributs.