opentelemetry-js

<a href="https://opentelemetry.io/docs/languages/js/getting-started/">入门指南</a>   •   <a href="https://open-telemetry.github.io/opentelemetry-js">API和SDK参考</a> <a href="https://github.com/open-telemetry/opentelemetry-js/releases"> <img alt="GitHub 发布（按日期排序的最新版本，包括预发布）" src="https://img.shields.io/github/v/release/open-telemetry/opentelemetry-js?include_prereleases&style=for-the-badge"> </a> <a href="https://codecov.io/gh/open-telemetry/opentelemetry-js/branch/main/"> <img alt="Codecov 状态" src="https://img.shields.io/codecov/c/github/open-telemetry/opentelemetry-js?style=for-the-badge"> </a> <a href="https://github.com/open-telemetry/opentelemetry-js/blob/main/LICENSE"> <img alt="许可证" src="https://yellow-cdn.veclightyear.com/835a84d5/e7e1548f-964c-4abc-afdc-619eb2228dd4.svg?style=for-the-badge"> </a> <a href="https://circleci.com/gh/open-telemetry/opentelemetry-js"> <img alt="构建状态" src="https://yellow-cdn.veclightyear.com/835a84d5/be7b3596-b30f-40a1-8cd5-031811b6a1fe.svg?style=shield"> </a> <img alt="测试版" src="https://img.shields.io/badge/status-beta-informational?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAAAXNSR0IArs4c6QAAAIRlWElmTU0AKgAAAAgABQESAAMAAAABAAEAAAEaAAUAAAABAAAASgEbAAUAAAABAAAAUgEoAAMAAAABAAIAAIdpAAQAAAABAAAAWgAAAAAAAACQAAAAAQAAAJAAAAABAAOgAQADAAAAAQABAACgAgAEAAAAAQAAABigAwAEAAAAAQAAABgAAAAA8A2UOAAAAAlwSFlzAAAWJQAAFiUBSVIk8AAAAVlpVFh0WE1MOmNvbS5hZG9iZS54bXAAAAAAADx4OnhtcG1ldGEgeG1sbnM6eD0iYWRvYmU6bnM6bWV0YS8iIHg6eG1wdGs9IlhNUCBDb3JlIDUuNC4wIj4KICAgPHJkZjpSREYgeG1sbnM6cmRmPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5LzAyLzIyLXJkZi1zeW50YXgtbnMjIj4KICAgICAgPHJkZjpEZXNjcmlwdGlvbiByZGY6YWJvdXQ9IiIKICAgICAgICAgICAgeG1sbnM6dGlmZj0iaHR0cDovL25zLmFkb2JlLmNvbS90aWZmLzEuMC8iPgogICAgICAgICA8dGlmZjpPcmllbnRhdGlvbj4xPC90aWZmOk9yaWVudGF0aW9uPgogICAgICA8L3JkZjpEZXNjcmlwdGlvbj4KICAgPC9yZGY6UkRGPgo8L3g6eG1wbWV0YT4KTMInWQAABK5JREFUSA2dVm1sFEUYfmd2b/f2Pkqghn5eEQWKrRgjpkYgpoRCLC0oxV5apAiGUDEpJvwxEQ2raWPU+Kf8INU/RtEedwTCR9tYPloxGNJYTTQUwYqJ1aNpaLH3sXu3t7vjvFevpSqt7eSyM+/czvM8877PzB3APBoLgoDLsNePF56LBwqa07EKlDGg84CcWsI4CEbhNnDpAd951lXE2NkiNknCCTLv4HtzZuvPm1C/IKv4oDNXqNDHragety2XVzjECZsJARuBMyRzJrh1O0gQwLXuxofxsPSj4hG8fMLQo7bl9JJD8XZfC1E5yWFOMtd07dvX5kDwg6+2++Chq8txHGtfPoAp0gOFmhYoNFkHjn2TNUmrwRdna7W1QSkU8hvbGk4uThLrapaiLA2E6QY4u/lS9ItHfvJkxYsTMVtnAJLipYIWtVrcdX+8+b8IVnPl/R81prbuPZ1jpYw+0aEUGSkdFsgyBIaFTXCm6nyaxMtJ4n+TeDhJzGqZtQZcuYDgqDwDbqb0JF9oRpIG1Oea3bC1Y6N3x/WV8Zh83emhCs++hlaghDw+8w5UlYKq2lU7Pl8IkvS9KDqXmKmEwdMppVPKwGSEilmyAwJhRwWcq7wYC6z4wZ1rrEoMWxecdOjZWXeAQClBcYDN3NwVwD9pGwqUSyQgclcmxpNJqCuwLmDh3WtvPqXdlt+6Oz70HPGDNSNBee/EOen+rGbEFqDENBPDbtdCp0ukPANmzO0QQJYUpyS5IJJI3Hqt4maS+EB3199ozm8EDU/6 这段文本似乎是一个Base64编码的图像数据,而不是可翻译的文本内容。它包含了一系列字母、数字和符号,用于表示二进制图像数据。这种编码无法直接翻译成中文,因为它不包含任何语义信息。如果您需要将这个数据转换成图像,可以使用适当的工具或程序来解码它。 <a href="https://github.com/open-telemetry/opentelemetry-js/blob/main/CONTRIBUTING.md">贡献</a>   •   <a href="https://github.com/open-telemetry/opentelemetry-js/tree/main/examples">示例</a>

