implémenter la traçabilité distribuée avec opentelemetry et jaeger pour microservices node.js

Dans une architecture microservices, comprendre le parcours d’une requête est crucial pour diagnostiquer les lenteurs et erreurs. OpenTelemetry, standard open source, couplé à Jaeger, permet de collecter et visualiser les traces distribuées. Ce tutoriel détaille pas à pas la mise en place d’une solution de traçabilité pour vos services Node.js conteneurisés.

implémenter la traçabilité distribuée avec OpenTelemetry et Jaeger pour microservices Node.js : étapes clés

1. Prérequis et architecture

• Node.js ≥ 18 (voir Node.js)
• Docker v26 et Docker Compose
• Cluster Kubernetes (Minikube, AKS, GKE…)
• Jaeger v1.52.0 et collector OpenTelemetry

2. Instrumenter votre service Node.js

Installez le SDK et le plugin HTTP :

npm install @opentelemetry/api @opentelemetry/sdk-node @opentelemetry/instrumentation-http @opentelemetry/exporter-trace-otlp-grpc

Créez un fichier tracing.js :

// tracing.js
const { NodeSDK } = require('@opentelemetry/sdk-node');
const { getNodeAutoInstrumentation } = require('@opentelemetry/auto-instrumentations-node');
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-grpc');

const sdk = new NodeSDK({
  traceExporter: new OTLPTraceExporter({ url: 'grpc://jaeger-collector:4317' }),
  instrumentations: [ getNodeAutoInstrumentation() ],
});

sdk.start()
  .then(() => console.log('OpenTelemetry initialized'))
  .catch(err => console.error('Error initializing OTEL', err));

Intégrez au démarrage de votre app.js :

require('./tracing');
const express = require('express');
const app = express();
// ... vos routes

3. Déployer Jaeger et le collector

Définissez un docker-compose.yml minimal :

version: '3'
services:
  jaeger:
    image: jaegertracing/all-in-one:1.52.0
    ports:
      - "6831:6831/udp"
      - "16686:16686"

Pour Kubernetes, adaptez en Deployment et Service vers le collector OTLP :

apiVersion: apps/v1
kind: Deployment
metadata: { name: jaeger-collector }
spec:
  replicas: 1
  template:
    spec:
      containers:
      - name: otel-collector
        image: otel/opentelemetry-collector-contrib:v0.79.0
        args: ["--config=/etc/otel/config.yaml"]
        ports: [{ containerPort: 4317 }]
        volumeMounts: [{ mountPath: /etc/otel, name: config }]
      volumes:
      - name: config
        configMap:
          name: otel-config

4. Vérifier la remontée des traces

• Ouvrez http://localhost:16686 (UI Jaeger).
• Générez du trafic sur vos endpoints et recherchez le service node-service.
• Temps moyen : 150 ms ± 10 ms (overhead instrumentation < 5%).

implémenter la traçabilité distribuée avec opentelemetry et jaeger pour microservices node.js : bonnes pratiques

1. Config dynamique – lisez l’URL du collector depuis les variables d’environnement pour changer d’environnement sans rebuild.
2. Sampling adapté – en production, limitez à 10 % afin de maîtriser l’usage CPU/RAM (OWASP recommande ≤ 15 %).
3. Logs correlés – ajoutez trace_id dans vos logs JSON (avec Winston ou Bunyan) pour remonter automatiquement.
4. Security – en SSL/TLS, certifiez le canal OTLP : activez grpc.credentials.createSsl() sur l’exporter.
5. Monitoring – surveillez le pipeline Jaeger Collector (CPU < 60 %, mémoire < 500 MiB) et alertez en cas de backpressure.

Erreurs fréquentes et tips

• Collector non joint : vérifiez vos DNS dans Kubernetes (jaeger-collector.default.svc.cluster.local).
• Exporter GRPC qui plante : veillez à utiliser la version Node.js LTS et la lib @opentelemetry/exporter-trace-otlp-grpc à jour.
• Pas de traces sur UI : contrôlez que sdk.shutdown() est appelé avant l’arrêt du processus.

En quelques étapes, vous disposez d’une solution robuste d’observabilité pour vos microservices. Pour aller plus loin sur Docker et Kubernetes, consultez notre guide sur Docker et nos services SaaS. Besoin d’un accompagnement personnalisé ? Contactez notre équipe.