or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-opentelemetry--instrumentation-express

OpenTelemetry instrumentation for Express.js web applications enabling automatic distributed tracing and observability

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

To install, run

npx @tessl/cli install tessl/npm-opentelemetry--instrumentation-express@0.52.0

index.mddocs/

OpenTelemetry Express Instrumentation

OpenTelemetry Express Instrumentation provides automatic tracing and observability for Express.js web applications. It automatically captures HTTP request spans, route information, middleware execution, and request handler performance metrics without requiring code changes to existing applications.

Package Information

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

Core Imports

import { ExpressInstrumentation } from "@opentelemetry/instrumentation-express";

For additional types and enums:

import {
  ExpressInstrumentation,
  ExpressLayerType,
  AttributeNames,
  type ExpressInstrumentationConfig,
  type ExpressRequestInfo,
  type ExpressRequestCustomAttributeFunction,
  type IgnoreMatcher,
  type LayerPathSegment,
  type SpanNameHook,
} from "@opentelemetry/instrumentation-express";

For CommonJS:

const { ExpressInstrumentation } = require("@opentelemetry/instrumentation-express");

Basic Usage

import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
import { registerInstrumentations } from "@opentelemetry/instrumentation";
import { HttpInstrumentation } from "@opentelemetry/instrumentation-http";
import { ExpressInstrumentation } from "@opentelemetry/instrumentation-express";

const provider = new NodeTracerProvider();
provider.register();

registerInstrumentations({
  instrumentations: [
    // Express instrumentation requires HTTP layer to be instrumented
    new HttpInstrumentation(),
    new ExpressInstrumentation(),
  ],
});

Architecture

The Express instrumentation works by patching Express Router methods (route, use) and Application methods (use) to automatically create spans for middleware, routers, and request handlers. It uses a layered approach where:

  • Router Spans: Created for Express Router instances
  • Middleware Spans: Created for middleware functions
  • Request Handler Spans: Created for route handlers and final request processors
  • Layer Path Tracking: Maintains a stack of route paths to construct accurate route information
  • Context Propagation: Ensures proper OpenTelemetry context flow through the Express middleware chain

Capabilities

Express Instrumentation Class

Main instrumentation class that extends OpenTelemetry's InstrumentationBase to provide automatic Express.js tracing.

/**
 * Express instrumentation for OpenTelemetry
 * Automatically instruments Express.js applications for distributed tracing
 */
class ExpressInstrumentation extends InstrumentationBase<ExpressInstrumentationConfig> {
  /**
   * Creates a new Express instrumentation instance
   * @param config - Optional configuration for the instrumentation
   */
  constructor(config?: ExpressInstrumentationConfig);

  /**
   * Initializes the instrumentation by returning module definitions
   * @returns Array of InstrumentationNodeModuleDefinition for express module
   */
  init(): InstrumentationNodeModuleDefinition[];
}

Layer Type Classification

Enumeration defining the types of Express layers that can be instrumented.

/**
 * Types of Express layers that can be instrumented
 */
enum ExpressLayerType {
  ROUTER = 'router',
  MIDDLEWARE = 'middleware',
  REQUEST_HANDLER = 'request_handler',
}

Attribute Names

Standard attribute names used by the Express instrumentation for OpenTelemetry spans.

/**
 * OpenTelemetry attribute names used by Express instrumentation
 */
enum AttributeNames {
  EXPRESS_TYPE = 'express.type',
  EXPRESS_NAME = 'express.name',
}

Configuration Interface

Configuration options for customizing Express instrumentation behavior.

/**
 * Configuration options for Express Instrumentation
 */
interface ExpressInstrumentationConfig extends InstrumentationConfig {
  /** Ignore specific layers based on their name using matchers */
  ignoreLayers?: IgnoreMatcher[];
  /** Ignore specific layers based on their type */
  ignoreLayersType?: ExpressLayerType[];
  /** Custom function for span naming */
  spanNameHook?: SpanNameHook;
  /** Function for adding custom attributes on Express request */
  requestHook?: ExpressRequestCustomAttributeFunction;
}

Request Information Interface

Information about Express requests passed to hooks and callbacks.