关于本项目

这是 OpenTelemetry 的 JavaScript 版本，一个用于从应用程序收集跟踪、指标和日志的框架。

快速开始

以下描述了如何为基本的 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-base');
const { Resource } = require('@opentelemetry/resources');
const { SEMRESATTRS_SERVICE_NAME } = require('@opentelemetry/semantic-conventions');

// 配置 SDK 将遥测数据导出到控制台
// 启用元包中的所有自动插装
const traceExporter = new ConsoleSpanExporter();
const sdk = new opentelemetry.NodeSDK({
  resource: new Resource({
    [SEMRESATTRS_SERVICE_NAME]: 'my-service',
  }),
  traceExporter,
  instrumentations: [getNodeAutoInstrumentations()]
});

// 初始化 SDK 并注册到 OpenTelemetry API
// 这使 API 能够记录遥测数据
sdk.start();

// 在进程退出时优雅地关闭 SDK
process.on('SIGTERM', () => {
  sdk.shutdown()
    .then(() => console.log('跟踪已终止'))
    .catch((error) => console.log('终止跟踪时出错', error))
    .finally(() => process.exit(0));
});

运行您的应用程序

node -r ./tracing.js app.js

上述示例将向控制台输出有关您的 Node.js 应用程序的自动插装遥测数据。有关更深入的示例，请参阅入门指南。有关自动插装的更多信息，请参阅 @opentelemetry/sdk-trace-node，它为 Node.js 应用程序提供自动插装。如果自动插装不适合您的需求，或者您想创建手动跟踪，请参阅 @opentelemetry/sdk-trace-base。

库作者

如果您是想将 OpenTelemetry 构建到您的库中的库作者，请参阅文档。作为库作者，重要的是您只依赖公共 API 上发布的属性和方法。如果您使用 SDK 中任何不是公共 API 官方部分的属性或方法，当应用程序所有者使用不同的 SDK 实现时，您的库可能会出现问题。

支持的运行时

平台版本	支持情况
Node.JS `v22`	:heavy_check_mark:
Node.JS `v20`	:heavy_check_mark:
Node.JS `v18`	:heavy_check_mark:
Node.JS `v16`	:heavy_check_mark:
Node.JS `v14`	:heavy_check_mark:
更早的 Node 版本	参见 Node 支持
Web 浏览器	参见下面的浏览器支持

Node 支持

仅支持 Node.js 活跃或维护 LTS 版本。较早版本的 node 可能可以工作，但 OpenTelemetry 不对其进行测试，也不保证它们能正常工作。请注意，Node.JS v8 在 v8.12.0 之前的版本将无法工作，因为 OpenTelemetry Node 依赖于 v8.5.0 中引入的 perf_hooks 模块和从 v8.12.0 开始正确设置的 performance.timeOrigin。

浏览器支持

[!重要] 浏览器的客户端插装是实验性的，并且大多数未指定。如果您有兴趣提供帮助，请联系客户端插装 SIG。

目前没有官方支持的浏览器列表。OpenTelemetry 使用标准的 Web 技术开发，旨在在当前支持的主要浏览器版本中工作。

包版本兼容性

OpenTelemetry 作为 3 个类别的不同包发布：API、稳定 SDK 和实验性。 API 位于 /api，稳定 SDK 包位于 /packages 目录中，实验性包列在 /experimental/packages 目录中。实验目录中可能还有实验性信号的 API 包。所有稳定包以相同版本发布，所有实验性包以相同版本发布。下表描述了每组包的哪些版本预期可以一起工作。

