Instrumenting Node.js Applications

Automatic instrumentation

Automatic instrumentation for Node.js is done by including the automatic instrumentation Javascript libraries with your application. A wide range of libraries and frameworks is supported.

Automatic instrumentation does not require any modifications of the application. To set it up follow these steps:

  1. Add the Open Telemetry instrumentation SDK to your application:

    npm install --save @opentelemetry/api
npm install --save @opentelemetry/auto-instrumentations-node

  2. Update the command that starts your application to load the SDK, either by updating the docker image entry point or command or by updating the command in the Kubernetes manifest for your application. Add --require @opentelemetry/auto-instrumentations-node/register:

    node --require @opentelemetry/auto-instrumentations-node/register app.js

  3. Deploy your application with the extra environment variables to configure the service name and exporter endpoint, supported protocols are gRPC and protobuf over HTTP.

  4. Verify SUSE Observability is receiving traces and/or metrics by searching for the metrics / traces in the metrics / trace explorer for your service name

For more details please refer to the Open Telemetry documentation.

The auto instrumentation configured via environment variables only supports traces until this Open Telemetry issue is resolved. To enable metrics from the automatic instrumentation code changes are needed. Please follow the instructions in the Open Telemetry documentation to make these changes.

Manual instrumentation

Manual instrumentation can be used when you need metrics, traces or logs from parts of the code that are not supported by the auto instrumentation. For example, unsupported libraries, in-house code or business-level metrics.

To capture that data you need to modify your application.

  1. Include the Open Telemetry SDK as a dependency

  2. Add code to your application to capture metrics, spans or logs where needed

There is detailed documentation for this on the Open Telemetry Javascript SDK doc pages.

Configure the OTLP exporter to send telemetry to the Agent’s telemetry gateway. See Configure your SDKs for the endpoint and protocol settings.