Report Node.js application data using a Jaeger client - Managed Service for OpenTelemetry

Lorsque vous exécutez une application Node.js, vous devez pouvoir surveiller la latence des requêtes, les taux d'erreur et les dépendances de service pour diagnostiquer les problèmes de performance. Managed Service for OpenTelemetry (Tracing Analysis) collecte et visualise les traces distribuées de votre application, ce qui vous aide à identifier les goulots d'étranglement au sein des microservices.

Cette rubrique explique comment instrumenter une application Node.js avec la bibliothèque cliente Jaeger afin d'envoyer les données de trace à Tracing Analysis.

Fonctionnement de l'envoi des données

Les données de trace parviennent au backend Tracing Analysis via l'un des deux chemins suivants :

Envoi direct : l'application envoie les spans via HTTP vers un endpoint de collecteur. Aucune infrastructure supplémentaire n'est requise.
Envoi via un agent : l'application envoie les spans à un agent Jaeger local via UDP, qui les transfère ensuite au collecteur. Utilisez cette méthode si vous avez besoin du transport UDP ou d'une mise en tampon locale des spans.

Les étapes ci-dessous utilisent l'envoi direct (approche la plus courante). Pour l'envoi via un agent, consultez la documentation jaeger-client-node.

Prérequis

Avant de commencer, assurez-vous que :

Node.js est installé sur votre machine.

La dépendance jaeger-client est ajoutée à votre projet :

  "dependencies": {
      "jaeger-client": "^3.12.0"
  }

Vous disposez d'un endpoint de collecteur Jaeger ou Zipkin (consultez la section « Obtenir l'endpoint du collecteur » ci-dessous).

Obtenir l'endpoint du collecteur

Connectez-vous à la console Managed Service for OpenTelemetry.
Dans le volet de navigation de gauche, cliquez sur Cluster Configurations. Ensuite, cliquez sur l'onglet Access point information.
Dans la barre de navigation supérieure, sélectionnez une région. Dans la section Cluster Information, activez l'option Show Token.
Dans la section Client, cliquez sur Jaeger ou Zipkin.
Copiez l'endpoint depuis la colonne Related Information.

Remarque

Si votre application s'exécute dans un environnement de production Alibaba Cloud, utilisez un endpoint Virtual Private Cloud (VPC). Sinon, utilisez un endpoint public. Pour Zipkin, utilisez l'endpoint v2 sauf si vous avez une raison spécifique d'utiliser la version v1.

Instrumenter votre application

Étape 1 : Initialiser le traceur

Configurez le client Jaeger avec le nom de votre service, la stratégie d'échantillonnage et l'endpoint du collecteur.

Remarque

Remplacez <endpoint> par l'endpoint obtenu dans la section précédente. L'endpoint est également disponible sur la page Overview de la console Tracing Analysis.

const initTracer = require("jaeger-client").initTracer;

const config = {
    serviceName: 'node-service',
    sampler: {
        type: "const",
        param: 1
    },
    reporter: {
        collectorEndpoint: "<endpoint>"
    },
};

Étape 2 : Créer une instance de traceur

const tracer = initTracer(config);

Étape 3 : Créer et terminer des spans

Une span représente une unité de travail unique. Démarrez une span, ajoutez éventuellement des tags et des journaux, puis terminez-la pour envoyer les données.

const span = tracer.startSpan("say-hello");

// Attach metadata as key-value tags (appears in the trace detail view)
span.setTag("tagKey-01", "tagValue-01");

// Record a timestamped log entry (appears in the span's log timeline)
span.log({event: "timestamp", value: Date.now()});

// Finish the span to flush it to the collector
span.finish();

Étape 4 : Vérifier les traces dans la console

Connectez-vous à la console Tracing Analysis et consultez la trace.

Exemple complet avec Express

Cet exemple instrumente une application Express. Chaque requête entrante est encapsulée dans une span, et une entrée de journal est enregistrée pour la route /api.

const express = require("express");
const initTracer = require("jaeger-client").initTracer;
const app = express();

const config = {
    serviceName: 'node-service',
    sampler: {
        type: "const",
        param: 1
    },
    reporter: {
        collectorEndpoint: "<endpoint>"
    },
};
const tracer = initTracer(config);

// Middleware: start a span for every incoming request
app.all('*', function (req, res, next) {
    req.span = tracer.startSpan("say-hello");
    next();
});

// Route handler: log a timestamp and finish the span
app.get("/api", function (req, res) {
    const span = req.span;
    span.log({event: "timestamp", value: Date.now()});
    req.span.finish();
    res.send({code: 200, msg: "success"});
});

app.listen(3000, '127.0.0.1', function () {
    console.log('start');
});

Remplacez <endpoint> par votre endpoint de collecteur, puis exécutez l'application :

node app.js

Envoyez une requête de test :

curl http://127.0.0.1:3000/api

Réponse attendue :

{"code":200,"msg":"success"}

Espaces réservés

Remplacez l'espace réservé suivant par votre valeur réelle avant d'exécuter le code :

Espace réservé	Description
`<endpoint>`	Endpoint du collecteur Jaeger obtenu depuis la console Managed Service for OpenTelemetry. Consultez la section « Obtenir l'endpoint du collecteur » ci-dessus.