or run

npx @tessl/cli init
Log in

Version

Files

tile.json

tessl/npm-opentelemetry--instrumentation

Base class for node which OpenTelemetry instrumentation modules extend

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@opentelemetry/instrumentation@0.204.x

To install, run

npx @tessl/cli install tessl/npm-opentelemetry--instrumentation@0.204.0

index.mddocs/

OpenTelemetry Instrumentation

OpenTelemetry Instrumentation provides a foundational base class for creating instrumentation modules that automatically instrument third-party libraries and frameworks in both Node.js and browser environments. It offers a comprehensive API for hooking into module loading mechanisms, wrapping and unwrapping methods with tracing capabilities, and managing instrumentation lifecycle.

Package Information

  • Package Name: @opentelemetry/instrumentation
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @opentelemetry/instrumentation

Core Imports

import { 
  InstrumentationBase, 
  registerInstrumentations, 
  InstrumentationNodeModuleDefinition, 
  InstrumentationNodeModuleFile,
  isWrapped,
  safeExecuteInTheMiddle,
  safeExecuteInTheMiddleAsync,
  SemconvStability,
  semconvStabilityFromStr,
  type Instrumentation,
  type InstrumentationConfig,
  type InstrumentationModuleDefinition,
  type InstrumentationModuleFile,
  type ShimWrapped,
  type SpanCustomizationHook,
  type AutoLoaderOptions,
  type AutoLoaderResult
} from "@opentelemetry/instrumentation";

For CommonJS:

const { 
  InstrumentationBase, 
  registerInstrumentations, 
  InstrumentationNodeModuleDefinition, 
  InstrumentationNodeModuleFile,
  isWrapped,
  safeExecuteInTheMiddle,
  safeExecuteInTheMiddleAsync,
  SemconvStability,
  semconvStabilityFromStr
} = require("@opentelemetry/instrumentation");

Basic Usage

import { InstrumentationBase, InstrumentationNodeModuleDefinition } from "@opentelemetry/instrumentation";

class MyInstrumentation extends InstrumentationBase {
  constructor(config = {}) {
    super("my-instrumentation", "1.0.0", config);
  }

  protected init() {
    return new InstrumentationNodeModuleDefinition(
      "target-module",
      [">=1.0.0 <2.0.0"],
      (moduleExports, moduleVersion) => {
        // Patch the module
        return moduleExports;
      },
      (moduleExports, moduleVersion) => {
        // Unpatch the module
      }
    );
  }

  enable() {
    // Enable instrumentation
  }

  disable() {
    // Disable instrumentation
  }
}

// Register the instrumentation
const unregister = registerInstrumentations({
  instrumentations: [new MyInstrumentation()]
});

Architecture

OpenTelemetry Instrumentation is built around several key components:

  • InstrumentationBase: Abstract base class providing core instrumentation functionality
  • Module Definition System: Define which modules and versions to instrument with patch/unpatch functions
  • Auto-registration: Automatic loading and lifecycle management of instrumentations
  • Platform Support: Separate implementations for Node.js and browser environments
  • Provider Integration: Seamless integration with TracerProvider, MeterProvider, and LoggerProvider
  • Safe Execution: Error handling and recovery mechanisms for instrumentation operations

Capabilities

Base Instrumentation Class

Core abstract base class that instrumentation modules extend. Provides lifecycle management, provider integration, and configuration handling.

abstract class InstrumentationBase<ConfigType extends InstrumentationConfig = InstrumentationConfig> 
  implements Instrumentation<ConfigType> {
  abstract enable(): void;
  abstract disable(): void;
  setTracerProvider(tracerProvider: TracerProvider): void;
  setMeterProvider(meterProvider: MeterProvider): void;
  setLoggerProvider?(loggerProvider: LoggerProvider): void;
  setConfig(config: ConfigType): void;
  getConfig(): ConfigType;
}

Base Instrumentation

Module Definition System

System for defining which modules to instrument, their supported versions, and how to patch/unpatch them.

class InstrumentationNodeModuleDefinition implements InstrumentationModuleDefinition {
  constructor(
    name: string,
    supportedVersions: string[],
    patch?: (exports: any, moduleVersion?: string) => any,
    unpatch?: (exports: any, moduleVersion?: string) => void,
    files?: InstrumentationModuleFile[]
  );
}

class InstrumentationNodeModuleFile implements InstrumentationModuleFile {
  constructor(
    name: string,
    supportedVersions: string[],
    patch: (moduleExports: any, moduleVersion?: string) => any,
    unpatch: (moduleExports?: any, moduleVersion?: string) => void
  );
}

Module Definitions

Auto-Registration System

Registration and lifecycle management system for instrumentations with provider configuration.

function registerInstrumentations(options: AutoLoaderOptions): () => void;

interface AutoLoaderOptions {
  instrumentations?: (Instrumentation | Instrumentation[])[];
  tracerProvider?: TracerProvider;
  meterProvider?: MeterProvider;
  loggerProvider?: LoggerProvider;
}

Auto-Registration

Utility Functions

Safe execution utilities and function wrapping detection for robust instrumentation.

function isWrapped(func: unknown): func is ShimWrapped;

function safeExecuteInTheMiddle<T>(
  execute: () => T,
  onFinish: (e: Error | undefined, result: T | undefined) => void,
  preventThrowingError?: boolean
): T;

function safeExecuteInTheMiddleAsync<T>(
  execute: () => T,
  onFinish: (e: Error | undefined, result: T | undefined) => void,
  preventThrowingError?: boolean
): Promise<T>;

Utilities

Semantic Convention Support

Support for semantic convention stability migration with namespace-specific configuration.

enum SemconvStability {
  STABLE = 0x1,
  OLD = 0x2,
  DUPLICATE = 0x3
}

function semconvStabilityFromStr(
  namespace: string,
  str: string | undefined
): SemconvStability;

Semantic Conventions

Core Types

interface Instrumentation<ConfigType extends InstrumentationConfig = InstrumentationConfig> {
  instrumentationName: string;
  instrumentationVersion: string;
  disable(): void;
  enable(): void;
  setTracerProvider(tracerProvider: TracerProvider): void;
  setMeterProvider(meterProvider: MeterProvider): void;
  setLoggerProvider?(loggerProvider: LoggerProvider): void;
  setConfig(config: ConfigType): void;
  getConfig(): ConfigType;
}

interface InstrumentationConfig {
  enabled?: boolean;
}

interface InstrumentationModuleDefinition {
  name: string;
  moduleExports?: any;
  moduleVersion?: string;
  supportedVersions: string[];
  files: InstrumentationModuleFile[];
  includePrerelease?: boolean;
  patch?: (moduleExports: any, moduleVersion?: string) => any;
  unpatch?: (moduleExports: any, moduleVersion?: string) => void;
}

interface InstrumentationModuleFile {
  name: string;
  moduleExports?: unknown;
  supportedVersions: string[];
  patch(moduleExports: unknown, moduleVersion?: string): unknown;
  unpatch(moduleExports?: unknown, moduleVersion?: string): void;
}

interface ShimWrapped extends Function {
  __wrapped: boolean;
  __unwrap: Function;
  __original: Function;
}

type SpanCustomizationHook<SpanCustomizationInfoType> = (
  span: Span,
  info: SpanCustomizationInfoType
) => void;