OpenTelemetry cho Node.js (CommonJS và ES modules)

Node.js không cần sửa code: auto-instrumentations của OpenTelemetry vá http, fetch (undici), Express, Fastify, NestJS, client cơ sở dữ liệu, Pino, Winston và nhiều thư viện khác khi chúng được nạp, còn SDK đọc bộ biến chuẩn.

Đã kiểm ngày 2026-10-24 với node 22.23.4, @opentelemetry/sdk-node 0.300.0, @opentelemetry/auto-instrumentations-node 0.82.0, pino 10.4.0: traces đạt, logs đạt, log mang trace/span của request.

Cài đặt#

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

CommonJS (require)#

Nạp file register trước app:

export OTEL_SEMCONV_STABILITY_OPT_IN=httpexport OTEL_NODE_RESOURCE_DETECTORS=env,host,osnode --require @opentelemetry/auto-instrumentations-node/register app.js

Nếu không đổi được lệnh khởi động (PaaS, npm start, trình quản lý tiến trình), hãy đặt cờ vào NODE_OPTIONS: NODE_OPTIONS="--require @opentelemetry/auto-instrumentations-node/register".

ES modules (import)#

ES modules cần thêm loader hook, nếu không thì không thứ gì code của bạn import được gắn instrumentation — app vẫn chạy, nhưng không gửi span nào và log không mang trace ID:

export OTEL_SEMCONV_STABILITY_OPT_IN=httpexport OTEL_NODE_RESOURCE_DETECTORS=env,host,osnode --experimental-loader=@opentelemetry/instrumentation/hook.mjs --import @opentelemetry/auto-instrumentations-node/register app.mjs

App là ESM khi package.json có "type": "module" hoặc file vào có đuôi .mjs. TypeScript biên dịch ra CommonJS là CommonJS, dù mã nguồn trông thế nào.

Logs#

Pino và Bunyan được nối tự động: mỗi lệnh ghi log trong lúc xử lý request trở thành một bản ghi log OpenTelemetry mang trace ID và span ID của request đó, còn đầu ra thường (stdout, file) giữ nguyên. Winston cần thêm gói @opentelemetry/winston-transport cài cạnh nó. console.log không được thu — hãy dùng logger. (Lần chạy của Belvador dùng Pino.)

Các biến ở trên làm gì#

• OTEL_SEMCONV_STABILITY_OPT_IN=http cho span HTTP dùng tên thuộc tính ổn định (url.path, http.request.method, http.response.status_code) mà bộ lọc của Belvador dùng.

• OTEL_NODE_RESOURCE_DETECTORS=env,host,os mô tả máy mà không dùng detector process, vốn chép nguyên dòng lệnh — kèm mọi bí mật truyền trong đó — vào từng span.

Tắt bớt instrumentation#

Mỗi instrumentation tắt được theo tên, ví dụ các span hệ thống file gây nhiễu:

export OTEL_NODE_DISABLED_INSTRUMENTATIONS=fs,dns,net

Tiến trình chạy ngắn#

Script, CLI và handler serverless có thể thoát trước khi lô dữ liệu của exporter được gửi (mặc định khoảng năm giây). File register tự gửi nốt khi nhận SIGTERM và khi thoát bình thường; tiến trình gọi thẳng process.exit() hoặc bị kill sẽ mất lô cuối.

Cùng SDK Belvador#

Với lỗi, giữ SDK Belvador hoặc Sentry của bạn và đưa API OpenTelemetry cho SDK Belvador để lỗi mang ID của span đang chạy — xem Liên kết request. Đừng để hai công cụ cùng tạo span trong một tiến trình (một bên làm chủ tracing); với @sentry/node, xem Cùng SDK Sentry.