Blog Docs Log in Get started

tessl/npm-opentelemetry--instrumentation-http

OpenTelemetry instrumentation for Node.js HTTP and HTTPS modules enabling automatic telemetry collection for client and server operations

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

HTTP Instrumentation

The HttpInstrumentation class is the main entry point for automatic HTTP telemetry collection in Node.js applications. It extends InstrumentationBase and provides automatic instrumentation for both http and https modules.

Capabilities

HttpInstrumentation Class

Main instrumentation class that handles automatic HTTP telemetry collection for both client and server operations.

/**
 * HTTP and HTTPS instrumentation for OpenTelemetry
 * Automatically instruments Node.js http and https modules to collect telemetry data
 */
class HttpInstrumentation extends InstrumentationBase<HttpInstrumentationConfig> {
  /**
   * Creates a new HTTP instrumentation instance
   * @param config - Optional configuration for the instrumentation
   */
  constructor(config?: HttpInstrumentationConfig);
}

Usage Examples:

import { HttpInstrumentation } from "@opentelemetry/instrumentation-http";
import { registerInstrumentations } from "@opentelemetry/instrumentation";

// Basic instantiation with default settings
const httpInstrumentation = new HttpInstrumentation();

// Registration with OpenTelemetry
registerInstrumentations({
  instrumentations: [httpInstrumentation],
});

// With configuration options
const configuredInstrumentation = new HttpInstrumentation({
  ignoreIncomingRequestHook: (req) => {
    // Ignore health check endpoints
    return req.url?.startsWith('/health') === true;
  },
  requestHook: (span, request) => {
    // Add custom attributes for every request
    span.setAttribute('custom.request_id', 
      request.headers['x-request-id'] || 'unknown');
  },
  headersToSpanAttributes: {
    server: {
      requestHeaders: ['user-agent', 'authorization'],
      responseHeaders: ['content-type']
    }
  }
});

Inherited Methods

As an extension of InstrumentationBase, HttpInstrumentation inherits several important methods:

/**
 * Enable the instrumentation
 */
enable(): void;

/**
 * Disable the instrumentation
 */
disable(): void;

/**
 * Set the instrumentation configuration (can be called after instantiation)
 * @param config - New configuration to apply
 */
setConfig(config: HttpInstrumentationConfig): void;

/**
 * Get the current configuration
 * @returns Current instrumentation configuration
 */
getConfig(): HttpInstrumentationConfig;

Usage Examples:

const httpInstrumentation = new HttpInstrumentation({
  disableOutgoingRequestInstrumentation: true
});

// Later in the application lifecycle
httpInstrumentation.setConfig({
  disableOutgoingRequestInstrumentation: false,
  ignoreOutgoingRequestHook: (req) => {
    // Now enable outgoing requests but ignore specific URLs
    return req.hostname?.includes('internal-service') === true;
  }
});

// Temporarily disable all HTTP instrumentation
httpInstrumentation.disable();

// Re-enable when needed
httpInstrumentation.enable();

// Check current configuration
const currentConfig = httpInstrumentation.getConfig();
console.log('Current server name:', currentConfig.serverName);

Telemetry Data Collected

Spans Created

The instrumentation automatically creates spans for:

Outgoing HTTP requests (CLIENT spans): Created when your application makes HTTP requests to other services
Incoming HTTP requests (SERVER spans): Created when your application receives HTTP requests

Attributes Captured

Standard OpenTelemetry HTTP semantic convention attributes:

http.method / http.request.method - HTTP request method (GET, POST, etc.)
http.url / url.full - Full request URL
http.status_code / http.response.status_code - HTTP response status code
http.user_agent / user_agent.original - User-Agent header value
net.peer.ip / client.address - Client IP address
net.peer.port / client.port - Client port number
And many more based on semantic convention version

Metrics Recorded

The instrumentation records HTTP duration metrics:

http.client.duration - Duration of outgoing HTTP requests
http.server.duration - Duration of incoming HTTP requests
http.client.request.duration - Stable semantic convention client duration (when enabled)
http.server.request.duration - Stable semantic convention server duration (when enabled)

Semantic Convention Support

The instrumentation supports both old (v1.7.0) and new stable (v1.23.0+) HTTP semantic conventions:

// Control via environment variable
process.env.OTEL_SEMCONV_STABILITY_OPT_IN = 'http';      // Use stable only
process.env.OTEL_SEMCONV_STABILITY_OPT_IN = 'http/dup';  // Use both old and stable
// Default: uses old v1.7.0 conventions

The instrumentation automatically adapts attribute names and metric names based on the configured semantic convention stability option.

Install with Tessl CLI

npx tessl i tessl/npm-opentelemetry--instrumentation-http

docs

configuration.md

hook-functions.md

http-instrumentation.md