Follow the instructions on this page to instrument your Node.js application running on a host, such as a macOS, Windows, or Linux device. Make sure you have already installed the Observe Agent.

Add zero-code instrumentation

Perform the following steps to add zero-code instrumentation to your Node.js apps.

1. Add the OpenTelemetry zero-code instrumentation for Node.js.

   Run the following commands to add zero-code instrumentation for your Node.js application, meaning you don’t have to modify your application’s source code to collect telemetry:

   npm install @opentelemetry/sdk-node \
   @opentelemetry/api \
   @opentelemetry/auto-instrumentations-node \
   @opentelemetry/sdk-metrics \
   @opentelemetry/sdk-trace-node

2. Set the following environment variables to configure the Node.js instrumentation. Replace the placeholders such as ${YOUR_SERVICE_NAME} with the actual information from your environment.

   export OTEL_SERVICE_NAME=${YOUR_SERVICE_NAME}
   export NODE_OPTIONS="--require @opentelemetry/auto-instrumentations-node/register"
   export OTEL_RESOURCE_ATTRIBUTES=deployment.environment=${YOUR_APP_ENVIRONMENT}
   export OTEL_EXPORTER_OTLP_ENDPOINT=http://${YOUR_OBSERVE_AGENT_ENDPOINT}:4318

3. Run your instrumented app:

   node --require @opentelemetry/auto-instrumentations-node/register <YOUR_APP_ENTRYPOINT>.js
   

ESM support

If your application is written in JavaScript as ECMAScript modules (ESM), or compiled to ESM from TypeScript, then a loader hook is required to properly patch instrumentation. Below is the custom hook for ESM instrumentation:

--experimental-loader=@opentelemetry/instrumentation/hook.mjs

This flag must be passed to the node binary, which is often done as a startup command and/or in the NODE_OPTIONS environment variable. For more information, ECMAScript Modules vs. Common JS in the OpenTelemetry documentation.

Use the following commands to run your app with the experimental loader:

node --experimental-loader=@opentelemetry/instrumentation/hook.mjs --require @opentelemetry/auto-instrumentations-node/register <YOUR_APP_ENTRYPOINT>.js