@opentelemetry/instrumentation

What is @opentelemetry/instrumentation?

The @opentelemetry/instrumentation package is part of the OpenTelemetry project, which aims to provide a unified and standardized observability framework for monitoring applications' performance and behavior. This particular package offers a way to automatically instrument code to collect telemetry data such as traces and metrics, making it easier to monitor and debug applications.

What are @opentelemetry/instrumentation's main functionalities?

Automatic Instrumentation

Automatically instruments Node.js applications to collect telemetry data, such as tracing information for HTTP requests. This example shows how to set up the NodeTracerProvider and register the HttpInstrumentation to start collecting data.

const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
const { registerInstrumentations } = require('@opentelemetry/instrumentation');
const { HttpInstrumentation } = require('@opentelemetry/instrumentation-http');

const provider = new NodeTracerProvider();

registerInstrumentations({
  instrumentations: [
    new HttpInstrumentation()
  ],
  tracerProvider: provider,
});

Custom Instrumentation

Enables the creation of custom instrumentation for any library or application code not covered by the existing instrumentations. This example demonstrates how to extend the InstrumentationBase class to create a custom instrumentation.

const { InstrumentationBase } = require('@opentelemetry/instrumentation');

class MyCustomInstrumentation extends InstrumentationBase {
  constructor() {
    super('MyCustomInstrumentation');
  }

  init() {
    // Custom initialization logic
  }
}

Other packages similar to @opentelemetry/instrumentation

jaeger-client

Jaeger client is a package for distributed tracing in microservices architecture. It can be used to monitor and troubleshoot transactions in complex distributed systems. Compared to @opentelemetry/instrumentation, jaeger-client is more specific to the Jaeger backend, whereas OpenTelemetry provides a more vendor-neutral approach, allowing data to be exported to various backends including Jaeger.

README

OpenTelemetry Instrumentation for web and node

Installation

npm install --save @opentelemetry/instrumentation

Usage in Node

import {
  InstrumentationBase,
  InstrumentationConfig,
  InstrumentationNodeModuleDefinition,
  InstrumentationNodeModuleFile,
} from '@opentelemetry/instrumentation';

import type * as module_name_to_be_patched from 'module_name_to_be_patched';

export class MyPlugin extends InstrumentationBase {
  constructor(config: InstrumentationConfig = {}) {
    super('MyPlugin', VERSION, config);
  }

  /**
   * Init method will be called when the plugin is constructed.
   * It returns an `InstrumentationNodeModuleDefinition` which describes
   *   the node module to be instrumented and patched.
   * It may also return a list of `InstrumentationNodeModuleDefinition`s if
   *   the plugin should patch multiple modules or versions.
   */
  protected init() {
    const module = new InstrumentationNodeModuleDefinition<typeof module_name_to_be_patched>(
      'module_name_to_be_patched',
      ['1.*'],
       this._onPatchMain,
       this._onUnPatchMain,
    );
    // in case you need to patch additional files - this is optional
    module.files.push(this._addPatchingMethod());

    return module;
    // you can also define more modules then just return an array of modules
    // return [module1, module2, ....]
  }

  private _onPatchMain(moduleExports: typeof module_name_to_be_patched) {
    this._wrap(
      moduleExports,
      'mainMethodName',
      this._patchMainMethodName()
    );
    return moduleExports;
  }

  private _onUnPatchMain(moduleExports: typeof module_name_to_be_patched) {
    this._unwrap(moduleExports, 'mainMethodName');
  }

  private _addPatchingMethod(): InstrumentationNodeModuleFile<typeof module_name_to_be_patched> {
    const file = new InstrumentationNodeModuleFile<typeof module_name_to_be_patched>(
      'module_name_to_be_patched/src/some_file.js',
      this._onPatchMethodName,
      this._onUnPatchMethodName,
    );
    return file;
  }

  private _onPatchMethodName(moduleExports: typeof module_name_to_be_patched) {
    this._wrap(
      moduleExports,
      'methodName',
      this._patchMethodName()
    );
    return moduleExports;
  }

  private _onUnPatchMethodName(moduleExports: typeof module_name_to_be_patched) {
    this._unwrap(moduleExports, 'methodName');
  }

  private _patchMethodName(): (original) => any {
    const plugin = this;
    return function methodName(original) {
      return function patchMethodName(this: any): PromiseOrValue<module_name_to_be_patched.methodName> {
        console.log('methodName', arguments);
        return original.apply(this, arguments);
      };
    };
  }

