{"id":21659,"library":"opentelemetry-esbuild-plugin-node","title":"OpenTelemetry Esbuild Plugin for Node.js","description":"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.","status":"active","version":"4.4.0","language":"javascript","source_language":"en","source_url":"https://github.com/DrewCorlin/opentelemetry-node-bundler-plugins","tags":["javascript","opentelemetry","bundler","esbuild","typescript"],"install":[{"cmd":"npm install opentelemetry-esbuild-plugin-node","lang":"bash","label":"npm"},{"cmd":"yarn add opentelemetry-esbuild-plugin-node","lang":"bash","label":"yarn"},{"cmd":"pnpm add opentelemetry-esbuild-plugin-node","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency; must be >=0.19.x for plugin compatibility.","package":"esbuild","optional":false},{"reason":"Provides the getNodeAutoInstrumentations() function used to configure instrumentations.","package":"@opentelemetry/auto-instrumentations-node","optional":true}],"imports":[{"note":"Package ships TypeScript types and is ESM-first. CommonJS require works but may lose type checking.","wrong":"const openTelemetryPlugin = require('opentelemetry-esbuild-plugin-node')","symbol":"openTelemetryPlugin","correct":"import { openTelemetryPlugin } from 'opentelemetry-esbuild-plugin-node'"},{"note":"This function is from the separate package @opentelemetry/auto-instrumentations-node, not from the plugin itself.","wrong":"import { getNodeAutoInstrumentations } from 'opentelemetry-esbuild-plugin-node'","symbol":"getNodeAutoInstrumentations","correct":"import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node'"}],"quickstart":{"code":"import { build } from 'esbuild';\nimport { openTelemetryPlugin } from 'opentelemetry-esbuild-plugin-node';\nimport { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';\n\nbuild({\n  entryPoints: ['src/server.ts'],\n  bundle: true,\n  outfile: 'dist/app.js',\n  platform: 'node',\n  target: 'node20',\n  plugins: [\n    openTelemetryPlugin({\n      instrumentations: getNodeAutoInstrumentations(),\n    }),\n  ],\n}).catch(() => process.exit(1));","lang":"typescript","description":"Shows minimal configuration to bundle OpenTelemetry Node.js instrumentations into an esbuild output."},"warnings":[{"fix":"Avoid closures or variable references in instrumentation configuration functions; use only parameters.","message":"Functions in instrumentation configs must be pure (cannot reference external scope) because the config is serialized and embedded into the bundle.","severity":"gotcha","affected_versions":">=4.0.0"},{"fix":"Initialize the NodeSDK with the appropriate builtin instrumentations (e.g., @opentelemetry/instrumentation-http) to cover builtins.","message":"Node.js builtin modules (e.g., http, fs) will NOT be instrumented by this plugin; they must be instrumented at runtime via the NodeSDK.","severity":"gotcha","affected_versions":">=4.0.0"},{"fix":"Use the externalModules option in the plugin AND set the same modules in esbuild's external option.","message":"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.","severity":"gotcha","affected_versions":">=4.0.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"npm install @opentelemetry/auto-instrumentations-node","cause":"Missing required peer dependency @opentelemetry/auto-instrumentations-node.","error":"Cannot find module '@opentelemetry/auto-instrumentations-node'"},{"fix":"npm install esbuild@latest (ensure >=0.19.0)","cause":"Installed esbuild version is too old for this plugin version.","error":"Error: Plugin openTelemetryPlugin: esbuild version must be >=0.19.x"},{"fix":"Use named import: import { openTelemetryPlugin } from 'opentelemetry-esbuild-plugin-node'","cause":"Incorrect import (e.g., using default import instead of named import).","error":"TypeError: openTelemetryPlugin is not a function"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}