Node.js 零代码接入¶

Beacon Node.js 支持该软件包已验证的 Node.js 维护版本，最低为 Node.js 18.19。 Security 的运行时要求更严格，详见下文。

接入前，请先完成公共配置，开启 DataKit OpenTelemetry 采集器。以下命令以 Linux/macOS Shell 为例，假设应用与 DataKit 部署在同一主机；跨主机或容器部署时，请替换 127.0.0.1 并调整监听地址。

安装¶

npm install @beacon-observability/nodejs

启动¶

export OTEL_SERVICE_NAME=my-node-service
export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4317
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export NODE_OPTIONS="--require @beacon-observability/nodejs/register"
node app.js

保留应用原有的 node 命令。如果 NODE_OPTIONS 已有内容，请追加 --require，不要覆盖原参数。

调试与诊断¶

保留上文的 NODE_OPTIONS 预加载配置，临时开启 OpenTelemetry 诊断日志：

OTEL_LOG_LEVEL=debug node app.js > beacon-nodejs-debug.log 2>&1

日志写入终端，上述命令将标准输出和标准错误一起保存。启用 Security 时，继续使用其要求的 ESM --import 预加载方式。

排障后恢复原启动命令；若在部署环境中设置了 OTEL_LOG_LEVEL=debug，请移除该设置并重启应用。

Profile¶

先开启 DataKit Profile 采集器，再设置以下变量并沿用上文的启动方式。Profile 使用独立的 HTTP 上传地址，不复用 OTLP Trace 地址。

@beacon-observability/nodejs 已包含 Profile 能力。保留 Node.js 零代码指南中的预加载配置，并设置支持兼容 pprof multipart 格式的 HTTP 接收端：

export NODE_OPTIONS="--require @beacon-observability/nodejs/register"
export OTEL_SERVICE_NAME=my-node-service
export OTEL_PROFILING_ENABLED=true
export OTEL_PROFILING_PPROF_UPLOAD_URL=http://127.0.0.1:9529/profiling/v1/input
node app.js

默认启用 wall profile。如需增加 heap profile：

export OTEL_PROFILING_MEMORY_ENABLED=true

默认上传周期为 60 秒。OTEL_PROFILING_EXPORT_INTERVAL 可以按秒调整周期，OTEL_PROFILING_PPROF_HEADERS 用于设置以逗号分隔的 名称:值 HTTP Header。

参数参考¶

环境变量名称区分大小写。

环境变量	类型 / 可选值	默认值	说明
`OTEL_PROFILING_ENABLED`	布尔值；`true`、`1`、`yes`、`on` 表示启用	`false`	启用 pprof 采集。
`OTEL_PROFILING_PPROF_UPLOAD_URL`	HTTP(S) URL	未设置	启用 Profile 时必填，用于接收 multipart pprof 上传。
`OTEL_PROFILING_EXPORT_INTERVAL`	正数，秒	`60`	Profile 采集和上传间隔。
`OTEL_PROFILING_MEMORY_ENABLED`	布尔值	`false`	在默认 wall-time Profile 之外增加 heap Profile。
`OTEL_PROFILING_PPROF_HEADERS`	逗号分隔的 `名称=值` 或 `名称:值`	空	附加 HTTP 请求头。

导出器还会把 OTEL_SERVICE_NAME，以及 OTEL_RESOURCE_ATTRIBUTES 中的 service.version、deployment.environment.name（或 deployment.environment）和 host.name 作为 Profile 元数据。

Security¶

Security 已包含在软件包中，支持 Node.js 22.22.3+ 或 24.11.1+，需使用 ESM --import 预加载而不是 --require。参阅 Node.js Security 指南。

验证接入¶

访问应用接口，产生经过受支持框架或依赖库的请求，再进入观测云「应用性能监测 > 链路」，按上文服务名筛选。完整检查步骤参见公共配置，无数据时参见故障排查。