  private _patchMainMethodName(): (original) => any {
    const plugin = this;
    return function mainMethodName(original) {
      return function patchMainMethodName(this: any): PromiseOrValue<module_name_to_be_patched.mainMethodName> {
        console.log('mainMethodName', arguments);
        return original.apply(this, arguments);
      };
    };
  }
}

// Later

const myPLugin = new MyPlugin();
myPLugin.setTracerProvider(provider); // this is optional
myPLugin.setMeterProvider(meterProvider); // this is optional
myPLugin.enable();
// or use Auto Loader

Usage in Web

import {
  InstrumentationBase,
  InstrumentationConfig,
} from '@opentelemetry/instrumentation';

import { Instrumentation } from '@opentelemetry/instrumentation';

export class MyPlugin extends InstrumentationBase {
  constructor(config: InstrumentationConfig = {}) {
    super('MyPlugin', VERSION, config);
  }

  private _patchOpen() {
    return (original: OpenFunction): OpenFunction => {
      const plugin = this;
      return function patchOpen(this: XMLHttpRequest, ...args): void {
        console.log('open', arguments);
        return original.apply(this, args);
      };
    };
  }

  public enable() {
    this._wrap(XMLHttpRequest.prototype, 'open', this._patchOpen());
  }
  public disable() {
    this._unwrap(XMLHttpRequest.prototype, 'open');
  }
}

// Later

const myPLugin = new MyPlugin();
myPLugin.setTracerProvider(provider);
myPLugin.setMeterProvider(meterProvider);
myPLugin.enable();
// or use Auto Loader

AutoLoader

Successor of loading plugins through TracerProvider "plugins" option. It also supersedes PluginLoader for node. The old configurations usually looks like

NODE - old way using TracerProvider

const { NodeTracerProvider } = require('@opentelemetry/node');
const { B3Propagator } = require('@opentelemetry/propagator-b3');
const provider = new NodeTracerProvider({
  plugins: {
    http: { enabled: false },
  },
});
provider.register({
  propagator: new B3Propagator(),
});

WEB - old way using TracerProvider

const { WebTracerProvider } = require('@opentelemetry/web');
const { UserInteractionPlugin } = require('@opentelemetry/plugin-user-interaction');
const { XMLHttpRequestInstrumentation } = require('@opentelemetry/instrumentation-xml-http-request');
const { B3Propagator } = require('@opentelemetry/propagator-b3');
const provider = new WebTracerProvider({
  plugins: [
    new UserInteractionPlugin(),
    new XMLHttpRequestInstrumentation({
      ignoreUrls: [/localhost/],
      propagateTraceHeaderCorsUrls: [
        'http://localhost:8090',
      ],
    }),
  ],
});
provider.register({
  propagator: new B3Propagator(),
});

After change it will look like this - mixing plugins and instrumentations together All plugins will be bound to TracerProvider as well as instrumentations

NODE - Auto Loader

const { B3Propagator } = require('@opentelemetry/propagator-b3');
const { registerInstrumentations } = require('@opentelemetry/instrumentation');
const { GraphQLInstrumentation } = require('@opentelemetry/instrumentation-graphql');
const { NodeTracerProvider } = require('@opentelemetry/node');
const tracerProvider = new NodeTracerProvider();

registerInstrumentations({
  instrumentations: [
    new UserInteractionPlugin(),
    new XMLHttpRequestInstrumentation({
      ignoreUrls: [/localhost/],
      propagateTraceHeaderCorsUrls: [
        'http://localhost:8090',
      ],
    }),
  ],
  meterProvider: meterProvider,
  tracerProvider: tracerProvider,
  logger: new ConsoleLogger(), // optional
});

tracerProvider.register({
  propagator: new B3Propagator(),
});

WEB - Auto Loader

const { B3Propagator } = require('@opentelemetry/propagator-b3');
const { registerInstrumentations } = require('@opentelemetry/instrumentation');
import { XMLHttpRequestInstrumentation } from '@opentelemetry/instrumentation-xml-http-request';
const { UserInteractionPlugin } = require('@opentelemetry/plugin-user-interaction');
const { WebTracerProvider } = require('@opentelemetry/web');
const tracerProvider = new WebTracerProvider();

