Application Real-Time Monitoring Service:Envie dados de rastreamento de uma aplicação Node.js

Obtenha o endpoint

1. Faça login no console do Managed Service for OpenTelemetry.

2. No painel de navegação à esquerda, clique em Cluster Configurations. Na página exibida, clique em aba Access point information.

3. Na barra de navegação superior, selecione uma região. Na seção Cluster Information, ative Show Token.

4. Defina Client como OpenTelemetry.

5. Na coluna Related Information, copie o endpoint.

   

Se sua application executa em um ambiente de produção da Alibaba Cloud, utilize o endpoint da Virtual Private Cloud (VPC). Para todos os outros ambientes, use o endpoint público.

Passo 1: Instale as dependências

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

Passo 2: Instale os pacotes do OpenTelemetry

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

Passo 3: Crie a aplicação

O exemplo abaixo cria um servidor Express básico com duas rotas:

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

Passo 4: Defina variáveis de ambiente e inicie a aplicação

Configure as seguintes variáveis de ambiente e inicie a aplicação:

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

Substitua os placeholders abaixo pelos seus valores reais:

A tabela a seguir descreve cada variável de ambiente:

Para detalhes sobre todas as variáveis de ambiente disponíveis no OpenTelemetry, consulte Configuração de instrumentação automática .

Passo 5: Gere dados de rastreamento

Envie uma requisição para gerar rastros:

curl localhost:7001/hello

Após a conclusão da requisição, o SDK exporta os dados de rastreamento para o Managed Service for OpenTelemetry.

Passo 1: Adicione as dependências do OpenTelemetry

Inclua as seguintes dependências no arquivo 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"
}

Passo 2: Crie o tracer provider

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

Passo 3: Registre as instrumentações do framework

Registre as instrumentações de HTTP e Express para rastrear requisições de entrada e saída automaticamente:

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 outros frameworks Node.js, consulte o pacote OpenTelemetry auto-instrumentations-node e verifique os plugins disponíveis.

Passo 4: Configure o exportador

Configure um exportador OTLP via gRPC para enviar dados de rastreamento ao 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();

Substitua os placeholders a seguir pelos seus valores reais:

Passo 5 (opcional): Adicione eventos e atributos personalizados

Anexe eventos e atributos ao span atual para fornecer contexto específico da aplicação:

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 mais informações sobre a API de rastreamento do OpenTelemetry, consulte o Guia de introdução ao OpenTelemetry JS .

A aplicação não aparece no console

• Verifique se OTEL_EXPORTER_OTLP_TRACES_ENDPOINT (automático) ou o parâmetro url em OTLPTraceExporter (manual) corresponde ao endpoint fornecido no console.

• Confirme a conectividade de rede com o endpoint. Se sua application roda fora da Alibaba Cloud, utilize o endpoint público em vez do endpoint VPC.

• Certifique-se de que sua aplicação recebeu pelo menos uma requisição. O OpenTelemetry armazena spans em buffer antes de exportá-los.

• Na instrumentação manual, confirme se o tracer provider foi inicializado antes de qualquer importação da aplicação. Ordem de inicialização incorreta resulta em spans ausentes.

Ative logs de depuração

Defina o nível de log do OpenTelemetry como debug para inspecionar o comportamento do SDK:

export OTEL_LOG_LEVEL=debug

Reinicie a aplicação e verifique a saída no console em busca de logs e erros de exportação de spans. Uma exportação bem-sucedida gera entradas de log semelhantes a:

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

Caso nenhuma entrada de span apareça, verifique se sua aplicação processou pelo menos uma requisição e se o endpoint está acessível.

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