Node.js zero-code instrumentation¶

Beacon Node.js supports the maintained Node.js runtime lines tested by the package, starting with Node.js 18.19. Security has a narrower runtime requirement documented below.

Before starting, enable the DataKit OpenTelemetry input as described in Common configuration. The commands use a Linux/macOS shell and assume that the application and DataKit run on the same host. Replace 127.0.0.1 and adjust the listening address for remote or container deployments.

Install¶

npm install @beacon-observability/nodejs

Run¶

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

Keep the application's existing node command. If NODE_OPTIONS already contains options, append the --require entry instead of replacing them.

Debugging and diagnostics¶

Retain the NODE_OPTIONS preload configuration above and temporarily enable OpenTelemetry diagnostic logging:

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

Diagnostic logs go to the console; this command captures both standard output and standard error. When Security is enabled, keep its required ESM --import preload.

Return to the normal launch command after troubleshooting. If OTEL_LOG_LEVEL=debug was added to the deployment environment, remove it and restart the application.

Profile¶

Enable the DataKit Profile input, then set the variables below and retain the launch configuration above. Profiles use a separate HTTP upload endpoint, independent of the OTLP traces endpoint.

Profiling is included in @beacon-observability/nodejs. Keep the preload from the Node.js zero-code guide, then configure an HTTP receiver that accepts the compatible pprof multipart layout:

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 profiling is enabled by default. Add heap profiles with:

export OTEL_PROFILING_MEMORY_ENABLED=true

The default upload interval is 60 seconds. OTEL_PROFILING_EXPORT_INTERVAL changes it in seconds, and OTEL_PROFILING_PPROF_HEADERS supplies comma-separated name:value HTTP headers.

Configuration reference¶

Environment-variable names are case-sensitive.

Environment variable	Type / accepted values	Default	Description
`OTEL_PROFILING_ENABLED`	Boolean: `true`, `1`, `yes`, `on` enable it	`false`	Enables pprof collection.
`OTEL_PROFILING_PPROF_UPLOAD_URL`	HTTP(S) URL	Unset	Required when profiling is enabled; receives multipart pprof uploads.
`OTEL_PROFILING_EXPORT_INTERVAL`	Positive number, seconds	`60`	Profile collection and upload interval.
`OTEL_PROFILING_MEMORY_ENABLED`	Boolean	`false`	Adds heap profiles to the default wall-time profiles.
`OTEL_PROFILING_PPROF_HEADERS`	Comma-separated `name=value` or `name:value` pairs	Empty	Extra HTTP request headers.

The exporter also reads OTEL_SERVICE_NAME and the service.version, deployment.environment.name (or deployment.environment), and host.name entries in OTEL_RESOURCE_ATTRIBUTES as profile metadata.

Security¶

Security is included and opt in on Node.js 22.22.3+ or 24.11.1+. It requires the ESM --import preload instead of --require. See the Node.js Security guide.

Verify¶

Send a request through a supported framework or library, then open APM > Traces in Guance and filter by the configured service name. See Common configuration for verification steps and Troubleshooting if no data appears.