registerInstrumentations({
  instrumentations: [
    new GraphQLInstrumentation(),
    {
      plugins: {
        http: { enabled: false },
      },
    }
  ],
  meterProvider: meterProvider,
  tracerProvider: tracerProvider,
  logger: new ConsoleLogger(), // optional
});

tracerProvider.register({
  propagator: new B3Propagator(),
});

License

Apache 2.0 - See LICENSE for more information.

Useful links

• For more information on OpenTelemetry, visit: https://opentelemetry.io/
• For help or feedback on this project, join us in GitHub Discussions

Changelog

0.16.0

:boom: Breaking Change

• opentelemetry-exporter-collector
  • #1863 fix(exporter-collector): all http export requests should share same a… (@blumamir)
• opentelemetry-api, opentelemetry-exporter-collector, opentelemetry-exporter-jaeger
  • #1860 chore: fixing status code aligning it with proto (@obecny)

:rocket: (Enhancement)

• opentelemetry-core
  • #1837 chore(http-propagation): reduce complexity of traceparent parsing (@marcbachmann)
• opentelemetry-api, opentelemetry-exporter-collector, opentelemetry-exporter-jaeger
  • #1860 chore: fixing status code aligning it with proto (@obecny)

:bug: (Bug Fix)

• opentelemetry-exporter-collector
  • #1863 fix(exporter-collector): all http export requests should share same a… (@blumamir)

:books: (Refine Doc)

• opentelemetry-api
  • #1864 chore: export API singleton types (@dyladan)
• opentelemetry-api-metrics, opentelemetry-api, opentelemetry-context-async-hooks, opentelemetry-context-base, opentelemetry-context-zone-peer-dep, opentelemetry-context-zone, opentelemetry-core, opentelemetry-exporter-collector-grpc, opentelemetry-exporter-collector-proto, opentelemetry-exporter-collector, opentelemetry-exporter-jaeger, opentelemetry-exporter-prometheus, opentelemetry-exporter-zipkin, opentelemetry-grpc-utils, opentelemetry-instrumentation-fetch, opentelemetry-instrumentation-grpc, opentelemetry-instrumentation-http, opentelemetry-instrumentation-xml-http-request, opentelemetry-instrumentation, opentelemetry-metrics, opentelemetry-node, opentelemetry-plugin-grpc-js, opentelemetry-plugin-grpc, opentelemetry-plugin-http, opentelemetry-plugin-https, opentelemetry-propagator-b3, opentelemetry-resource-detector-aws, opentelemetry-resource-detector-gcp, opentelemetry-resources, opentelemetry-sdk-node, opentelemetry-semantic-conventions, opentelemetry-shim-opentracing, opentelemetry-tracing, opentelemetry-web
  • #1866 chore: remove all gitter links and replace with dicussions (@dyladan)
• opentelemetry-exporter-jaeger
  • #1869 Add info that the project only works with Node.js (@JapuDCret)
• opentelemetry-api-metrics, opentelemetry-api, opentelemetry-context-async-hooks, opentelemetry-context-base, opentelemetry-context-zone-peer-dep, opentelemetry-context-zone, opentelemetry-core, opentelemetry-exporter-collector-grpc, opentelemetry-exporter-collector-proto, opentelemetry-exporter-collector, opentelemetry-exporter-jaeger, opentelemetry-exporter-prometheus, opentelemetry-exporter-zipkin, opentelemetry-grpc-utils, opentelemetry-instrumentation-fetch, opentelemetry-instrumentation-grpc, opentelemetry-instrumentation-http, opentelemetry-instrumentation-xml-http-request, opentelemetry-instrumentation, opentelemetry-metrics, opentelemetry-node, opentelemetry-plugin-grpc-js, opentelemetry-plugin-grpc, opentelemetry-plugin-http, opentelemetry-plugin-https, opentelemetry-resource-detector-aws, opentelemetry-resource-detector-gcp, opentelemetry-resources, opentelemetry-sdk-node, opentelemetry-semantic-conventions, opentelemetry-shim-opentracing, opentelemetry-tracing, opentelemetry-web
  • #1865 Fix all links to point to main (@dyladan)
• Other
  • #1858 docs: update contribution documentation (@drexler)

Committers: 6

• Amir Blum (@blumamir)
• Bartlomiej Obecny (@obecny)
• Daniel Dyla (@dyladan)
• Marc Bachmann (@marcbachmann)
• @JapuDCret
• andrew quartey (@drexler)