OpenTelemetry Support

N|Solid has added support for some OpenTelemetry features:

• It provides an implementation of the OpenTelemetry TraceAPI which allows the user to instrument their own code using the de-facto standard API.
• It also supports the use lots of instrumentation modules available in the OpenTelemetry echosystem.
• It support exporting traces using the OpenTelemetry Protocol(OTLP) over HTTP.

OpenTelemetry JS Tracing API

Using the OpenTelemetry JS API @opentelemetry/api to instrument your own code is very easy. N|Solid provides a nsolid.otel.register() API which allows to use the N|Solid implementation of the OpenTelemetry TraceAPI. See a very basic example in the following code. Notice that for the traces to be generated the enviroment variable NSOLID_TRACING_ENABLED should be set.

// Run this code with `NSOLID_TRACING_ENABLED=1` so traces are generated.
const nsolid = require('nsolid');
const api = require('@opentelemetry/api');

if (!nsolid.otel.register(api)) {
  throw new Error('Error registering api');
}

const tracer = api.trace.getTracer('Test tracer');
const span = tracer.startSpan('initial', { attributes: { a: 1, b: 2 }});
span.updateName('my name');
span.setAttributes({c: 3, d: 4 });
span.setAttribute('e', 5);
span.addEvent('my_event 1', Date.now());
span.addEvent('my_event 2', { attr1: 'val1', attr2: 'val2'}, Date.now());
span.end();

Integration with OpenTelemetry-compatible instrumentation modules

N|Solid also provides a nsolid.otel.registerInstrumentations() API to register instrumentation modules that use the OpenTelemetry TraceAPI that are available in the OpenTelemetry echosystem. The following code shows an example using the @opentelemetry/instrumentation-fs module:

// Run this code with `NSOLID_TRACING_ENABLED=1` so traces are generated.
const nsolid = require('nsolid');
const api = require('@opentelemetry/api');
const os = require('os');
const path = require('path');

const { FsInstrumentation } = require('@opentelemetry/instrumentation-fs');

nsolid.start({
  tracingEnabled: true
});

if (!nsolid.otel.register(api)) {
  throw new Error('Error registering api');
}

nsolid.otel.registerInstrumentations([
  new FsInstrumentation({
  })
]);

const fs = require('fs');
fs.mkdtemp(path.join(os.tmpdir(), 'foo-'), (err, directory) => {
  if (err) throw err;
  console.log(directory);
});

Exporting Traces via OTLP over HTTP

It's possible now to export traces with N|Solid to endpoints supporting the OpenTelemetry Protocol(OTLP) over HTTP. On top of that we make very easy to send traces to specific vendors endpoints such as Datadog, DynaTrace and NewRelic. And not only that, for these vendors we're also able to export the metrics N|Solid generates, so this info can also be displayed in their solutions with no need to use their agents which have the performance issues explained in this article.

To configure the OTLP endpoint there are two configuration options we need to set either via NSOLID_OTLP and NSOLID_OTLP_CONFIG the environment variables or the other ways N|Solid provides to set them.

NSOLID_OTLP defines the type of endpoint we're exporting the traces to. Allowed values at the moment are:

• datadog
• dynatrace
• newrelic
• otlp

NSOLID_OTLP_CONFIG defines the configuration for the type of endpoint selected in NSOLID_OTLP. This configuration is a string containing a JS object serialized using JSON. The format of this JS object differs depending on the type of endpoint.

Endpoint Type	Format
datadog	{ zone: 'us' | 'eu', key: 'your_datadog_key', url: 'otlp_endpoint_url' }
dynatrace	{ site: 'you_dynatrace_size', token: 'your_dynatrace' }
newrelic	{ zone: 'us' | 'eu', key: 'your_datadog_key' }
otlp	{ url: 'otlp_endpoint_url' }

Here is an example of how to configure N|Solid to export data to Dynatrace. Notice you need N|Solid to be licensed.

$ NSOLID_OTLP=dynatrace NSOLID_OTLP_CONFIG='{"site":"my_site","token":"my_token"}' NSOLID_LICENSE_TOKEN=my_nsolid_license nsolid my_process.js