opentelemetry-js:JavaScript 可观测性框架，用于收集应用程序的追踪、指标和日志

关于本项目

这是 OpenTelemetry 的 JavaScript 版本，一个用于从应用程序中采集链路追踪、指标和日志的框架。

快速入门

OpenTelemetry JS 的多数文档均以编译后的应用程序以 CommonJS 方式运行为前提进行编写。 如需了解 ECMAScript Modules 与 CommonJS 的更多详情，请参阅 esm-support。

以下内容介绍如何为基础 Web 应用程序配置链路追踪。 如需更详细的文档，请参见网站 https://opentelemetry.io/docs/instrumentation/js/。

安装

NPM 上带有 latest 标签的依赖项之间应相互兼容。 更多信息，请参见下方的版本兼容矩阵。

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

注意： auto-instrumentations-node 是来自 opentelemetry-js-contrib 的元包，它提供了一种初始化多个 Node.js 插桩的便捷方式。

设置追踪

// tracing.js

'use strict'

const process = require('process');
const opentelemetry = require('@opentelemetry/sdk-node');
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
const { ConsoleSpanExporter } = require('@opentelemetry/sdk-trace');
const { resourceFromAttributes } = require('@opentelemetry/resources');
const { ATTR_SERVICE_NAME } = require('@opentelemetry/semantic-conventions');

// configure the SDK to export telemetry data to the console
// enable all auto-instrumentations from the meta package
const traceExporter = new ConsoleSpanExporter();
const sdk = new opentelemetry.NodeSDK({
  resource: resourceFromAttributes({
    [ATTR_SERVICE_NAME]: 'my-service',
  }),
  traceExporter,
  instrumentations: [getNodeAutoInstrumentations()]
});

// initialize the SDK and register with the OpenTelemetry API
// this enables the API to record telemetry
sdk.start();

// gracefully shut down the SDK on process exit
process.on('SIGTERM', () => {
  sdk.shutdown()
    .then(() => console.log('Tracing terminated'))
    .catch((error) => console.log('Error terminating tracing', error))
    .finally(() => process.exit(0));
});

运行你的应用程序

node -r ./tracing.js app.js

上面的示例会将关于您的 Node.js 应用程序的自动插桩遥测数据输出到控制台。如需更深入的示例，请参阅入门指南。

调试设置

按照上述方式插桩的应用程序可能未表现出预期行为。 例如，如果应用程序本应将数据发送到 Open Telemetry collector，但该 collector 可能没有收到任何数据。可以通过启用诊断日志记录器来深入了解此类问题：

// Added as additional configuration to tracing.js

const {
  diag,
  DiagConsoleLogger,
  DiagLogLevel
} = require('@opentelemetry/api');
diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.DEBUG);

库作者

如果你是一位希望将 OpenTelemetry 集成到库中的库作者，请参见文档。作为库作者，你只能依赖公共 API 中公开的属性和方法，这一点非常重要。如果你使用了 SDK 中任何未正式纳入公共 API 的属性或方法，当应用所有者采用不同的 SDK 实现时，你的库可能会失效。

支持的运行时

平台版本	支持
Node.js v24	✔️
Node.js v22	✔️
Node.js v20	✔️
Node.js v18	✔️
更早的 Node 版本	参见 Node 支持
Web 浏览器	参见下文 浏览器支持

Node 支持

仅支持 Node.js Active 或 Maintenance LTS 版本。 早期版本的 Node 可能可以工作，但 OpenTelemetry 未对其进行测试，也不保证能够正常工作。

浏览器支持

OpenTelemetry 不针对特定浏览器 / 运行时的版本进行定义，而是根据底层使用的语言特性来确定最低支持版本。

当前最低语言特性支持级别设为 ECMAScript 2022，这些特性在所有现代浏览器 / 运行时中均可用。

这意味着，如果你的目标环境或最终用户使用不支持 ES2022 的浏览器 / 运行时，你需要转译代码，并为缺失的特性提供必要的 polyfill，以确保与目标环境兼容。由于使用不支持 ES2022 的浏览器或运行时而产生的任何支持问题，都将以“不修复”状态关闭。

