Implémenter OpenTelemetry dans tes projets
Traces, métriques, logs : un seul protocole. Le chemin concret pour passer à OpenTelemetry, Collector et sampling compris.
Le jour où tes logs ne suffisent plus
Une requête met 2,4 secondes en production. Tu ouvres les logs : la ligne « checkout ok » est là, timestampée, rassurante. Elle ne dit pas que 1,8 seconde s'est passée dans un appel HTTP vers le service de paiement, ni que ce service attendait un verrou Postgres.
Les logs racontent des événements isolés. Une trace raconte le trajet. C'est toute la différence entre constater une lenteur et la localiser.
OpenTelemetry existe pour ça : un standard ouvert porté par la CNCF qui décrit comment produire, transporter et exporter traces, métriques et logs avec un vocabulaire commun. L'instrumentation n'appartient plus au vendor. Tu changes de backend sans retoucher une ligne applicative.
Trois signaux, un seul protocole
Avant d'écrire du code, il faut savoir ce que tu collectes. Les trois signaux ne répondent pas aux mêmes questions et ne coûtent pas la même chose.
| Signal | Question à laquelle il répond | Coût | Exemple concret |
|---|---|---|---|
| Traces | Où passe le temps d'une requête ? | élevé (volume + rétention) | 1,8 s dans un appel SQL sur orders |
| Métriques | Comment évolue le système dans le temps ? | faible | p95 de latence, taux d'erreur 5xx |
| Logs | Que s'est-il passé exactement à cet instant ? | moyen | stack trace d'une exception 500 |
Le ciment entre les trois, c'est le contexte : un trace_id partagé. Un log qui porte le trace_id de la requête devient cliquable depuis la waterfall. Sans ce lien, tu gardes trois silos et trois façons de chercher.
Le Collector, la pièce que tout le monde oublie
La tentation du premier jour : exporter directement depuis l'application vers le backend. Ça marche, et ça te condamne. Chaque changement de backend, chaque ajout de filtre, chaque modification de rétention devient une release applicative.
Le Collector est un process intermédiaire qui reçoit en OTLP, transforme, filtre, échantillonne et réexporte. L'application parle un seul protocole. Tout le reste est de la configuration, déployable indépendamment.
receivers:
otlp:
protocols:
grpc:
endpoint: 0.0.0.0:4317
http:
endpoint: 0.0.0.0:4318
processors:
memory_limiter:
check_interval: 1s
limit_mib: 400
batch:
timeout: 5s
send_batch_size: 8192
resource:
attributes:
- key: deployment.environment.name
value: production
action: upsert
exporters:
otlphttp:
endpoint: http://tempo:4318
service:
pipelines:
traces:
receivers: [otlp]
processors: [memory_limiter, resource, batch]
exporters: [otlphttp]
Trois détails comptent vraiment ici. memory_limiter doit être le premier processeur du pipeline, sinon le Collector se fait tuer par l'OOM killer dès le premier pic. batch réduit le nombre de requêtes réseau vers le backend d'un facteur 10 à 100. Et deployment.environment.name est le nom actuel de la convention : l'ancien deployment.environment est déprécié depuis la 1.27.
Python : trois commandes pour la première trace
Sur un service Python, l'auto-instrumentation couvre FastAPI, Flask, Django, requests, httpx, psycopg, Redis et SQLAlchemy. Tu n'écris pas une ligne de code — le détail des paquets est dans le guide Python officiel.
uv pip install opentelemetry-distro opentelemetry-exporter-otlp
uv run opentelemetry-bootstrap -a install
OTEL_SERVICE_NAME=api-paiement \
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 \
OTEL_RESOURCE_ATTRIBUTES=service.version=1.4.2 \
uv run opentelemetry-instrument python -m uvicorn app:app
La dernière ligne relance ton process avec un sitecustomize qui patche les bibliothèques au démarrage. Tu obtiens des spans serveur, des spans clients SQL et HTTP, et les attributs normalisés dont ton backend a besoin pour construire la waterfall.
Le piège immédiat : sans OTEL_SERVICE_NAME, tous tes services s'appellent unknown_service. Ton backend affiche alors une seule ligne moyenne qui mélange l'API de paiement et le service de facturation. Ce n'est pas une erreur bloquante. Tu le découvres trois semaines plus tard en cherchant pourquoi les dashboards ne veulent rien dire.
Ce que tu mets dans le resource décide de tout
Le resource décrit l'entité qui produit la télémétrie : service, version, environnement, cluster, pod. Il est attaché à chaque span et à chaque métrique. C'est ce qui te permet de filtrer « la version 1.4.2 en prod sur le cluster ouest » sans avoir à taguer ton code.
Renseigne-le en variables d'environnement plutôt qu'en dur dans le code. Un même binaire doit pouvoir s'annoncer staging ou production selon l'endroit où il tourne.
export OTEL_SERVICE_NAME=api-paiement
export OTEL_RESOURCE_ATTRIBUTES="service.version=1.4.2,deployment.environment.name=production,k8s.namespace.name=paiement,k8s.pod.name=$HOSTNAME"
Sur Kubernetes, la règle est encore plus simple : utilise l'Operator et le Instrumentation CRD. Il injecte les variables, gère l'agent en sidecar et met à jour les attributs k8s.* automatiquement quand un pod est recréé.
Quand l'auto-instrumentation s'arrête, tu prends le relais
L'auto te donne le squelette. Elle ignore ta logique métier : pourquoi un panier a été refusé, combien de règles ont été évaluées, quel entrepôt a répondu en dernier.
from opentelemetry import trace
tracer = trace.get_tracer("checkout")
def valider_panier(panier, client):
with tracer.start_as_current_span("checkout.valider") as span:
span.set_attribute("cart.items", len(panier.lignes))
span.set_attribute("cart.total_eur", panier.total)
span.set_attribute("customer.tier", client.tier)
refus = regles.evaluer(panier)
span.set_attribute("checkout.refus_motif", refus.motif or "")
if refus:
span.set_status(trace.Status(trace.StatusCode.ERROR, refus.motif))
return refus
Deux règles de survie. Un span représente une opération avec un début et une fin mesurables, pas une fonction utilitaire appelée 400 fois par requête. Et les attributs suivent les conventions sémantiques dès qu'elles existent.
Ce point est moins cosmétique qu'il n'y paraît. http.method est devenu http.request.method, http.status_code est devenu http.response.status_code. Un dashboard qui interroge encore les anciens noms ne renvoie pas d'erreur : il renvoie du vide.
Le sampling, ou comment ne pas exploser ta facture
Une API à 300 requêtes par seconde produit plus de 25 millions de spans par jour. Multiplie par le prix au gigaoctet de ton backend et tu comprends pourquoi la rétention des traces est le premier poste de coût d'un projet d'observabilité. J'ai détaillé les ordres de grandeur dans le vrai coût de l'observabilité.
Le sampling par tête jette avant de savoir ce qui s'est passé : 10 % de tout, y compris tes erreurs. Le sampling par queue attend la fin de la trace et garde l'intégralité de ce qui t'intéresse.
processors:
tail_sampling:
decision_wait: 10s
policies:
- name: erreurs
type: status_code
status_code: {status_codes: [ERROR]}
- name: lentes
type: latency
latency: {threshold_ms: 500}
- name: reste
type: probabilistic
probabilistic: {sampling_percentage: 5}
decision_wait: 10s signifie que chaque trace reste en mémoire pendant dix secondes avant décision. À 300 req/s, ça fait 3 000 traces en attente, avec leurs spans : dimensionne la RAM du Collector en conséquence.
Contrainte plus vicieuse : le tail sampling exige que toutes les spans d'une trace arrivent au même Collector. Derrière un load balancer, il faut router par trace_id, sinon chaque instance décide dans son coin et tu conserves des traces tronquées.
Les cinq pièges qui cassent une trace en production
- Le proxy qui avale
traceparent. Un reverse proxy qui reconstruit les en-têtes à la main coupe la propagation W3C. Résultat : deux traces orphelines au lieu d'une, et un service qui apparaît toujours comme racine alors qu'il est appelé au troisième niveau. - Le span sans parent dans un thread pool. Le contexte OTel s'appuie sur
contextvars, qui ne traverse pasThreadPoolExecutor.submitsans propagation explicite. Utilisecontextvars.copy_context().runou attache le span à la tâche soumise. - La cardinalité explosive. Mettre
user.idou l'URL complète en attribut de métrique crée des millions de séries temporelles et fait gonfler la mémoire du backend. Les identifiants vont dans les traces, indexées pour ça, jamais dans les métriques. - Le flush perdu à l'arrêt. Un conteneur qui sort sans
shutdown()perd leBatchSpanProcessorencore en mémoire. Déclaretracer_provider.shutdown()dans ton hook d'arrêt, et laisse quelques secondes de grace period au pod. - Le double export. Auto-instrumentation et instrumentation manuelle mal cadrées produisent deux spans pour le même appel sortant. Le symptôme ne se voit pas à l'œil : compte les spans par trace dans une requête de test.
Une migration en cinq jours, pas en cinq mois
| Jour | Action | Critère de sortie |
|---|---|---|
| J1 | Collector en local, export vers un backend de test | une trace visible de bout en bout |
| J2 | Auto-instrumentation sur un service non critique | spans serveur et spans SQL cohérents |
| J3 | Conventions sémantiques et attributs de resource | service.name et version sur chaque span |
| J4 | Tail sampling centré erreurs et lenteur | 100 % des erreurs conservées |
| J5 | Deuxième service, vérification de la propagation | une seule trace pour un appel inter-services |
Le critère du J5 est le seul qui compte vraiment. Tant qu'un appel entre deux services produit deux traces distinctes, tu n'as pas migré : tu as ajouté du bruit à ton monitoring existant. C'est précisément le point que j'avais creusé dans ce qu'OpenTelemetry change dans le métier.
Questions fréquentes
Faut-il changer de backend après la migration ?
Rien ne t'y oblige. Tout backend qui accepte OTLP en entrée fonctionne avec de l'instrumentation standard. Le gain est ailleurs : le jour où tu renégocies ton contrat, ton code ne dépend plus du vendor.
OpenTelemetry remplace-t-il Prometheus ?
Non, il le complète. Prometheus reste un stockage de métriques solide. OTel fournit le SDK et le protocole qui l'alimentent, et te permet de supprimer les exporters maison que tu maintiens depuis des années.
Combien de temps pour 40 microservices ?
Le premier service prend une journée. Le vingtième prend une heure. Le coût réel n'est pas l'instrumentation : c'est l'harmonisation des noms d'attributs et des noms de services entre les équipes.
Le Collector est-il un point de défaillance unique ?
Oui si tu le déploies en un seul pod. En sidecar ou en DaemonSet, la panne reste locale. En Deployment derrière un Service, prévois au moins deux réplicas et un buffer disque pour absorber les coupures du backend.
Instrumente un service cette semaine, un seul, avec le Collector devant. Tu verras la différence sur la première alerte de nuit : la question passe de « qu'est-ce qui a planté ? » à « quelle requête a planté, et où ».