JavaScript OpenTelemetry auto-instrumentation

You can instrument your JavaScript/NodeJS services by using either the official OpenTelemetry distribution (recommended) or the Sumo Logic Distribution for OpenTelemetry JS.

Option 1: Auto-instrumentation using official OpenTelemetry for JS

The OpenTelemetry-JS community supports all active versions of NodeJS. See a list of supported runtimes.

The instructions below apply to the OpenTelemetry JavaScript Instrumentation in version 1.8.0/0.41.1.

There are a few simple steps to instrument your application and obtain telemetry data.

Packages installation

required step

You must install the packages listed below to apply the instrumentation and export telemetry data.

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

Instrumentation configuration

After successful installation of the packages, it is important to properly configure instrumentation. Configuration is set through environment variables.

Disables the metrics exporter:
```
OTEL_METRICS_EXPORTER=none
```
Sets the exporter to OTLP:
```
OTEL_TRACES_EXPORTER=otlp
```
Configures the endpoint where telemetry data will be sent:
```
OTEL_EXPORTER_OTLP_ENDPOINT=http://OTLP_ENDPOINT:4318
```
This should be the OpenTelemetry Collector/Agent endpoint address or OTLP/HTTP source. For Kubernetes environments, see the available endpoints for a direct connection. For other environments, see endpoints and protocols.
Configures the service name. Ensure the string value represents its business logic, such as "FinanceServiceCall". This will appear as a tracing service name in Sumo Logic.
```
OTEL_SERVICE_NAME=SERVICE_NAME
```
Configure the application name. This will appear as a tracing application name in Sumo Logic. Additional attributes can be added here as comma-separated key=value pairs.
```
OTEL_RESOURCE_ATTRIBUTES=application=APPLICATION_NAME
```
Configure the resource detectors. Additional attributes related to environment are added to the spans.
```
OTEL_NODE_RESOURCE_DETECTORS="env,host,os"
```

Application execution

When everything is configured, it is very simple to run an instrumented application.

node --require @opentelemetry/auto-instrumentations-node/register your-js-script.js

Option 2: Auto-instrumentation using Sumo Logic OpenTelemetry for JS distro (Basic)

Sumo Logic provides its own distribution for OpenTelemetry (OT) JS tracing instrumentation. It is fully compatible with official OT package and free to use also with other vendor backends. This method is recommended as it makes installation easy, straightforward, and quick with a "just-works" scenario. It is provided as all-in-one runner for node.js projects used to enable OpenTelemetry auto-instrumentation with OTLP HTTP exporter.

Setup

Instead of running your script like node index.js, use the following command:

npx @sumologic/opentelemetry-node index.js

Your index.js file will run automatically with a started @opentelemetry/sdk-node.

Remember to provide configuration using environment variables:

OTEL_EXPORTER_OTLP_ENDPOINT. Must be provided with the location of the OpenTelemetry Collector/Agent (recommended for production) or OTLP/HTTP source. If you haven't yet installed a collector, refer to the following setup instructions:
- Set up traces collection for Kubernetes environments
- Set up traces collection for other environments usage
OTEL_SERVICE_NAME. A logical service name that represents its business logic.
OTEL_RESOURCE_ATTRIBUTES. Set "application" name attribute which should represent its business logic and extra attributes attached to all spans. Add the deployment.environment=[environment-name] tag as needed to allow for filtering by environment on dashboard panels. For more information, see Services Dashboard Panels.

Example:

OTEL_SERVICE_NAME=api
OTEL_RESOURCE_ATTRIBUTES="application=banking-app,deployment.environment=dev"
OTEL_EXPORTER_OTLP_ENDPOINT=http://examplehost:4318
npx @sumologic/opentelemetry-node index.js

To speed up the npx @sumologic/opentelemetry-node command, you can do:

npm i -g @sumologic/opentelemetry-node

Instrumented packages

The Sumo Logic OpenTelemetry for JS instrumentation enables all officially supported core and contrib auto-instrumentation plugins defined in @opentelemetry/auto-instrumentations-node, including:

Limitations

Only OTLP/HTTP proto exporter is supported
Only W3C context propagation is supported
Support for logs and metrics requires instrumentation using official OpenTelemetry for JS

Option 1: Auto-instrumentation using official OpenTelemetry for JS​

Packages installation​

Instrumentation configuration​

Application execution​

Option 2: Auto-instrumentation using Sumo Logic OpenTelemetry for JS distro (Basic)​

Setup​

Instrumented packages​

Limitations​