随着项目演进以及底层语言特性的发展，这一最低支持级别可能会发生变化。

TypeScript 支持

OpenTelemetry JavaScript 使用 TypeScript v5.2.2 构建。如果你有依赖它的 TypeScript 项目（应用、库、插桩等）， 我们建议使用相同或更高版本来编译该项目。

OpenTelemetry JavaScript 将遵循 DefinitelyType 的 TypeScript 支持政策，该政策设置了 2 年的支持窗口。对于 2 年以前的 TypeScript 版本，OpenTelemetry JavaScript 将在次要版本中停止支持。

包版本兼容性

OpenTelemetry 以一组不同包的形式发布，分为三类：API、稳定版 SDK 和实验性包。 API 位于 /api，稳定版 SDK 包位于 /packages 目录，实验性包列于 /experimental/packages 目录。 实验目录中也可能包含用于实验性信号的 API 包。 所有稳定版包均以同一版本发布，所有实验性包也以同一版本发布。 下表说明了各组包中哪些版本预期可以配合使用。

稳定版包	实验性包
2.0.x	0.200.x
1.30.x	0.57.x
1.29.x	0.56.x
1.28.x	0.55.x
1.27.x	0.54.x
1.25.x	0.52.x

旧版本兼容性矩阵

稳定版包	实验性包
1.24.x	0.51.x
1.23.x	0.50.x
1.22.x	0.49.x
1.21.x	0.48.x
1.20.x	0.47.x
1.19.x	0.46.x
1.18.x	0.45.x
1.17.x	0.43.x, 0.44.x
1.16.x	0.42.x
1.15.x	0.41.x
1.14.x	0.40.x
1.13.x	0.39.x
1.12.x	0.38.x
1.11.x	0.37.x
1.10.x	0.36.x
1.9.x	0.35.x
1.8.x（此版本及更高版本针对指标需要 API >=1.3.0）	0.34.x
1.7.x	0.33.x
1.6.x	0.32.x
1.5.x	0.31.x
1.4.x	0.30.x
1.3.x	0.29.x
1.2.x	0.29.x
1.1.x	0.28.x
1.0.x	0.27.x
1.0.x（此版本及更高版本针对追踪需要 API >=1.0.0）	0.26.x

版本管理

每个包的当前版本均可在该模块对应的 package.json 文件中找到。更多详细信息，请参阅规范中的版本与稳定性文档。

功能状态

信号	API 状态	SDK 状态
追踪	稳定	稳定
指标	稳定	稳定
日志	开发中	开发中

有关功能支持的详细分解，请参阅规范合规矩阵。

贡献

我们非常欢迎您的参与！使用 up-for-grabs 和 good first issue 标签即可开始参与项目。有关如何构建和修改本项目的说明，请参阅 CONTRIBUTING 指南。

我们每周都会召开 SIG 会议！会议详情和纪要请参见社区页面。

维护者

• Chengzhong Wu, Bloomberg
• Daniel Dyla, Dynatrace
• David Luna, Elastic
• Jamie Danielson, Honeycomb
• Marc Pichler, Dynatrace
• Marylia Gutierrez, Grafana Labs
• Trent Mick, Elastic

关于维护者角色的更多信息，请参阅社区仓库。

审批者

• Hector Hernandez, Microsoft
• Jackson Weber, Microsoft
• Martin Kuba, Grafana Labs
• Raphaël Thériault, SolarWinds

此外，浏览器 SIG 维护者 会被授予浏览器目标包的审批者角色，具体以本仓库的 CODEOWNERS 文件中的定义为准。

关于审批者角色的更多信息，请参阅社区仓库。

问题分类者

本团队成员拥有对 opentelemetry-js.git 和 opentelemetry-js-contrib.git 的问题分类权限。

• N/A

如需了解问题分类者角色的更多信息，请参阅社区仓库。

