关于本项目
这是 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 |
较早版本兼容性矩阵
稳定版包 | 实验版包 |
---|---|
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 来开始参与项目。关于如何构建和修改此项目的说明,请参阅 贡献指南。
我们每周都有一次 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应用程序提供自动检测和跟踪。它仅适用于浏览器环境。 |
兼容的导出器
OpenTelemetry是与供应商无关的,可以通过各种导出器实现将数据上传到任何后端。尽管OpenTelemetry支持许多后端,但供应商/用户也可以为专有和非官方支持的后端实现自己的导出器。
请查看OpenTelemetry注册表以获取可用导出器列表。
检测
OpenTelemetry可以使用检测自动收集跟踪数据。
如需请求对列表中未包含的模块的自动跟踪支持,请提交问题。或者,供应商/用户可以自行编写检测。
目前,OpenTelemetry支持以下自动跟踪:
Node检测
核心
贡献
这些检测托管在 https://github.com/open-telemetry/opentelemetry-js-contrib/tree/master/plugins/node
Web检测
核心
贡献
这些检测托管在 https://github.com/open-telemetry/opentelemetry-js-contrib/tree/master/plugins/web
适配器
包 | 描述 |
---|---|
@opentelemetry/shim-opentracing | OpenTracing适配器允许现有的OpenTracing检测向OpenTelemetry报告 |
有用的链接
- 升级指南:升级指南
- 有关OpenTelemetry的更多信息,请访问:https://opentelemetry.io/
- 如需本项目的帮助或反馈,请加入我们的GitHub讨论区
许可证
Apache 2.0 - 更多信息请参见LICENSE。