Registry / observability / opentelemetry-esbuild-plugin-node

opentelemetry-esbuild-plugin-node

library4.4.0jsnpmunverified

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.

observability devops

npm install opentelemetry-esbuild-plugin-node

github ↗package ↗

INSTALL

IMPORT

SIG · OPENTELEMETRY-ESBU

opentelemetry-esbuild-plugin-node

observabilityjavascriptv4.4.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–223 runs

build_error

glibc

node 18–223 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

openTelemetryPlugin

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

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

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

getNodeAutoInstrumentations

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

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

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

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));

Debug

Known issues

gotchaFunctions 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.

affects: >=4.0.0

gotchaNode.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.

affects: >=4.0.0

gotchaThe 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.

affects: >=4.0.0

Errors

Common errors & fixes

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

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

fix

npm install @opentelemetry/auto-instrumentations-node

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

Installed esbuild version is too old for this plugin version.

fix

npm install esbuild@latest (ensure >=0.19.0)

TypeError: openTelemetryPlugin is not a function

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

fix

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

Upgrade

Version history

4.4.0latest on npm

Audit

Dependencies

esbuildrequiredPeer dependency; must be >=0.19.x for plugin compatibility.

@opentelemetry/auto-instrumentations-nodeoptionalProvides the getNodeAutoInstrumentations() function used to configure instrumentations.

Agent activity

16 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/DrewCorlin/opentelemetry-node-bundler-plugins ↗

packagehttps://www.npmjs.com/package/opentelemetry-esbuild-plugin-node ↗