Introduction

Dans les environnements micro‑services, la visibilité sur les appels HTTP et les opérations de base de données est cruciale pour réduire le MTTR. NestJS, framework Node.js très répandu, offre une architecture modulaire idéale pour intégrer OpenTelemetry. Ce guide vous montre comment, en cinq étapes, instrumenter votre API NestJS et exporter les traces vers Lescopr, la solution B2B SaaS d’observabilité qui combine APM, suivi des SLA et conformité RGPD.

1. Initialiser le projet NestJS

1.1 Créer la base du projet

npm i -g @nestjs/cli
nest new my‑api
cd my‑api

Cette commande génère une structure de dossiers standard (src, test, etc.) et configure TypeScript. Le choix de TypeScript garantit la typabilité des métriques et facilite le mapping des spans.

1.2 Installer les dépendances d’observabilité

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

Ces paquets permettent d’instrumenter automatiquement les modules HTTP, Express, et les clients DB courants.

2. Configurer OpenTelemetry dans NestJS

2.1 Créer le fichier de configuration `otel‑config.ts`

import { NodeSDK } from '@opentelemetry/sdk-node';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';

const exporter = new OTLPTraceExporter({
  url: 'https://otel.lescopr.com/v1/traces', // Endpoint Lescopr
});

export const otelSDK = new NodeSDK({
  traceExporter: exporter,
  instrumentations: [getNodeAutoInstrumentations()],
});

otelSDK.start();

Cette configuration initialise le SDK, active l’instrumentation automatique et définit l’exportateur HTTP vers Lescopr.

2.2 Lancer le SDK avant le serveur NestJS

Modifiez main.ts :

import { otelSDK } from './otel-config'; // <-- import du SDK
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  await app.listen(3000);
}
bootstrap();

Le SDK démarre dès le lancement du processus, garantissant que chaque requête est tracée.

3. Enrichir les traces avec des attributs métier

3.1 Utiliser les décorateurs NestJS

import { Span, trace } from '@opentelemetry/api';

@Injectable()
export class UsersService {
  async findOne(id: string) {
    const span = trace.getSpan(trace.getActiveSpan());
    span?.setAttribute('user.id', id);
    // logique métier …
  }
}

En ajoutant des attributs comme user.id ou transaction.type, vous rendez les traces exploitable dans les dashboards Lescopr.

3.2 Propagation du contexte HTTP

NestJS utilise express sous‑couche. OpenTelemetry capture automatiquement les en‑têtes traceparent. Aucun code supplémentaire n’est requis, mais il est recommandé de vérifier la propagation dans les middlewares personnalisés.

4. Exporter les traces vers Lescopr

4.1 Configurer les variables d’environnement

export OTEL_EXPORTER_OTLP_ENDPOINT=https://otel.lescopr.com/v1/traces
export OTEL_RESOURCE_ATTRIBUTES=service.name=my‑api,service.version=1.0.0

Ces variables permettent à l’exportateur d’inclure les métadonnées du service, utiles pour le filtrage dans les tableaux de bord.

4.2 Vérifier la réception des traces

Après le premier appel GET /users, ouvrez le tableau de bord Lescopr → Traces et recherchez le service.name=my‑api. Vous devez voir un span racine HTTP GET /users avec des sous‑spans pour la base de données et les middlewares.

5. Optimiser la collecte et le coût

5.1 Batch et compression

OpenTelemetry regroupe les spans en paquets de 10 000 ms par défaut. Ajustez le batchTimeout si votre volume de requêtes est élevé :

import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-base';
otelSDK.addSpanProcessor(new BatchSpanProcessor(exporter, {
  scheduleDelayMillis: 5000,
}));

5.2 Filtrage des spans non critiques

Utilisez le Sampler pour ignorer les requêtes de santé (/health) :

import { ParentBasedSampler, TraceIdRatioBasedSampler } from '@opentelemetry/core';
otelSDK.configureTracerProvider({
  sampler: new ParentBasedSampler({
    root: new TraceIdRatioBasedSampler(0.5), // 50 % des requêtes
  }),
});

5.3 Monitoring du coût d’exportation

Lescopr propose un tableau de bord Export Cost qui indique le nombre de spans exportés par minute et le volume de données. Configurez des alertes si le coût dépasse le budget prévu.

Conclusion

En suivant ces cinq étapes – création du projet, configuration du SDK, enrichissement des spans, exportation vers Lescopr et optimisation du flux – vous obtenez une visibilité complète sur votre API NestJS. Les traces collectées permettent d’identifier rapidement les goulots d’étranglement, de mesurer le respect des SLA et de garantir la conformité RGPD grâce aux métadonnées enrichies.

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