Implémenter OpenTelemetry dans tes projets

Traces, métriques, logs : un seul protocole. Le chemin concret pour passer à OpenTelemetry, Collector et sampling compris.

Schéma OpenTelemetry : applications, Collector, backend

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.

SignalQuestion à laquelle il répondCoûtExemple concret
TracesOù passe le temps d'une requête ?élevé (volume + rétention)1,8 s dans un appel SQL sur orders
MétriquesComment évolue le système dans le temps ?faiblep95 de latence, taux d'erreur 5xx
LogsQue s'est-il passé exactement à cet instant ?moyenstack 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

  1. 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.
  2. Le span sans parent dans un thread pool. Le contexte OTel s'appuie sur contextvars, qui ne traverse pas ThreadPoolExecutor.submit sans propagation explicite. Utilise contextvars.copy_context().run ou attache le span à la tâche soumise.
  3. La cardinalité explosive. Mettre user.id ou 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.
  4. Le flush perdu à l'arrêt. Un conteneur qui sort sans shutdown() perd le BatchSpanProcessor encore en mémoire. Déclare tracer_provider.shutdown() dans ton hook d'arrêt, et laisse quelques secondes de grace period au pod.
  5. 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

JourActionCritère de sortie
J1Collector en local, export vers un backend de testune trace visible de bout en bout
J2Auto-instrumentation sur un service non critiquespans serveur et spans SQL cohérents
J3Conventions sémantiques et attributs de resourceservice.name et version sur chaque span
J4Tail sampling centré erreurs et lenteur100 % des erreurs conservées
J5Deuxième service, vérification de la propagationune 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ù ».