OpenTelemetry JavaScript：为 Node.js 应用接入 traces、metrics 与 logs

项目用途

OpenTelemetry JavaScript 是 OpenTelemetry 的 JavaScript 客户端，用于从应用收集 traces、metrics 和 logs。它适合希望在 JavaScript 或 Node.js 服务中建立统一遥测采集入口的开发者、平台工程师、可观测性团队，以及需要把遥测能力集成进库的作者。仓库采用 Apache License 2.0，项目本身未归档。

README 将 tracing、metrics 和 logs 的 API 与 SDK 状态标为 Stable。不过，“稳定”不等于接入后无需设计：团队仍需决定采集哪些信号、如何导出、如何控制数据量，以及如何处理敏感属性。这些具体策略不能仅凭项目页面确认，部署前应结合自身后端和数据治理要求验证。

已知功能与接入方式

项目提供 API、稳定 SDK 和实验包等不同类别。README 展示了 Node.js 场景：通过 NodeSDK 初始化资源与 tracing exporter，并可使用来自 opentelemetry-js-contrib 的自动插桩元包启用多种 Node.js 插桩。示例使用 ConsoleSpanExporter 输出 span，适合先确认初始化和数据生成是否正常；它并不代表生产环境应直接把遥测写到控制台。

项目文档同时考虑 CommonJS 与 ECMAScript Modules，但 README 明确指出，许多文档假设编译后的应用以 CommonJS 运行。使用 ESM、打包器或框架时，应先核对模块解析和初始化时机。库作者则应只依赖公开 API；使用 SDK 内部属性或方法，可能在应用采用不同 SDK 实现时造成破坏性问题。

采用前的限制

Node.js 方面，README 表示仅支持 Active 或 Maintenance LTS；未列出的旧版本可能可以运行，但未经过项目测试，也不保证可用。若采用 v3.0.0，最低 Node.js 已提升至 >=22.15.0，Node.js 18 和 20 不再支持，同时存在公共接口变化，实验包需要使用 0.300.0 才与该版本兼容。因此，升级前应检查运行时、锁文件、实验包及自研封装。

v3.0.0 还改变了构建产物和 exports 规则，深层导入构建目录不再解析。依赖内部路径的应用或库需要迁移到公开入口，不能简单假设旧路径换个文件名就能继续工作。浏览器端客户端插桩仍属 experimental，且最低语言特性为 ECMAScript 2022；目标环境不满足时需要自行转译并提供必要 polyfill。React Native 与 Expo 使用浏览器实现，也有 Metro、React Native 版本要求，不能直接套用 Node.js 部署方案。

部署考虑

落地时建议先在单一服务中验证 SDK 初始化、资源属性、导出链路和优雅关闭，再扩展到更多服务。确认遥测是否真正抵达后端时，可使用诊断日志辅助排查，但应避免在生产环境无控制地提高日志量。依赖版本应按项目兼容矩阵管理，尤其要区分稳定包和实验包。最终还需评估采集内容、保留策略、访问权限与成本；这些方面本项目资料未提供具体保证，不能把“支持某信号”理解为完整的生产治理方案。

资料来源

• GitHub repository metadata
• Project README
• Official release
• Official project page

资料核对日期：2026-10-23