Managed Service for OpenTelemetry:Soumettre des données de trace depuis une application Node.js

Obtenir l'endpoint

1. Connectez-vous à la console Managed Service for OpenTelemetry.

2. Dans le volet de navigation de gauche, cliquez sur Cluster ConfigurationsCluster Configurations. Sur la page qui s'affiche, cliquez sur l'onglet Access point informationAccess point information.

3. Dans la barre de navigation supérieure, sélectionnez une région. Dans la section Cluster InformationCluster Information, activez l'option Show TokenShow Token.

4. Définissez ClientClient sur OpenTelemetryOpenTelemetry.

5. Dans la colonne Related InformationRelated Information, copiez l'endpoint.

   

Si votre application s'exécute dans un environnement de production Alibaba Cloud, utilisez l'endpoint VPC (Virtual Private Cloud). Utilisez l'endpoint public pour tous les autres environnements.

Étape 1 : Installer les dépendances

cd auto-instrumentation
npm init -y
npm install express axios

Étape 2 : Installer les packages OpenTelemetry

npm install --save @opentelemetry/api @opentelemetry/auto-instrumentations-node

Étape 3 : Créer l'application

L'exemple suivant crée un serveur Express de base avec deux routes :

"use strict";

const axios = require("axios").default;
const express = require("express");
const app = express();

app.get("/", async (req, res) => {
  const result = await axios.get("http://localhost:7001/hello");
  return res.status(201).send(result.data);
});

app.get("/hello", async (req, res) => {
  console.log("hello world!")
  res.json({ code: 200, msg: "success" });
});

app.use(express.json());

app.listen(7001, () => {
  console.log("Listening on http://localhost:7001");
});

Étape 4 : Définir les variables d'environnement et démarrer l'application

Définissez les variables d'environnement suivantes, puis démarrez l'application :

export OTEL_TRACES_EXPORTER="otlp"
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="<your-endpoint>"
export OTEL_NODE_RESOURCE_DETECTORS="env,host,os"
export OTEL_SERVICE_NAME="<your-service-name>"
export NODE_OPTIONS="--require @opentelemetry/auto-instrumentations-node/register"
node main.js

Remplacez les espaces réservés suivants par vos valeurs réelles :

Le tableau suivant décrit chaque variable d'environnement :

Pour plus de détails sur toutes les variables d'environnement OpenTelemetry disponibles, consultez Configuration de l'instrumentation automatique .

Étape 5 : Générer des données de trace

Envoyez une requête pour générer des traces :

curl localhost:7001/hello

Une fois la requête terminée, le SDK exporte les données de trace vers Managed Service for OpenTelemetry.

Étape 1 : Ajouter les dépendances OpenTelemetry

Ajoutez les dépendances suivantes à votre fichier package.json :

"dependencies": {
    "@opentelemetry/api": "^1.0.4",
    "@opentelemetry/exporter-trace-otlp-grpc": "^0.27.0",
    "@opentelemetry/instrumentation": "^0.27.0",
    "@opentelemetry/instrumentation-express": "^0.27.0",
    "@opentelemetry/instrumentation-http": "^0.27.0",
    "@opentelemetry/resources": "^1.0.1",
    "@opentelemetry/sdk-trace-base": "^1.0.1",
    "@opentelemetry/sdk-trace-node": "^1.0.1"
}

Étape 2 : Créer le fournisseur de traceur

const { Resource } = require("@opentelemetry/resources");
const { NodeTracerProvider } = require("@opentelemetry/sdk-trace-node");
const {
  SemanticResourceAttributes,
} = require("@opentelemetry/semantic-conventions");

const provider = new NodeTracerProvider({
  resource: new Resource({
    [SemanticResourceAttributes.HOST_NAME]: require("os").hostname(),
    // Replace "opentelemetry-express" with your service name
    [SemanticResourceAttributes.SERVICE_NAME]: "opentelemetry-express",
  }),
});

Étape 3 : Enregistrer les instrumentations de framework

Enregistrez les instrumentations HTTP et Express pour tracer automatiquement les requêtes entrantes et sortantes :

const { registerInstrumentations } = require("@opentelemetry/instrumentation");
const { HttpInstrumentation } = require("@opentelemetry/instrumentation-http");
const {
  ExpressInstrumentation,
} = require("@opentelemetry/instrumentation-express");

registerInstrumentations({
  tracerProvider: provider,
  instrumentations: [new HttpInstrumentation(), ExpressInstrumentation],
});

Pour instrumenter d'autres frameworks Node.js, consultez le package OpenTelemetry auto-instrumentations-node pour voir les plugins disponibles.

Étape 4 : Configurer l'exportateur