/**
 * Information about Express request for hooks and callbacks
 */
interface ExpressRequestInfo<T = any> {
  /** An express request object */
  request: T;
  /** The matched route path */
  route: string;
  /** Type of the Express layer handling the request */
  layerType: ExpressLayerType;
}

Custom Attribute Function

Function type for adding custom attributes to spans based on Express request information.

/**
 * Function that can be used to add custom attributes to the current span
 * @param span - The Express middleware layer span
 * @param info - Express request information including route and layer type
 */
interface ExpressRequestCustomAttributeFunction {
  (span: Span, info: ExpressRequestInfo): void;
}

Span Name Hook

Function type for customizing span names based on Express request information.

/**
 * Function for customizing span names
 * @param info - Express request information
 * @param defaultName - Default name supplied by the instrumentation
 * @returns Custom span name
 */
type SpanNameHook = (
  info: ExpressRequestInfo,
  defaultName: string
) => string;

Ignore Matcher

Type for matching patterns to ignore specific layers during instrumentation.

/**
 * Pattern matching for ignoring layers during instrumentation
 */
type IgnoreMatcher = string | RegExp | ((name: string) => boolean);

Layer Path Segment

Type representing individual segments of Express layer paths.

/**
 * Individual segment of Express layer path
 */
type LayerPathSegment = string | RegExp | number;

Usage Examples

Basic Instrumentation Setup

import { ExpressInstrumentation } from "@opentelemetry/instrumentation-express";
import { registerInstrumentations } from "@opentelemetry/instrumentation";

registerInstrumentations({
  instrumentations: [
    new ExpressInstrumentation(),
  ],
});

Configuration with Layer Filtering

import { ExpressInstrumentation, ExpressLayerType } from "@opentelemetry/instrumentation-express";

const expressInstrumentation = new ExpressInstrumentation({
  ignoreLayers: [
    // Ignore health check endpoints
    '/health',
    /^\/static\//,
    // Ignore specific middleware by name
    (name) => name === 'helmet',
  ],
  ignoreLayersType: [
    // Ignore all router spans
    ExpressLayerType.ROUTER,
  ],
});

Custom Request Attributes

import { ExpressInstrumentation, ExpressLayerType } from "@opentelemetry/instrumentation-express";

const expressInstrumentation = new ExpressInstrumentation({
  requestHook: (span, info) => {
    // Add custom attributes for request handlers only
    if (info.layerType === ExpressLayerType.REQUEST_HANDLER) {
      span.setAttribute('http.method', info.request.method);
      span.setAttribute('express.base_url', info.request.baseUrl);
      span.setAttribute('user.id', info.request.user?.id || 'anonymous');
    }
  },
});

Custom Span Naming

import { ExpressInstrumentation } from "@opentelemetry/instrumentation-express";

const expressInstrumentation = new ExpressInstrumentation({
  spanNameHook: (info, defaultName) => {
    // Customize span names for request handlers
    if (info.layerType === 'request_handler') {
      return `${info.request.method} ${info.route}`;
    }
    return defaultName;
  },
});

Important Notes

  • HTTP Instrumentation Required: Express instrumentation expects the HTTP layer to also be instrumented using @opentelemetry/instrumentation-http
  • Supported Express Versions: Works with Express 4.x and 5.x (>=4.0.0 <6)
  • Asynchronous Middleware Limitation: Time reported for asynchronous middleware represents only synchronous execution time, not asynchronous work
  • Node.js Version Support: Requires Node.js ^18.19.0 || >=20.6.0
  • Semantic Conventions: Uses OpenTelemetry semantic conventions v1.27.0 and sets http.route attribute

Error Handling

The instrumentation automatically captures and records exceptions that occur in Express middleware and request handlers. Errors are recorded as span exceptions with proper error status codes.

Integration with Other Instrumentations

Express instrumentation is designed to work alongside other OpenTelemetry instrumentations, particularly:

  • HTTP Instrumentation: Required for complete request lifecycle tracing
  • Database Instrumentations: For tracing database queries within Express handlers
  • External HTTP Client Instrumentations: For tracing outbound HTTP calls