Node.js : Instrumenter un microservice avec OpenTelemetry et exporter les traces vers Lescopr

Dans un contexte où les équipes SRE doivent garantir des SLA stricts, la visibilité sur chaque appel d’un microservice Node.js devient cruciale. Ce guide pas à pas montre comment installer OpenTelemetry, instrumenter le code, et pousser les traces vers la plateforme Lescopr afin d’améliorer la visibilité et réduire le MTTR.

Préparer l’environnement de développement

Choisir le runtime Node.js

• Utilisez la version LTS actuelle (v18 ou supérieure) pour bénéficier des dernières améliorations de performance et de sécurité.
• Vérifiez la compatibilité du SDK OpenTelemetry avec votre version via la documentation officielle.

Installer les dépendances OpenTelemetry

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

Ces packages offrent l'API de base, le SDK Node, l'instrumentation HTTP et un exporteur OTLP compatible avec Lescopr. Consultez la [documentation OpenTelemetry] pour les options d'installation avancées.

Implémenter l’instrumentation

Instrumentation automatique des requêtes HTTP

Le SDK Node détecte automatiquement les requêtes entrantes et sortantes lorsqu’on charge l’instrumentation HTTP :

const { NodeTracerProvider } = require('@opentelemetry/sdk-node');
const { HttpInstrumentation } = require('@opentelemetry/instrumentation-http');

const provider = new NodeTracerProvider({
  sampler: new AlwaysOnSampler(), // voir section "Best practices"
});
provider.addSpanProcessor(new SimpleSpanProcessor(new OTLPTraceExporter()));
provider.register();

new HttpInstrumentation().enable();

Ajout du tracing personnalisé

Pour les opérations métier (ex. appel à une base de données), créez des spans manuels :

const tracer = provider.getTracer('my-service');
app.get('/users', async (req, res) => {
  const span = tracer.startSpan('fetch-users');
  try {
    const users = await db.query('SELECT * FROM users');
    res.json(users);
  } finally {
    span.end();
  }
});

Pourquoi créer des spans personnalisés ? Les spans automatiques ne couvrent que le transport HTTP. En ajoutant des spans métier, vous obtenez une vue granulaire du temps passé dans chaque couche, ce qui facilite le diagnostic des goulots d’étranglement.

Best practices (liste à puces)

• AlwaysOnSampler pendant la phase de développement pour capturer 100 % des traces.
• Réduire le taux de sampling en production avec ParentBasedSampler afin de contrôler le volume de données.
• Ajouter des attributs pertinents (ex. http.method, db.system) pour enrichir les requêtes dans Lescopr.

Configurer l’exporteur Lescopr

Créer la clé d’API Lescopr

1. Connectez‑vous à votre compte Lescopr.
2. Accédez à Settings → API Keys.
3. Générer une clé avec le scope trace:write.

Paramétrer le Exporter OTLP

const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-http');

const exporter = new OTLPTraceExporter({
  url: 'https://api.lescopr.io/v1/traces',
  headers: { 'Authorization': `Bearer ${process.env.LESCOPR_API_KEY}` },
});
provider.addSpanProcessor(new BatchSpanProcessor(exporter));

Cette configuration envoie les traces au point d’entrée HTTP de Lescopr. Consultez le [Guide d’export Lescopr] pour les paramètres avancés (compression, timeout, etc.).

Vérifier et optimiser les traces

Analyser les traces dans le tableau de bord Lescopr

• Ouvrez le tableau de bord Traces et filtrez par service my-service.
• Identifiez les latences élevées et les erreurs HTTP : 5 xx ou temps de réponse > 500 ms.
• Utilisez les métriques de saturation du CPU et GC pauses pour corréler les pics de latence.

Ajuster le sampling

En production, passez à un ParentBasedSampler qui hérite du contexte parent lorsqu’une requête critique est détectée :

const { ParentBasedSampler, TraceIdRatioBasedSampler } = require('@opentelemetry/core');
provider.register({
  sampler: new ParentBasedSampler({
    root: new TraceIdRatioBasedSampler(0.2), // 20 % des traces globales
  }),
});

Cette approche réduit le volume de données tout en conservant les traces des transactions les plus importantes.

Conclusion

En suivant ces étapes – préparation de l’environnement, instrumentation du code, configuration de l’exporteur Lescopr et optimisation du sampling – vous obtenez une visibilité complète sur vos microservices Node.js. Les traces enrichies dans Lescopr permettent de réduire le MTTR, d’améliorer le respect des SLA et d’accélérer les boucles de rétroaction produit.

Pour aller plus loin, la documentation Lescopr détaille la mise en place pas à pas.