稳定包	实验性包
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.44.x

<details> <summary>较早版本兼容性矩阵</summary> <table> <tr><th>稳定版包</th> <th>实验版包</th></tr> <tr><td>1.16.x</td> <td>0.42.x</td></tr> <tr><td>1.15.x</td> <td>0.41.x</td></tr> <tr><td>1.14.x</td> <td>0.40.x</td></tr> <tr><td>1.13.x</td> <td>0.39.x</td></tr> <tr><td>1.12.x</td> <td>0.38.x</td></tr> <tr><td>1.11.x</td> <td>0.37.x</td></tr> <tr><td>1.10.x</td> <td>0.36.x</td></tr> <tr><td>1.9.x</td> <td>0.35.x</td></tr> <tr><td>1.8.x (此版本及以后版本的指标功能需要 API >=1.3.0)</td> <td>0.34.x</td></tr> <tr><td>1.7.x</td> <td>0.33.x</td></tr> <tr><td>1.6.x</td> <td>0.32.x</td></tr> <tr><td>1.5.x</td> <td>0.31.x</td></tr> <tr><td>1.4.x</td> <td>0.30.x</td></tr> <tr><td>1.3.x</td> <td>0.29.x</td></tr> <tr><td>1.2.x</td> <td>0.29.x</td></tr> <tr><td>1.1.x</td> <td>0.28.x</td></tr> <tr><td>1.0.x</td> <td>0.27.x</td></tr> <tr><td>1.0.x (此版本及以后版本的追踪功能需要 API >=1.0.0)</td> <td>0.26.x</td></tr> </table> </details>

版本控制

每个包的当前版本可以在相应模块的 package.json 文件中找到。更多详情请参阅规范中的版本控制和稳定性文档。

功能状态

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

有关功能支持的更详细分析，请参阅规范遵从性矩阵。

贡献

我们非常欢迎您的帮助！使用标签 up-for-grabs 和 good first issue 来开始参与项目。关于如何构建和修改此项目的说明，请参阅贡献指南。

我们每周都有一次 SIG 会议！有关会议详情和记录，请查看社区页面。

社区成员

维护者 (@open-telemetry/javascript-maintainers)

Amir Blum，Odigos
Chengzhong Wu，Bloomberg
Daniel Dyla，Dynatrace
Jamie Danielson，Honeycomb
Marc Pichler，Dynatrace
Trent Mick，Elastic

在社区仓库中了解更多关于维护者角色的信息。

审批者 (@open-telemetry/javascript-approvers)

David Luna，Elastic
Hector Hernandez，Microsoft
Martin Kuba，Lightstep
Matthew Wear，LightStep
Naseem K. Ullah，Transit
Neville Wylie，Microsoft
Purvi Kanal，Honeycomb
Svetlana Brennan，New Relic

在社区仓库中了解更多关于审批者角色的信息。

分类者 (@open-telemetry/javascript-triagers)

Marylia Gutierrez，Grafana Labs

在社区仓库中了解更多关于分类者角色的信息。

荣誉退休成员

Bartlomiej Obecny，LightStep，维护者
Daniel Khan，Dynatrace，维护者
Mayur Kale，Google，维护者
Rauno Viskus，维护者
Valentin Marchaud，维护者
Brandon Gonzalez，LightStep，审批者
Roch Devost，DataDog，审批者
John Bley，Splunk，审批者
Mark Wolff，Microsoft，审批者
Olivier Albertini，Ville de Montréal，审批者
Gerhard Stöbich，Dynatrace，审批者
Haddas Bronfman，Cisco，审批者

在社区仓库中了解更多关于荣誉退休成员角色的信息。

感谢所有已经做出贡献的人

包

API

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

实现 / SDK

包	描述
@opentelemetry/sdk-trace-base	此模块提供对检测和span创建的完全控制。默认情况下不加载`async_hooks`或任何检测。它适用于服务器和浏览器环境。
@opentelemetry/sdk-metrics	此模块提供用于报告时间序列数据的工具和计量器。
@opentelemetry/sdk-trace-node	此模块为Node.js应用程序提供自动跟踪。它仅适用于服务器环境。
@opentelemetry/sdk-trace-web	此模块为Web应用程序提供自动检测和跟踪。它仅适用于浏览器环境。