Contrib 问题分类者

本团队成员拥有对 opentelemetry-js-contrib.git 的问题分类权限。 通常，本团队成员是 contrib 仓库中一个或多个包的组件负责人。

• Aaron Abbott, Google
• Abhinav Mathur, AppDynamics
• Bartlomiej Obecny
• Daniel Li
• dashpole
• dylanrussell
• Florencia Acosta, Embrace
• henrinormak
• Jackson Weber, Microsoft
• Jaryk, Volvo Cars
• Jonathan Lee
• Jonathan Munz, Embrace
• kirrg001, Instana
• MartenH, Splunk
• Mike Goldsmith, Honeycomb
• Motti
• naseemkullah
• onurtemizkan
• psx95
• Punya Biswal, Google
• sharadraju
• Siim Kallas, Splunk
• sudarshan12s
• t2t2, Splunk
• Trivikram Kamat, AWS
• weyert
• yiyuan-he

如需了解问题分类者角色的更多信息，请参阅社区仓库。

荣誉成员

• Amir Blum，维护者
• Bartlomiej Obecny，维护者
• Brandon Gonzalez，审批者
• Daniel Khan，维护者
• Gerhard Stöbich，审批者
• Haddas Bronfman，审批者
• John Bley，审批者
• Mark Wolff，审批者
• Matthew Wear，审批者
• Mayur Kale，维护者
• Naseem K. Ullah，审批者
• Neville Wylie，审批者
• Olivier Albertini，审批者
• Purvi Kanal，审批者
• Rauno Viskus，维护者
• Roch Devost，审批者
• Svetlana Brennan，审批者
• Valentin Marchaud，维护者

有关荣誉成员角色的更多信息，请参阅 社区仓库。

感谢所有贡献者！

包

API

包	描述
@opentelemetry/api	该包为 OpenTelemetry 核心链路追踪和指标模型提供 TypeScript 接口、枚举以及空操作实现。它适用于服务端和浏览器环境。
@opentelemetry/core	该包为 OpenTelemetry API 中的链路追踪和指标提供默认实现和空操作实现。它适用于服务端和浏览器环境。

实现 / SDKs

包	描述
@opentelemetry/sdk-trace	该模块提供对插桩和 span 创建的完全控制。默认不会加载 async_hooks 或任何插桩。适用于服务端和浏览器场景。
@opentelemetry/sdk-metrics	该模块提供用于上报时间序列数据的测量器和计量器。

兼容导出器

OpenTelemetry 与厂商无关，可通过多种导出器实现将数据上传至任意后端。尽管 OpenTelemetry 已支持许多后端，供应商/用户也可以为专有或非官方支持的后端实现自己的导出器。

可查阅 OpenTelemetry registry 获取可用导出器的列表。

插桩

OpenTelemetry 可以使用插桩自动收集追踪数据。

如需为未包含在此列表中的模块申请自动追踪支持，请提交 issue。此外，供应商/用户可以自行编写插桩。

目前，OpenTelemetry 支持以下自动追踪：

Node 插桩

核心

• @opentelemetry/instrumentation-grpc
• @opentelemetry/instrumentation-http

Contrib

这些插桩托管在 https://github.com/open-telemetry/opentelemetry-js-contrib/tree/master/plugins/node

Web 插桩

核心

• @opentelemetry/instrumentation-xml-http-request
• @opentelemetry/instrumentation-fetch

Contrib

这些插桩托管在 https://github.com/open-telemetry/opentelemetry-js-contrib/tree/master/plugins/web

Shims

包	描述
@opentelemetry/shim-opentracing	OpenTracing shim 允许现有的 OpenTracing 插桩上报至 OpenTelemetry

相关链接

• 升级到 SDK 2.x 指南
• 有关 OpenTelemetry 的更多信息，请访问：https://opentelemetry.io/
• 如需获取帮助或反馈，欢迎加入 GitHub Discussions

许可证

Apache 2.0 - 更多信息请参阅 LICENSE。