tessl/npm-opentelemetry--instrumentation

Base class for node which OpenTelemetry instrumentation modules extend

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Base Instrumentation

Name: tessl/npm-opentelemetry--instrumentation
Author: tessl

The base instrumentation system provides the foundation for creating OpenTelemetry instrumentation modules that can automatically instrument third-party libraries and frameworks.

Capabilities

InstrumentationBase Class

Abstract base class that all instrumentation modules should extend. Provides lifecycle management, provider integration, and configuration handling.

/**
 * Base abstract class for instrumenting node and web plugins
 */
abstract class InstrumentationBase<ConfigType extends InstrumentationConfig = InstrumentationConfig> 
  extends InstrumentationAbstract<ConfigType> 
  implements Instrumentation<ConfigType> {
  
  constructor(
    instrumentationName: string,
    instrumentationVersion: string,
    config: ConfigType
  );

  /** Enable the instrumentation (implemented for Node.js) */
  enable(): void;

  /** Disable the instrumentation (implemented for Node.js) */
  disable(): void;

  /** Initialize and return module definitions */
  protected abstract init(): 
    | InstrumentationModuleDefinition 
    | InstrumentationModuleDefinition[] 
    | void;

  /** Set tracer provider */
  setTracerProvider(tracerProvider: TracerProvider): void;

  /** Set meter provider */
  setMeterProvider(meterProvider: MeterProvider): void;

  /** Set logger provider */
  setLoggerProvider?(loggerProvider: LoggerProvider): void;

  /** Set instrumentation configuration */
  setConfig(config: ConfigType): void;

  /** Get current configuration */
  getConfig(): ConfigType;

  /** Get module definitions (experimental) */
  getModuleDefinitions(): InstrumentationModuleDefinition[];
}

Usage Example:

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

class HttpInstrumentation extends InstrumentationBase {
  constructor(config = {}) {
    super("@opentelemetry/instrumentation-http", "1.0.0", config);
  }

  protected init() {
    return new InstrumentationNodeModuleDefinition(
      "http",
      ["*"],
      (moduleExports, moduleVersion) => {
        // Patch http module
        this._wrap(moduleExports, 'request', this._patchRequest.bind(this));
        return moduleExports;
      },
      (moduleExports, moduleVersion) => {
        // Unpatch http module  
        this._unwrap(moduleExports, 'request');
      }
    );
  }

  // enable() and disable() are implemented by the base class
  // No need to override unless custom behavior is required

  private _patchRequest(original: Function) {
    return function(this: any, ...args: any[]) {
      // Add tracing logic here
      return original.apply(this, args);
    };
  }
}

InstrumentationAbstract (Base Class)

Core abstract class providing common instrumentation functionality.

/**
 * Base abstract internal class for instrumenting node and web plugins
 */
abstract class InstrumentationAbstract<ConfigType extends InstrumentationConfig = InstrumentationConfig> 
  implements Instrumentation<ConfigType> {
  
  readonly instrumentationName: string;
  readonly instrumentationVersion: string;

  constructor(
    instrumentationName: string,
    instrumentationVersion: string,
    config: ConfigType
  );

  /** Tracer instance */
  protected get tracer(): Tracer;

  /** Meter instance */
  protected get meter(): Meter;

  /** Logger instance */
  protected get logger(): Logger;

  /** Shimmer wrap function */
  protected _wrap: typeof wrap;

  /** Shimmer unwrap function */
  protected _unwrap: typeof unwrap;

  /** Shimmer mass wrap function */
  protected _massWrap: typeof massWrap;

  /** Shimmer mass unwrap function */
  protected _massUnwrap: typeof massUnwrap;

  /** Execute span customization hook safely */
  protected _runSpanCustomizationHook<SpanCustomizationInfoType>(
    hookHandler: SpanCustomizationHook<SpanCustomizationInfoType> | undefined,
    triggerName: string,
    span: Span,
    info: SpanCustomizationInfoType
  ): void;

  /** Update metric instruments (override in subclasses) */
  protected _updateMetricInstruments(): void;
}

Configuration Management

Base configuration interface and management for all instrumentations.

/**
 * Base interface for configuration options common to all instrumentations
 */
interface InstrumentationConfig {
  /** Whether to enable the plugin (default: true) */
  enabled?: boolean;
}

Usage Example:

interface HttpInstrumentationConfig extends InstrumentationConfig {
  requestHook?: (span: Span, request: IncomingMessage) => void;
  responseHook?: (span: Span, response: ServerResponse) => void;
  ignoreIncomingRequestUrls?: (string | RegExp)[];
}

class HttpInstrumentation extends InstrumentationBase<HttpInstrumentationConfig> {
  constructor(config: HttpInstrumentationConfig = {}) {
    super("@opentelemetry/instrumentation-http", "1.0.0", config);
  }

  // Use this.getConfig() to access configuration
  private _shouldIgnoreUrl(url: string): boolean {
    const config = this.getConfig();
    return config.ignoreIncomingRequestUrls?.some(pattern => 
      typeof pattern === 'string' ? url.includes(pattern) : pattern.test(url)
    ) ?? false;
  }
}

Provider Integration

Integration with OpenTelemetry providers for distributed tracing, metrics, and logging.

/**
 * Set tracer provider for this instrumentation
 */
setTracerProvider(tracerProvider: TracerProvider): void;

/**
 * Set meter provider for this instrumentation
 */
setMeterProvider(meterProvider: MeterProvider): void;

/**
 * Set logger provider for this instrumentation
 */
setLoggerProvider?(loggerProvider: LoggerProvider): void;

Usage Example:

import { trace, metrics } from "@opentelemetry/api";
import { logs } from "@opentelemetry/api-logs";

const instrumentation = new HttpInstrumentation();

// Providers are usually set via registerInstrumentations
// but can be set directly if needed
instrumentation.setTracerProvider(trace.getTracerProvider());
instrumentation.setMeterProvider(metrics.getMeterProvider());
instrumentation.setLoggerProvider(logs.getLoggerProvider());

Span Customization Hooks

System for allowing users to customize spans during instrumentation lifecycle events.

/**
 * SpanCustomizationHook allows users to add custom behavior to spans
 */
type SpanCustomizationHook<SpanCustomizationInfoType> = (
  span: Span,
  info: SpanCustomizationInfoType
) => void;

/**
 * Execute span customization hook safely with error handling
 */
protected _runSpanCustomizationHook<SpanCustomizationInfoType>(
  hookHandler: SpanCustomizationHook<SpanCustomizationInfoType> | undefined,
  triggerName: string,
  span: Span,
  info: SpanCustomizationInfoType
): void;

Usage Example:

interface HttpInstrumentationConfig extends InstrumentationConfig {
  requestHook?: SpanCustomizationHook<{ request: IncomingMessage }>;
}

class HttpInstrumentation extends InstrumentationBase<HttpInstrumentationConfig> {
  private _onRequest(span: Span, request: IncomingMessage) {
    // Execute user-provided hook safely
    this._runSpanCustomizationHook(
      this.getConfig().requestHook,
      'request',
      span,
      { request }
    );
  }
}

Install with Tessl CLI

npx tessl i tessl/npm-opentelemetry--instrumentation

docs

auto-registration.md

base-instrumentation.md

index.md

module-definitions.md

semconv-stability.md

utilities.md

tile.json

tessl/npm-opentelemetry--instrumentation