Node.js
5 分钟内为你的应用获取遥测数据！
这个页面将向你展示如何在 Node.js 中开始使用 OpenTelemetry。
Note
OpenTelemetry for Node.js 的日志记录库仍在开发中，因此下面没有提供示例。 有关状态详情，请参阅状态和发布。
前提条件
确保你已安装以下内容：
- Node.js
- TypeScript，如果您将使用 TypeScript。
示例应用程序
以下示例使用一个基本的 Express 应用程序。 如果您不使用 Express，也没关系——您也可以将 OpenTelemetry JavaScript 与其他 Web 框架一起使用，例如 Koa 和 Nest.JS。 有关受支持框架的库的完整列表，请参阅注册表。
有关更详细的示例，请参阅示例。
依赖项
起初，设置一个新目录中的空 package.json 文件：
npm init -y 接下来，安装 Express 依赖项。
npm install express @types/express npm install -D tsx # 一个可通过 Node 直接运行 TypeScript（.ts）文件的工具 npm install express 创建和启动一个 HTTP 服务器
创建一个名为 app.ts（如果不使用 TypeScript，则为 app.js）的文件，并将以下代码添加到其中：
/*app.ts*/ import express, { Express } from 'express'; const PORT: number = parseInt(process.env.PORT || '8080'); const app: Express = express(); function getRandomNumber(min: number, max: number) { return Math.floor(Math.random() * (max - min + 1) + min); } app.get('/rolldice', (req, res) => { res.send(getRandomNumber(1, 6).toString()); }); app.listen(PORT, () => { console.log(`Listening for requests on http://localhost:${PORT}`); }); /*app.js*/ const express = require('express'); const PORT = parseInt(process.env.PORT || '8080'); const app = express(); function getRandomNumber(min, max) { return Math.floor(Math.random() * (max - min + 1) + min); } app.get('/rolldice', (req, res) => { res.send(getRandomNumber(1, 6).toString()); }); app.listen(PORT, () => { console.log(`Listening for requests on http://localhost:${PORT}`); }); 执行以下命令启动应用，然后在浏览器中打开 http://localhost:8080/rolldice，验证应用是否正常运行。
$ npx tsx app.ts Listening for requests on http://localhost:8080 $ node app.js Listening for requests on http://localhost:8080 插桩
下面展示了如何安装、初始化和运行使用 OpenTelemetry 进行插桩的应用程序。
更多依赖项
首先，安装 Node SDK 和自动插桩包。
Node SDK 让你可以使用多个配置默认值来初始化 OpenTelemetry，这些默认值适用于大多数用例。
auto-instrumentations-node 包安装了插桩库，这些库将自动为库中调用的代码创建相应的 Span。 在这种情况下，它为 Express 提供了插桩，使示例应用程序能够自动为每个传入请求创建 Span。
npm install @opentelemetry/sdk-node \ @opentelemetry/api \ @opentelemetry/auto-instrumentations-node \ @opentelemetry/sdk-metrics \ @opentelemetry/sdk-trace-node 要查找所有自动插桩模块，可以查看注册表。
安装
插桩设置和配置必须在应用程序代码之前运行。一个常用的工具是 –import 标志。
创建一个名为 instrumentation.ts（如果不使用 TypeScript，则为 instrumentation.mjs）的文件，其中包含插桩设置代码。
Note
以下示例使用 --import instrumentation.ts（TypeScript）要求 Node.js v.20 或更高版本。 如果您使用的是 Node.js v.18，请使用 JavaScript 示例。
/*instrumentation.ts*/ import { NodeSDK } from '@opentelemetry/sdk-node'; import { ConsoleSpanExporter } from '@opentelemetry/sdk-trace-node'; import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node'; import { PeriodicExportingMetricReader, ConsoleMetricExporter, } from '@opentelemetry/sdk-metrics'; const sdk = new NodeSDK({ traceExporter: new ConsoleSpanExporter(), metricReader: new PeriodicExportingMetricReader({ exporter: new ConsoleMetricExporter(), }), instrumentations: [getNodeAutoInstrumentations()], }); sdk.start(); /*instrumentation.mjs*/ import { NodeSDK } from '@opentelemetry/sdk-node'; import { ConsoleSpanExporter } from '@opentelemetry/sdk-trace-node'; import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node'; import { PeriodicExportingMetricReader, ConsoleMetricExporter, } from '@opentelemetry/sdk-metrics'; const sdk = new NodeSDK({ traceExporter: new ConsoleSpanExporter(), metricReader: new PeriodicExportingMetricReader({ exporter: new ConsoleMetricExporter(), }), instrumentations: [getNodeAutoInstrumentations()], }); sdk.start(); 运行已完成插桩的应用
现在，你可以像平常一样运行应用程序，但可以使用 --import 标志在应用程序代码之前加载插桩。 确保你的 NODE_OPTIONS 环境变量中没有其他冲突的 --import 或 --require 标志， 例如 --require @opentelemetry/auto-instrumentations-node/register。
$ npx tsx --import ./instrumentation.ts app.ts Listening for requests on http://localhost:8080 $ node --import ./instrumentation.mjs app.js Listening for requests on http://localhost:8080 在浏览器中打开 http://localhost:8080/rolldice 并重新加载页面几次。 等待一段时间后，你应该会在控制台中看到 ConsoleSpanExporter 打印的 Span。
查看示例输出
{ resource: { attributes: { 'host.arch': 'arm64', 'host.id': '8FEBBC33-D6DA-57FC-8EF0-1A9C14B919F8', 'process.pid': 12460, // …… 部分资源属性已省略…… 'process.runtime.version': '22.17.1', 'process.runtime.name': 'nodejs', 'process.runtime.description': 'Node.js', 'telemetry.sdk.language': 'nodejs', 'telemetry.sdk.name': 'opentelemetry', 'telemetry.sdk.version': '2.0.1' } }, instrumentationScope: { name: '@opentelemetry/instrumentation-express', version: '0.52.0', schemaUrl: undefined }, traceId: '61e8960c349ca2a3a51289e050fd3b82', parentSpanContext: { traceId: '61e8960c349ca2a3a51289e050fd3b82', spanId: '631b666604f933bc', traceFlags: 1, traceState: undefined }, traceState: undefined, name: 'request handler - /rolldice', id: 'd8fcc05ac4f60c99', kind: 0, timestamp: 1755719307779000, duration: 2801.5, attributes: { 'http.route': '/rolldice', 'express.name': '/rolldice', 'express.type': 'request_handler' }, status: { code: 0 }, events: [], links: [] } { resource: { attributes: { 'host.arch': 'arm64', 'host.id': '8FEBBC33-D6DA-57FC-8EF0-1A9C14B919F8', 'process.pid': 12460, // …… 部分资源属性已省略…… 'process.runtime.version': '22.17.1', 'process.runtime.name': 'nodejs', 'process.runtime.description': 'Node.js', 'telemetry.sdk.language': 'nodejs', 'telemetry.sdk.name': 'opentelemetry', 'telemetry.sdk.version': '2.0.1' } }, instrumentationScope: { name: '@opentelemetry/instrumentation-http', version: '0.203.0', schemaUrl: undefined }, traceId: '61e8960c349ca2a3a51289e050fd3b82', parentSpanContext: undefined, traceState: undefined, name: 'GET /rolldice', id: '631b666604f933bc', kind: 1, timestamp: 1755719307777000, duration: 4705.75, attributes: { 'http.url': 'http://localhost:8080/rolldice', 'http.host': 'localhost:8080', 'net.host.name': 'localhost', 'http.method': 'GET', 'http.scheme': 'http', 'http.target': '/rolldice', 'http.user_agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:141.0) Gecko/20100101 Firefox/141.0', 'http.flavor': '1.1', 'net.transport': 'ip_tcp', 'net.host.ip': '::ffff:127.0.0.1', 'net.host.port': 8080, 'net.peer.ip': '::ffff:127.0.0.1', 'net.peer.port': 63067, 'http.status_code': 200, 'http.status_text': 'OK', 'http.route': '/rolldice' }, status: { code: 0 }, events: [], links: [] } 生成的 Span 会追踪针对 /rolldice 路由的请求生命周期。
再向该端点发送几次请求。片刻之后，你将在控制台输出中看到指标数据，例如：
查看示例输出
{ descriptor: { name: 'http.server.duration', type: 'HISTOGRAM', description: 'Measures the duration of inbound HTTP requests.', unit: 'ms', valueType: 1, advice: {} }, dataPointType: 0, dataPoints: [ { attributes: { 'http.scheme': 'http', 'http.method': 'GET', 'net.host.name': 'localhost', 'http.flavor': '1.1', 'http.status_code': 200, 'net.host.port': 8080, 'http.route': '/rolldice' }, startTime: [ 1755719307, 782000000 ], endTime: [ 1755719482, 940000000 ], value: { min: 1.439792, max: 5.775, sum: 15.370167, buckets: { boundaries: [ 0, 5, 10, 25, 50, 75, 100, 250, 500, 750, 1000, 2500, 5000, 7500, 10000 ], counts: [ 0, 5, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 ] }, count: 6 } }, { attributes: { 'http.scheme': 'http', 'http.method': 'GET', 'net.host.name': 'localhost', 'http.flavor': '1.1', 'http.status_code': 304, 'net.host.port': 8080, 'http.route': '/rolldice' }, startTime: [ 1755719433, 609000000 ], endTime: [ 1755719482, 940000000 ], value: { min: 1.39575, max: 1.39575, sum: 1.39575, buckets: { boundaries: [ 0, 5, 10, 25, 50, 75, 100, 250, 500, 750, 1000, 2500, 5000, 7500, 10000 ], counts: [ 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 ] }, count: 1 } } ] } { descriptor: { name: 'nodejs.eventloop.utilization', type: 'OBSERVABLE_GAUGE', description: 'Event loop utilization', unit: '1', valueType: 1, advice: {} }, dataPointType: 2, dataPoints: [ { attributes: {}, startTime: [ 1755719362, 939000000 ], endTime: [ 1755719482, 940000000 ], value: 0.00843049454565211 } ] } { descriptor: { name: 'v8js.gc.duration', type: 'HISTOGRAM', description: 'Garbage collection duration by kind, one of major, minor, incremental or weakcb.', unit: 's', valueType: 1, advice: { explicitBucketBoundaries: [ 0.01, 0.1, 1, 10 ] } }, dataPointType: 0, dataPoints: [ { attributes: { 'v8js.gc.type': 'minor' }, startTime: [ 1755719303, 5000000 ], endTime: [ 1755719482, 940000000 ], value: { min: 0.0005120840072631835, max: 0.0022552499771118163, sum: 0.006526499509811401, buckets: { boundaries: [ 0.01, 0.1, 1, 10 ], counts: [ 6, 0, 0, 0, 0 ] }, count: 6 } }, { attributes: { 'v8js.gc.type': 'incremental' }, startTime: [ 1755719310, 812000000 ], endTime: [ 1755719482, 940000000 ], value: { min: 0.0003403329849243164, max: 0.0012867081165313721, sum: 0.0016270411014556885, buckets: { boundaries: [ 0.01, 0.1, 1, 10 ], counts: [ 2, 0, 0, 0, 0 ] }, count: 2 } }, { attributes: { 'v8js.gc.type': 'major' }, startTime: [ 1755719310, 830000000 ], endTime: [ 1755719482, 940000000 ], value: { min: 0.0025888750553131105, max: 0.005744750022888183, sum: 0.008333625078201293, buckets: { boundaries: [ 0.01, 0.1, 1, 10 ], counts: [ 2, 0, 0, 0, 0 ] }, count: 2 } } ] } 下一步操作
通过对你自己的代码库进行手动插桩，丰富自动生成的插桩。 这将为你提供定制化的可观测性数据。
你还需要配置一个合适的导出器，将导出你的遥测数据到一个或多个遥测后端。
如果你想探索一个更复杂的示例，请查看 OpenTelemetry Demo， 其中包括基于 JavaScript 的支付服务和基于 TypeScript 的前端服务。
调试
出现问题了吗？你可以启用诊断日志记录来验证 OpenTelemetry 是否正确初始化：
/*instrumentation.ts*/ import { diag, DiagConsoleLogger, DiagLogLevel } from '@opentelemetry/api'; // 为了调试，将日志级别设置为 DiagLogLevel.DEBUG diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.INFO); // const sdk = new NodeSDK({... /*instrumentation.mjs*/ import { diag, DiagConsoleLogger, DiagLogLevel } from '@opentelemetry/api'; // 为了调试，将日志级别设置为 DiagLogLevel.DEBUG diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.INFO); // const sdk = new NodeSDK({... 意见反馈
这个页面对您有帮助吗？
Thank you. Your feedback is appreciated!
Please let us know how we can improve this page. Your feedback is appreciated!