Application Real-Time Monitoring Service:Submit trace data from a Node.js application

Obtención del endpoint

1. Inicie sesión en la consola de Managed Service for OpenTelemetry.

2. En el panel de navegación izquierdo, haga clic en Cluster Configurations. En la página que aparece, haga clic en la pestaña Access point information.

3. En la barra de navegación superior, seleccione una región. En la sección Cluster Information, active Show Token.

4. Establezca Client en OpenTelemetry.

5. En la columna Related Information, copie el endpoint.

   

Si su aplicación se ejecuta en un entorno de producción de Alibaba Cloud, utilice el endpoint de Virtual Private Cloud (VPC). Para cualquier otro entorno, use el endpoint público.

Paso 1: Instalar dependencias

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

Paso 2: Instalar paquetes de OpenTelemetry

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

Paso 3: Crear la aplicación

A continuación se muestra un ejemplo que crea un servidor Express básico con dos rutas:

"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");
});

Paso 4: Establecer variables de entorno e iniciar la aplicación

Establezca a continuación las variables de entorno y luego inicie la aplicación:

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

Reemplace los siguientes marcadores de posición con sus valores reales:

En la siguiente tabla se describe cada variable de entorno:

Para conocer los detalles de todas las variables de entorno disponibles en OpenTelemetry, consulte Configuración de instrumentación automática .

Paso 5: Generar datos de trazas

Envíe una solicitud para generar trazas:

curl localhost:7001/hello

Una vez que finaliza la solicitud, el SDK exporta los datos de trazas a Managed Service for OpenTelemetry.

Paso 1: Agregar dependencias de OpenTelemetry

Agregue a continuación las dependencias a su archivo 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"
}

Paso 2: Crear el proveedor de trazas

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",
  }),
});

Paso 3: Registrar las instrumentaciones del framework

Registre las instrumentaciones de HTTP y Express para trazar automáticamente las solicitudes entrantes y salientes:

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

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

Para instrumentar otros frameworks de Node.js, consulte el paquete OpenTelemetry auto-instrumentations-node , donde encontrará los complementos disponibles.

Paso 4: Configurar el exportador

Configure un exportador OTLP mediante gRPC para enviar los datos de trazas a 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();

Reemplace los siguientes marcadores de posición con sus valores reales:

Paso 5 (opcional): Agregar eventos y atributos personalizados

Adjunte eventos y atributos al span actual para añadir contexto específico de la aplicación:

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");

Para obtener más información sobre la API de trazas de OpenTelemetry, consulte la guía de introducción a OpenTelemetry JS .

La aplicación no aparece en la consola

• Compruebe que OTEL_EXPORTER_OTLP_TRACES_ENDPOINT (instrumentación automática) o el parámetro url en OTLPTraceExporter (instrumentación manual) coincida con el endpoint de la consola.

• Verifique la conectividad de red hacia el endpoint. Si su aplicación se ejecuta fuera de Alibaba Cloud, utilice el endpoint público en lugar del endpoint VPC.

• Asegúrese de que su aplicación haya recibido como mínimo una solicitud. OpenTelemetry almacena los spans en un búfer antes de exportarlos.

• En el caso de la instrumentación manual, compruebe que el proveedor de trazas se inicializó antes que cualquier importación de la aplicación. Un orden de inicialización incorrecto provoca la ausencia de spans.

Habilitar el registro de depuración

Establezca el nivel de registro de OpenTelemetry en debug para inspeccionar el comportamiento del SDK:

export OTEL_LOG_LEVEL=debug

Reinicie la aplicación y revise la salida de la consola para buscar registros y errores de exportación de spans. Una exportación exitosa genera entradas de registro similares a las siguientes:

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

Si no aparecen entradas de spans, compruebe que su aplicación procesó como mínimo una solicitud y que el endpoint es accesible.

"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");
});