通過OpenTelemetry為應用埋點并上報鏈路數據至可觀測鏈路 OpenTelemetry 版后,可觀測鏈路 OpenTelemetry 版即可開始監控應用,您可以查看應用拓撲、調用鏈路、異常事務、慢事務和SQL分析等一系列監控數據。本文介紹如何使用OpenTelemetry對Node.js Express應用進行自動或手動埋點并上報數據。
前提條件
Node.js版本需要14及以上,其他版本請使用Jaeger接入。Jaeger接入操作,請參見通過Jaeger上報Node.js應用數據。
登錄ARMS控制臺,在左側導航欄單擊接入中心。
在服務端應用區域單擊OpenTelemetry卡片。
在彈出的OpenTelemetry面板中選擇數據需要上報的地域。
說明初次接入的地域將會自動進行資源初始化。
選擇連接方式和上報方式,然后復制接入點信息。
連接方式:若您的服務部署在阿里云上,且所屬地域與選擇的接入地域一致,推薦使用阿里云內網方式,否則選擇公網方式。
上報方式:根據客戶端支持的協議類型選擇HTTP或gRPC協議上報數據。
背景信息
OpenTelemetry提供了若干自動埋點插件,支持為常見框架自動創建Span,支持的框架列表如下,完整信息請參見OpenTelemetry官方文檔。
框架名 | 鏈接 |
amqplib | |
aws-lambda | |
aws-sdk | |
bunyan | |
cassandra-driver | |
connect | |
cucumber | |
dataloader | |
dns | |
express | |
fastify | |
generic-pool | |
graphql | |
grpc | |
hapi | |
http | |
ioredis | |
knex | |
koa | |
lru-memoizer | |
memcached | |
mongodb | |
mongoose | |
mysql | |
mysql2 | |
nestjs-core | |
net | |
pg | |
pino | |
redis | |
restify | |
socket.io | |
winston |
示例Demo
示例代碼倉庫地址:opentelemetry-nodejs-demo
方法一:自動埋點(推薦)
下載運行項目所需的依賴。
cd auto-instrumentation npm init -y npm install express npm install axios
下載OpenTelemetry自動埋點所需的依賴。
npm install --save @opentelemetry/api npm install --save @opentelemetry/auto-instrumentations-node
編寫應用代碼。
以下代碼是通過Express實現的簡單應用示例:
"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"); });
通過環境變量設置OpenTelemetry參數并運行應用。
請將
${httpEndpoint}
替換為前提條件中獲取的HTTP接入點,請將${serviceName}
替換為您的應用名。export OTEL_TRACES_EXPORTER="otlp" export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="${httpEndpoint}" export OTEL_NODE_RESOURCE_DETECTORS="env,host,os" export OTEL_SERVICE_NAME="${serviceName}" export NODE_OPTIONS="--require @opentelemetry/auto-instrumentations-node/register" node main.js
說明有關OpenTelemetry環境變量的說明,請參見OpenTelemetry Node.js自動埋點配置。
訪問應用。
通過以下命令訪問應用,或者直接在瀏覽器中訪問該地址,即可生成調用鏈并上報至可觀測鏈路 OpenTelemetry 版。
curl localhost:7001/hello
方法二:手動埋點
在package.json中配置對OpenTelemetry的依賴。
"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" }
創建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(), [SemanticResourceAttributes.SERVICE_NAME]: "opentelemetry-express", //opentelemetry-express可替換為任意名稱。 }), });
通過Provider注冊HTTP和Express框架,自動監測并攔截HTTP和Express。
說明如需監測其他框架下的Node.js應用,請參見OpenTelemetry官方文檔。
const { registerInstrumentations } = require("@opentelemetry/instrumentation"); const { HttpInstrumentation } = require("@opentelemetry/instrumentation-http"); const { ExpressInstrumentation, } = require("@opentelemetry/instrumentation-express"); registerInstrumentations({ tracerProvider: provider, instrumentations: [new HttpInstrumentation(), ExpressInstrumentation], });
配置Exporter,導出數據到可觀測鏈路 OpenTelemetry 版。
請將下面代碼中的
<ENDPOINT>
和<AUTHENTICATION>
替換成前提條件中獲取的Endpoint和Authentication。const metadata = new grpc.Metadata(); metadata.set("Authentication", "<AUTHENTICATION>"); const exporter = new OTLPTraceExporter({ url: "<ENDPOINT>", metadata }); provider.addSpanProcessor(new SimpleSpanProcessor(exporter)); provider.register();
可選:添加自定義事件和屬性。
說明OpenTelemetry API的使用方法,請參見OpenTelemetry官方文檔。
const api = require("@opentelemetry/api"); const currentSpan = api.trace.getSpan(api.context.active()); currentSpan.addEvent("timestamp", { value: Date.now() }); currentSpan.setAttribute("tagKey-01", "tagValue-01");
在控制臺查看Trace
登錄ARMS控制臺后,在 頁面選擇目標應用,查看鏈路數據。
語言列顯示圖標的應用為接入應用監控的應用,顯示-圖標的應用為接入可觀測鏈路 OpenTelemetry 版的應用。
基于Express框架的Node.js應用完整示例
"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");
const provider = new NodeTracerProvider({
resource: new Resource({
[SemanticResourceAttributes.HOST_NAME]: require("os").hostname(),
[SemanticResourceAttributes.SERVICE_NAME]: "opentelemetry-express",
}),
});
registerInstrumentations({
tracerProvider: provider,
instrumentations: [new HttpInstrumentation(), ExpressInstrumentation],
});
const metadata = new grpc.Metadata();
metadata.set("Authentication", "<AUTHENTICATION>");
const exporter = new OTLPTraceExporter({ url: "<ENDPOINT>", metadata });
provider.addSpanProcessor(new SimpleSpanProcessor(exporter));
provider.register();
// 應用代碼
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");
});