Using instrumentation libraries

You can use instrumentation libraries in order to generate telemetry data for a library or framework.

For example, the instrumentation library for Express will automatically create spans based on the inbound HTTP requests.

Setup

Each instrumentation library is an NPM package, and installation is typically done like so:

npm install <name-of-package>

It is typically then registered at application startup time, such as when creating a TracerProvider.

Node.js

Node autoinstrumentation package

OpenTelemetry also defines the auto-instrumentations-node metapackage that bundles all Node.js-based instrumentation libraries into a single package. It’s a convenient way to add automatically-generated telemetry for all your libraries with minimal effort.

To use the package, first install it:

npm install @opentelemetry/auto-instrumentations-node

Then in your tracing initialization code, use registerInstrumentations:

/* tracing.js */

// Require dependencies
const { getNodeAutoInstrumentations } = require("@opentelemetry/auto-instrumentations-node");
const opentelemetry = require("@opentelemetry/api");
const { Resource } = require("@opentelemetry/resources");
const { SemanticResourceAttributes } = require("@opentelemetry/semantic-conventions");
const { NodeTracerProvider } = require("@opentelemetry/sdk-trace-node");
const { registerInstrumentations } = require("@opentelemetry/instrumentation");
const { ConsoleSpanExporter, BatchSpanProcessor } = require("@opentelemetry/sdk-trace-base");

// This registers all instrumentation packages
registerInstrumentations({
  instrumentations: [
    getNodeAutoInstrumentations()
  ],
});

const resource =
  Resource.default().merge(
    new Resource({
      [SemanticResourceAttributes.SERVICE_NAME]: "service-name-here",
      [SemanticResourceAttributes.SERVICE_VERSION]: "0.1.0",
    })
  );

const provider = new NodeTracerProvider({
    resource: resource,
});
const exporter = new ConsoleSpanExporter();
const processor = new BatchSpanProcessor(exporter);
provider.addSpanProcessor(processor);

provider.register();

Using individual instrumentation packages

If you don’t wish to use a metapackage, perhaps to decrease your dependency graph size, you can install and register individual instrumentation packages.

For example, here’s how you can install and register only the instrumentation-express and instrumentation-http packages to instrument inbound and outbound HTTP traffic.

npm install --save @opentelemetry/instrumentation-http @opentelemetry/instrumentation-express

And then register each instrumentation library:

/* tracing.js */

// Require dependencies
const { HttpInstrumentation } = require("@opentelemetry/instrumentation-http");
const { ExpressInstrumentation } = require("@opentelemetry/instrumentation-express");
const opentelemetry = require("@opentelemetry/api");
const { Resource } = require("@opentelemetry/resources");
const { SemanticResourceAttributes } = require("@opentelemetry/semantic-conventions");
const { NodeTracerProvider } = require("@opentelemetry/sdk-trace-node");
const { registerInstrumentations } = require("@opentelemetry/instrumentation");
const { ConsoleSpanExporter, BatchSpanProcessor } = require("@opentelemetry/sdk-trace-base");

// This registers all instrumentation packages
registerInstrumentations({
  instrumentations: [
    // Express instrumentation expects HTTP layer to be instrumented
    new HttpInstrumentation(),
    new ExpressInstrumentation(),
  ],
});

const resource =
  Resource.default().merge(
    new Resource({
      [SemanticResourceAttributes.SERVICE_NAME]: "service-name-here",
      [SemanticResourceAttributes.SERVICE_VERSION]: "0.1.0",
    })
  );

const provider = new NodeTracerProvider({
    resource: resource,
});
const exporter = new ConsoleSpanExporter();
const processor = new BatchSpanProcessor(exporter);
provider.addSpanProcessor(processor);

provider.register();

Configuring instrumentation libraries

Some instrumentation libraries offer additional configuration options.

For example, Express instrumentation offers ways to ignore specified middleware or enrich spans created automatically with a request hook.

You’ll need to refer to each instrumentation library’s documentation for advanced configuration.

Available instrumentation libraries

A full list of instrumentation libraries produced by OpenTelemetry is available from the opentelemetry-js-contrib repository.

You can also find more instrumentations available in the registry.

Next steps

After you have set up instrumentation libraries, you may want to add manual instrumentation to collect custom telemetry data.

You’ll also want to configure an appropriate exporter to export your telemetry data to one or more telemetry backends.