OpenTelemetry Esbuild Plugin for Node.js

4.4.0 verified Mon Apr 27 auth: no javascript

An esbuild plugin that bundles OpenTelemetry Node.js core and contrib instrumentations into your application at build time. Version 4.4.0 is the latest stable release, with active development. It simplifies adding OpenTelemetry tracing to Node.js apps by patching non-builtin packages and supporting configuration of instrumentations via the standard `@opentelemetry/auto-instrumentations-node` API. Differentiators: works specifically with esbuild, serializes instrumentation configuration at build time (leading to limitations on functions in configs), and does not bundle Node.js builtins (which are handled at runtime by the NodeSDK). Peer dependency on esbuild >=0.19.x.

Common errors

error Cannot find module '@opentelemetry/auto-instrumentations-node' ↓

cause Missing required peer dependency @opentelemetry/auto-instrumentations-node.

fix

npm install @opentelemetry/auto-instrumentations-node

error Error: Plugin openTelemetryPlugin: esbuild version must be >=0.19.x ↓

cause Installed esbuild version is too old for this plugin version.

fix

npm install esbuild@latest (ensure >=0.19.0)

error TypeError: openTelemetryPlugin is not a function ↓

cause Incorrect import (e.g., using default import instead of named import).

fix

Use named import: import { openTelemetryPlugin } from 'opentelemetry-esbuild-plugin-node'

Warnings

gotcha Functions in instrumentation configs must be pure (cannot reference external scope) because the config is serialized and embedded into the bundle. ↓

fix Avoid closures or variable references in instrumentation configuration functions; use only parameters.

gotcha Node.js builtin modules (e.g., http, fs) will NOT be instrumented by this plugin; they must be instrumented at runtime via the NodeSDK. ↓

fix Initialize the NodeSDK with the appropriate builtin instrumentations (e.g., @opentelemetry/instrumentation-http) to cover builtins.

gotcha The externalModules option is similar to esbuild's external but only affects plugin resolution; set the same modules as external in esbuild config to avoid bundling them twice. ↓

fix Use the externalModules option in the plugin AND set the same modules in esbuild's external option.

Install

npm install opentelemetry-esbuild-plugin-node

yarn add opentelemetry-esbuild-plugin-node

pnpm add opentelemetry-esbuild-plugin-node

Imports

openTelemetryPlugin

wrong

const openTelemetryPlugin = require('opentelemetry-esbuild-plugin-node')

correct

import { openTelemetryPlugin } from 'opentelemetry-esbuild-plugin-node'

Package ships TypeScript types and is ESM-first. CommonJS require works but may lose type checking.

getNodeAutoInstrumentations

wrong

import { getNodeAutoInstrumentations } from 'opentelemetry-esbuild-plugin-node'

correct

import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node'

This function is from the separate package @opentelemetry/auto-instrumentations-node, not from the plugin itself.

Quickstart

Shows minimal configuration to bundle OpenTelemetry Node.js instrumentations into an esbuild output.

import { build } from 'esbuild';
import { openTelemetryPlugin } from 'opentelemetry-esbuild-plugin-node';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';

build({
  entryPoints: ['src/server.ts'],
  bundle: true,
  outfile: 'dist/app.js',
  platform: 'node',
  target: 'node20',
  plugins: [
    openTelemetryPlugin({
      instrumentations: getNodeAutoInstrumentations(),
    }),
  ],
}).catch(() => process.exit(1));