Skip to main content
Sumo Logic

JavaScript OpenTelemetry auto-instrumentation

You can instrument your JavaScript/NodeJS services either using Sumo Logic distribution for OpenTelemetry JS that is all-in-one, easy and quick to setup or a bit more demanding official OpenTelemetry distribution

Auto-instrumentation using Sumo Logic OpenTelemetry for JS distro (easy setup)

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.

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_TRACES_ENDPOINT - source URL of your traces collector
  • 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

Example:

OTEL_SERVICE_NAME=api

OTEL_RESOURCE_ATTRIBUTES="application=banking-app,deployment=test"

OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://... npx @sumologic/opentelemetry-node index.js

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

npm i -g @sumologic/opentelemetry-node

Limitations
  • Only OTLP/HTTP proto exporter is supported
  • Only W3C context propagation is supported
  • No support for metrics and logs

Auto-instrumentation using official OpenTelemetry for JS 

The OpenTelemetry-JS community supports all active versions of NodeJS. See a list of supported runtimes. Instruction below applies to OpenTelemetry JavaScript Instrumentation in version 1.0.3/0.27.0.

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

1. Packages installation

The installation of the packages listed below is required to apply the instrumentation and export telemetry data.

$ npm install --save @opentelemetry/sdk-trace-node@1.0.1
$ npm install --save @opentelemetry/sdk-trace-base@1.0.1
$ npm install --save @opentelemetry/resources@1.0.1
$ npm install --save @opentelemetry/api@1.0.3

The packages above are mandatory. The next step is to install OpenTelemetry plugins and chosen exporters. They will automatically instrument used node modules. The list of available plugins can be found here. If the application is an HTTP Client/Server then their corresponding plugins must be installed like in the example below:

$ npm install --save @opentelemetry/instrumentation-http@0.27.0

2. Instrumentation with OpenTelemetry HTTP exporter

Install OpenTelemetry HTTP exporter package:

$ npm install --save @opentelemetry/exporter-trace-otlp-proto@0.27.0

To enable instrumentation in your application, add the code below to your project. The best way is to save it and name it tracer.js - this file will contain everything that is needed to configure tracing. The first step is to provide YOUR_SERVICE_NAME which should define a logical service name as a string value that represents its business logic. This will appear as a tracing service name in the Sumo Logic web interface. Similar to service name YOUR_APPLICATION_NAME should represent its business logic. The next step is to create new NodeTracerProvider() to automatically instrument NodeJS applications. It is important to initialize NodeTracerProvider before any other module of the application.

Next, configure the OpenTelemetry Exporter, exporterOptions. This is where url is configured. The url sets the collection receiver endpoint from a Sumo Logic Source. The example below points to the default Sumologic Kubernetes Collector.

After the exporter configuration, the instrumentation has to be registered. In our example, HttpInstrumentation() is registered. This will enable auto-instrumentation for the HTTP package. If there are other libraries to instrument it is enough to add them to the instrumentations list. All available instrumentation packages can be found in the repositories OpenTelemetry JS and OpenTelemetry JS Contrib.

'use strict';

const opentelemetry = require('@opentelemetry/api');
const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
const { BatchSpanProcessor } = require("@opentelemetry/sdk-trace-base");
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-proto');
const { registerInstrumentations } = require('@opentelemetry/instrumentation');
const { HttpInstrumentation } = require('@opentelemetry/instrumentation-http');
const { Resource } = require('@opentelemetry/resources');


module.exports = () => {
 const resources = new Resource({
    'service.name': 'YOUR_SERVICE_NAME',
    'application': 'YOUR_APPLICATION_NAME',
    //'ANY_OTHER_ATTRIBUTE_KEY': 'ANY_OTHER_ATTRIBUTE_VALUE',
 }); 

 const provider = new NodeTracerProvider({ resource: resources });
 
 const exporterOptions = {
  url: 'http://collection-sumologic-otelcol.sumologic:55681/v1/traces',
 }


 
 const exporter = new OTLPTraceExporter(exporterOptions);
 provider.addSpanProcessor(new BatchSpanProcessor(exporter));
 provider.register();

 registerInstrumentations({
  instrumentations: [
    new HttpInstrumentation(),
  ],
 })
 return opentelemetry.trace.getTracer("instrumentation-example");
}

The last step is to execute tracer in your application code. Add the following line in the code below in your application on the top of the code.

const tracer = require('./tracer')()