@xtreamsrl/node-instrumentation

This package exposes a utility function to instrument your Node.js application and a method decorator to wrap your class methods in custom spans.

Installation

npm install @xtreamsrl/node-instrumentation

Usage

The following code snippet shows a basic usage of the instrument function:

// app.ts

import { instrument } from '@xtreamsrl/node-instrumentation';
import { HttpInstrumentation } from '@opentelemetry/instrumentation-http';
import { ExpressInstrumentation } from '@opentelemetry/instrumentation-express';

instrument({
  serviceName: 'my-service',
  serviceVersion: '0.0.1',
  enableInstrumentationDebugLogging: false,
  instrumentations: [
    new ExpressInstrumentation(),
    new HttpInstrumentation(),
  ],
  exporter: process.env.ENV === 'prod'
    ? new ProdExporter()
    : new LocalExporter(),
});

// All other imports must be done after the instrument function call!
import * as AllOtherImoport from './all-other-staff';

Please note that the instrument function must be called before any other import statement in your application. The reason for this is that the opentelemetry instrumentation plugins must be imported before the underlying instrumented modules.

The configuration above will instrument your application with the ExpressInstrumentation and HttpInstrumentation plugins and will export the spans using the ProdExporter or LocalExporter depending on the ENV environment variable.

That is a basic and mockup configuration, you can find more information about the available configuration options in the following section.

Configuration

The instrument function accepts a configuration object with the following properties:

serviceName

The name of the service that is being instrumented. This will be used as the service.name attribute on all spans.

You can use the project name defined in your package.json file.

serviceVersion

The version of the service that is being instrumented. This will be used as the service.version attribute on all spans.

You can use the project version defined in your package.json file.

enableInstrumentationDebugLogging

Whether to enable debug logging for the node-instrumentation plugins. This is useful to debug issues with the node-instrumentation plugins.

node-instrumentationDebugLoggingLevel

The log level to use for the node-instrumentation plugins. Must be provided if enableInstrumentationDebugLogging is set to true.

node-instrumentations

An array of node-instrumentation plugins that will be used to instrument your application. The node-instrumentation plugins must implement the InstrumentationBase interface from the @opentelemetry/node-instrumentation package. It is required. If provided as an empty array no node-instrumentation plugin will be used and the application will not be instrumented.

exporter

The exporter that will be used to export the spans. The exporter must implement the SpanExporter interface from the @opentelemetry/sdk-trace-base package.

sampler

The sampler that will be used to sample the spans. The sampler must implement the Sampler interface from the @opentelemetry/api package. Optional, if not provided the AlwaysOnSampler will be used.

Environment Configuration

Setting the following environment variables will override the configuration options:

DISABLE_TRACING

If set to true the node-instrumentation will be disabled application wide.

Span Decorator

import { Span } from '@xtreamsrl/node-instrumentation';
import { Controller, Get } from '@nestjs/common';

@Controller('api')
export class PetController {
  @Span('Custom Span')
  @Get('custom-span')
  customSpan() {
    return this.doSomething();
  }

  @Span('Nested Span')
  private async doSomething() {
    return { message: 'Hello World!' };
  }
}

The code snippet above will create a custom span with the name Custom Span. The span will be created when the customSpan method is called and will be ended when the method returns.

The Span decorator supports nested spans, in the example above the doSomething method will be wrapped in a span with the name Nested Span that will be child of the Custom Span span.

Build

Run nx build node-instrumentation to build the package.

Run unit tests

Run nx test node-instrumentation to execute the unit tests via Jest.

Linting

Run nx lint node-instrumentation to execute the lint via ESLint.

Versioning

Export the GH_TOKEN environment variable with your GitHub token with at least the repo scope:

export GH_TOKEN=<YOUR_PERSONAL_GH_TOKEN>

Then run the following command:

lerna version

The GH_TOKEN is needed to push the version commit and tag to the remote repository and to create the release on GitHub.

For general information about the versioning process, please refer to the root Readme Versioning section.

Publishing

Update your local .npmrc file to include the following lines:

@xtreamsrl:registry=https://registry.npmjs.org/
//registry.npmjs.org/:_authToken=${NPM_TOKEN}

The ${NPM_TOKEN} placeholder is a npm personal access token publish permissions on the @xtreamsrl organization. It can be treated as placeholder to replace with the actual token value, or you can set it as an environment variable:

export NPM_TOKEN=<YOUR_PERSONAL_NPM_TOKEN>

Then run the following command:

npm run lerna-publish

Who we are

A proudly 🇮🇹 software development and data science startup.
We consider ourselves a family of talented and passionate people building their own products and powerful solutions for our clients. Get to know us more on xtreamers.io or follow us on LinkedIn.