OpenTelemetry Rollup Plugin Node

4.4.0 verified Mon Apr 27 auth: no javascript

Rollup plugin that bundles OpenTelemetry Node.js core and contrib instrumentations into your code during build. Current stable version is 4.4.0, released periodically as part of the opentelemetry-node-bundler-plugins monorepo. Key differentiator: it allows bundling OpenTelemetry instrumentation for deployment in serverless or embedded scenarios where runtime patching is not possible. Requires rollup and several peer dependencies, and works alongside other rollup plugins for TypeScript and CommonJS support. Note that it only patches non-builtin modules from opentelemetry-js-contrib, so builtin modules and SDK configuration must be handled separately.

Common errors

error Error: Must use import to load ES Module: /path/to/node_modules/opentelemetry-rollup-plugin-node/dist/index.js ↓

cause Attempting to require() an ES Module with CommonJS require().

fix

Change to dynamic import: const { openTelemetryPlugin } = await import('opentelemetry-rollup-plugin-node');

error TypeError: openTelemetryPlugin is not a function ↓

cause Default import used instead of named import, resulting in undefined.

fix

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

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

cause Missing required peer dependency.

fix

Install the package: npm install @opentelemetry/auto-instrumentations-node

Warnings

gotcha The plugin only instruments non-builtin modules from opentelemetry-js-contrib. Builtin modules (like http, fs) are not patched and must be handled separately with the NodeSDK. ↓

fix Use @opentelemetry/sdk-node with getNodeAutoInstrumentations for builtins, or configure builtin instrumentations manually via the plugin's builtinInstrumentations option if available.

deprecated The externalModules option might be removed or renamed in future releases. ↓

fix Use rollup's native external option instead.

breaking ESM-only: package no longer provides CommonJS exports since v3.0.0. ↓

fix Use import statement or dynamic import. Do not use require().

gotcha The plugin must be placed after nodeResolve in the plugins array to ensure module resolution works correctly. ↓

fix Order plugins as shown in the quickstart: nodeResolve first, then openTelemetryPlugin, then commonjs, json, typescript.

Install

npm install opentelemetry-rollup-plugin-node

yarn add opentelemetry-rollup-plugin-node

pnpm add opentelemetry-rollup-plugin-node

Imports

openTelemetryPlugin

wrong

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

correct

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

ESM-only; the package does not provide a CommonJS export. Use dynamic import if needed in CJS context.

openTelemetryPlugin

wrong

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

correct

const { openTelemetryPlugin } = await import('opentelemetry-rollup-plugin-node')

For CommonJS projects, use dynamic import. The package does not ship CJS.

openTelemetryPlugin

wrong

import defaultExport from 'opentelemetry-rollup-plugin-node'

correct

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

This is a named export, not a default export. Default import will give undefined.

Quickstart

Shows how to configure rollup with the OpenTelemetry plugin, including all required rollup plugins and basic instrumentation setup.

import { rollup } from 'rollup';
import { openTelemetryPlugin } from 'opentelemetry-rollup-plugin-node';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
import path from 'path';
import typescript from '@rollup/plugin-typescript';
import commonjs from '@rollup/plugin-commonjs';
import nodeResolve from '@rollup/plugin-node-resolve';
import json from '@rollup/plugin-json';

async function build() {
  const bundle = await rollup({
    input: path.normalize(__dirname + '/../src/app.ts'),
    plugins: [
      nodeResolve({ extensions: ['.mjs', '.js', '.json', '.ts'] }),
      openTelemetryPlugin({
        instrumentations: getNodeAutoInstrumentations({
          '@opentelemetry/instrumentation-pino': {
            logKeys: {
              traceId: 'traceId',
              spanId: 'spanId',
              traceFlags: 'traceFlags',
            },
          },
        }),
      }),
      commonjs(),
      json(),
      typescript({ tsconfig: path.normalize(__dirname + '/../tsconfig.json'), sourceMap: false }),
    ],
  });
  await bundle.write({ file: path.normalize(__dirname + '/../dist/app.js'), format: 'cjs' });
  await bundle.close();
}

build().catch(console.error);