Configurez un exportateur OTLP via gRPC pour envoyer les données de trace à Managed Service for OpenTelemetry :

const metadata = new grpc.Metadata();
metadata.set("Authentication", "<your-token>");

const exporter = new OTLPTraceExporter({ url: "<your-endpoint>", metadata });
provider.addSpanProcessor(new SimpleSpanProcessor(exporter));
provider.register();

Remplacez les espaces réservés suivants par vos valeurs réelles :

Étape 5 (facultative) : Ajouter des événements et attributs personnalisés

Attachez des événements et des attributs à la span actuelle pour ajouter un contexte spécifique à l'application :

const api = require("@opentelemetry/api");
const currentSpan = api.trace.getSpan(api.context.active());

// Add a timestamped event
currentSpan.addEvent("timestamp", { value: Date.now() });

// Add a custom attribute
currentSpan.setAttribute("tagKey-01", "tagValue-01");

Pour en savoir plus sur l'API de traçage OpenTelemetry, consultez le Guide de démarrage OpenTelemetry JS .

L'application n'apparaît pas dans la console

• Vérifiez que OTEL_EXPORTER_OTLP_TRACES_ENDPOINT (automatique) ou le paramètre url dans OTLPTraceExporter (manuel) correspond à l'endpoint de la console.

• Confirmez la connectivité réseau vers l'endpoint. Si votre application s'exécute en dehors d'Alibaba Cloud, utilisez l'endpoint public au lieu de l'endpoint VPC.

• Assurez-vous que votre application a reçu au moins une requête. OpenTelemetry met en buffer les spans avant de les exporter.

• Pour l'instrumentation manuelle, confirmez que le fournisseur de traceur est initialisé avant tout import d'application. Un ordre d'initialisation incorrect entraîne l'absence de spans.

Activer la journalisation de débogage

Définissez le niveau de journalisation OpenTelemetry sur debug pour inspecter le comportement du SDK :

export OTEL_LOG_LEVEL=debug

Redémarrez l'application et vérifiez la sortie de la console pour les journaux d'exportation de span et les erreurs. Une exportation réussie produit des entrées de journal similaires à :

@opentelemetry/api: Registered a global for diag v1.x.x
...
items to be sent [{"traceId":"...","spanId":"...","name":"GET /hello",...}]

Si aucune entrée de span n'apparaît, vérifiez que votre application a traité au moins une requête et que l'endpoint est accessible.

"use strict";

const { Resource } = require("@opentelemetry/resources");
const {
  OTLPTraceExporter,
} = require("@opentelemetry/exporter-trace-otlp-grpc");
const { NodeTracerProvider } = require("@opentelemetry/sdk-trace-node");
const { SimpleSpanProcessor } = require("@opentelemetry/sdk-trace-base");
const {
  ExpressInstrumentation,
} = require("@opentelemetry/instrumentation-express");
const { registerInstrumentations } = require("@opentelemetry/instrumentation");
const { HttpInstrumentation } = require("@opentelemetry/instrumentation-http");
const {
  SemanticResourceAttributes,
} = require("@opentelemetry/semantic-conventions");
const grpc = require("@grpc/grpc-js");

// 1. Create a tracer provider with service metadata
const provider = new NodeTracerProvider({
  resource: new Resource({
    [SemanticResourceAttributes.HOST_NAME]: require("os").hostname(),
    [SemanticResourceAttributes.SERVICE_NAME]: "opentelemetry-express",
  }),
});

// 2. Register HTTP and Express instrumentations
registerInstrumentations({
  tracerProvider: provider,
  instrumentations: [new HttpInstrumentation(), ExpressInstrumentation],
});

// 3. Configure the gRPC exporter with authentication
const metadata = new grpc.Metadata();
metadata.set("Authentication", "<your-token>");

const exporter = new OTLPTraceExporter({ url: "<your-endpoint>", metadata });
provider.addSpanProcessor(new SimpleSpanProcessor(exporter));
provider.register();

// 4. Application code (must come after provider registration)
const api = require("@opentelemetry/api");
const axios = require("axios").default;
const express = require("express");
const app = express();

app.get("/", async (req, res) => {
  const result = await axios.get("http://localhost:7001/api");
  return res.status(201).send(result.data);
});

app.get("/api", async (req, res) => {
  const currentSpan = api.trace.getSpan(api.context.active());
  currentSpan.addEvent("timestamp", { value: Date.now() });
  currentSpan.setAttribute("tagKey-01", "tagValue-01");
  res.json({ code: 200, msg: "success" });
});

app.use(express.json());

app.listen(7001, () => {
  console.log("Listening on http://localhost:7001");
});