Aller au contenu

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.

Mode de lecture

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.

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.

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.

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"]

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.

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.

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.

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.

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.

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.

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.

Fenêtre de terminal
pip install opentelemetry-distro opentelemetry-exporter-otlp
opentelemetry-bootstrap -a install
export OTEL_SERVICE_NAME=payment
export OTEL_RESOURCE_ATTRIBUTES=service.version=1.4.2,deployment.environment.name=dev
export OTEL_TRACES_EXPORTER=otlp
export OTEL_METRICS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
opentelemetry-instrument python app.py

opentelemetry-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_limiter vient en premier : il doit refuser les données avant tout autre traitement. batch vient en dernier, après les processors qui filtrent ou transforment.
  • L’exportateur debug affiche 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_grpc et l’exportateur OTLP HTTP otlp_http. Les anciens noms otlp et otlphttp restent 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.

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.