OpenTelemetry Node.js 接入观测云最佳实践

前言

这份最佳实践面向 Node.js 应用接入观测云的常见场景，目标是同时拿到：

• Trace
• Metric
• Profile

其中 Trace / Metric 走标准 OpenTelemetry 链路，Profile 走观测云扩展能力 @cloudcare/profiler-nodejs。

基础适配信息

适配版本：Node.js ^18.19.0 / >=20.6.0

统一上报端点：

• Trace：/otel/v1/traces
• Metric：/otel/v1/metrics
• Profile：/profiling/v1/input

实测 Demo 工程：GitHub 示例地址

开启 DataKit 采集

1. 开启 OTel 采集（Trace/Metric）

cd /usr/local/datakit/conf.d
cp samples/opentelemetry.conf.sample opentelemetry.conf

配置核心接口：

[[inputs.opentelemetry]]
  [inputs.opentelemetry.http]
    trace_api = "/otel/v1/traces"
    metric_api = "/otel/v1/metrics"

2. 开启性能剖析采集（Profile）

cd /usr/local/datakit/conf.d
cp samples/profile.conf.sample profile.conf
[[inputs.profile]]
  endpoints = ["/profiling/v1/input"]

3. 生效并验证

datakit service -R
datakit monitor

跨机器部署：确保上述三个接口对外开放、网络端口互通。

接入方案

1. Trace / Metric 接入

采用 OTLP HTTP 标准协议，使用官方 proto 导出器：

• 依赖包：@opentelemetry/exporter-trace-otlp-proto、@opentelemetry/exporter-metrics-otlp-proto
• 基础上报地址：http://127.0.0.1:9529/otel

2. Profile 接入

使用观测云专属扩展包，优先稳定、后迭代能力：

• 核心依赖：@cloudcare/profiler-nodejs
• 初期仅开启 wall CPU 剖析，链路稳定后再新增 heap 内存剖析

推荐默认配置

直接复用以下参数，无需自行调试，兼顾稳定与性能：

快速验证链路通畅

通过官方 Demo 一键验证全链路，无需自研测试代码：

npm install
OTEL_DIAG_LEVEL=DEBUG npm run demo

成功判定标准：

1. 请求可正常输出 traceId
2. 日志打印：Datakit profiling export succeeded for 1 profile(s)

总结

Node.js 接入观测云这件事，真正有效的做法不是一次性追求 “大而全”，而是分层推进。先保证 DataKit 采集器开启、端点可达，再用标准 OpenTelemetry 跑通 Trace / Metric，最后叠加观测云扩展的 Profile 能力。这样做的好处是，每一步都有明确的验证结果，每一层出现问题时也更容易定位。

如果你是在生产环境推进这项工作，建议默认采用本文里的保守配置：Trace / Metric 先稳定输出，Profile 先启用 wall，确认数据已经连续进入观测云后，再逐步开启 heap、调整采样周期，或者把配置推广到更多服务。这种方式节奏更稳，回滚更简单，也更符合真实线上系统的接入习惯。