To set up OpenTelemetry in a Node.js backend, install @opentelemetry/auto-instrumentations-node, set four environment variables, and start Node with its register file preloaded: --require for CommonJS, --import plus a loader hook for ES modules. Express then sends traces and metrics with no code change. Fastify and Next.js need one small file. Logs need Pino, Winston or Bunyan.1,2,15

The setup is short. The parts that go wrong fail silently: an ES modules app started the CommonJS way still sends traces but no logs, console.log is never exported, Winston needs one extra package, and Fastify dropped out of the auto-instrumentation bundle this year. This post covers the setup step by step, then each of those, then what the data turns into once it lands. If you would rather not do it by hand, your coding agent can: paste "Read fixter.dev/llms.txt and set up Fixter." into Claude Code or Cursor in your project.17 Running Python too? The same setup for FastAPI, Django and Flask is in OpenTelemetry for Python.

What you get for each framework

@opentelemetry/auto-instrumentations-node is a bundle: one install brings the instrumentation for Express, the Node HTTP server, database drivers such as pg, mysql2, mongodb and ioredis, outbound fetch calls through undici, and the Pino, Winston and Bunyan loggers. They patch each library as Node loads it, so you do not add tracing calls to your handlers.1,3

ExpressFastifyNext.js API routes
Instrumentation@opentelemetry/instrumentation-express, in the bundle@fastify/otel, from the Fastify team, installed on its ownNext.js emits its own spans; the bundle adds database and outbound calls
How it startsnode --require, or --import with the loader hook for ES modulesA small telemetry file that adds @fastify/otel, preloaded the same wayinstrumentation.ts in the project root
A span for each requestYes, plus spans for middleware and the route handlerYes from the HTTP instrumentation; route and hook spans need @fastify/otelYes, one for each API route
Errors on the traceA thrown error or next(err) is recorded on the spanThrough your logsThrough onRequestError and your logs
LogsPino, Winston or BunyanFastify logs through Pino once you turn its logger onPino; log server errors from onRequestError
Silent trapAn ES modules app started with --require sends traces but no logsThe bundle no longer covers FastifyThe Node SDK must only load in the Node.js runtime

From the OpenTelemetry JavaScript docs and repositories, the Fastify and Next.js docs, November 19, 2026.2,3,9,10,11,12,13

The current release is @opentelemetry/auto-instrumentations-node 0.83.1, published November 12, 2026. It needs Node.js 22.15.0 or newer.4

How to set up OpenTelemetry in Node.js, in five steps

The steps below are for Express or any other Node app with no framework file of its own, and they send to Fixter. Fastify and Next.js change step four; their sections follow. Steps one and four are the same for any backend that accepts OTLP, and the variables in step three are standard OpenTelemetry with Fixter's endpoint and key in them.1,15

  1. Install the packages. The bundle brings the SDK, the exporters and the instrumentations.1
Terminal
npm install @opentelemetry/api @opentelemetry/auto-instrumentations-node
  1. Create an API key. In the Fixter app, open Settings, API keys and create one. It starts with fixter_sk_ and is shown once, so store it with your other secrets as FIXTER_API_KEY.15
  2. Set four environment variables, wherever your deploy defines its environment: the shell, a compose file, the Deployment's env block.15
Environment
OTEL_SERVICE_NAME=checkout-service
OTEL_EXPORTER_OTLP_ENDPOINT=https://ingest.fixter.dev
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer $FIXTER_API_KEY"

# names the environment, so production and staging stay apart
OTEL_RESOURCE_ATTRIBUTES=deployment.environment.name=production

In Node the defaults already fit: traces, metrics and logs each export over OTLP, and the protocol defaults to http/protobuf, which is what Fixter takes.5,15 The protocol line only makes that explicit. The fifth line names the environment; it is one extra line and keeps production apart from staging later.15

  1. Start Node with the register file preloaded. Which command depends on how your app runs, and the next section shows how to tell.2
Terminal
# CommonJS (no "type": "module" in package.json)
node --require @opentelemetry/auto-instrumentations-node/register app.js

# ES modules ("type": "module", or .mjs files)
node --experimental-loader=@opentelemetry/instrumentation/hook.mjs \
  --import @opentelemetry/auto-instrumentations-node/register app.js

If your app starts through a script you do not want to edit, put the flag in NODE_OPTIONS instead:3

Terminal
# when the start command is a script you do not control
NODE_OPTIONS="--require @opentelemetry/auto-instrumentations-node/register" npm start
  1. Check that it arrived. Send a request to your app, then open the Logs page in Fixter and filter on your service name. Or ask your coding agent, once it is connected to Fixter over MCP: "Show me the last errors from checkout-service."15

Some instrumentations are noisy for a small app. To switch one off, list it without the @opentelemetry/instrumentation- prefix, for example OTEL_NODE_DISABLED_INSTRUMENTATIONS=fs,dns.3

CommonJS or ES modules: the trap that fails silently

Node loads CommonJS and ES modules through two different loaders, and --require only hooks the first. Start an ES modules app with --require alone and nothing errors or warns. Traces still appear, because CommonJS dependencies are still patched, but libraries the app loads with import, such as pino, are not. So no logs and no trace_id reach the backend.2,15

How to tell which one you run:2

  • ES modules: "type": "module" in the package.json of the built app, or .mjs files.
  • TypeScript: what counts is what tsconfig.json compiles to. Source written with import can still compile to require calls, and then the app is CommonJS.
  • A CommonJS app with ES modules dependencies can need the loader hook too. When a dependency that is itself an ES module imports an instrumented package, that package goes through the ES modules loader and is not patched. The OpenTelemetry docs give NestJS 12 importing Express as the example.

For ES modules, the OpenTelemetry docs name @opentelemetry/instrumentation/hook.mjs as the only supported loader hook, passed with --experimental-loader, which is the second command in step four.2

Logs: why console.log sends nothing

Traces come from the framework and library instrumentations. Logs only come from a logging library that OpenTelemetry bridges, and in Node that means Pino, Winston or Bunyan. A service that logs with console.log sends traces and metrics but no logs at all.15 Each bridge does two things: it sends each record to the OpenTelemetry logs SDK, and it adds trace_id and span_id to records written during a request, so you can go from an error line to the request that produced it.6,7,8

LoggerSends logsExtra stepVersions
PinoYesNonepino 5.14 up to 10 for trace ids; log sending from pino 7
WinstonYesnpm install @opentelemetry/winston-transportLog sending needs Winston 3
BunyanYesNone; an err field is exported as exception attributesbunyan 1
console.logNoMove to one of the aboveNone

Winston is the one that catches people. The instrumentation is in the bundle, but it only sends logs when @opentelemetry/winston-transport is installed in the project. Without it you get the trace_id on your console lines and nothing exported.7

Terminal, Winston only
npm install @opentelemetry/winston-transport

Log the error object, not only a message, and log it while the request is still running so the record carries its trace:6

Express, with Pino
import pino from 'pino';

const logger = pino();

app.post('/checkout', async (req, res) => {
  try {
    await charge(req.body.orderId);
    res.sendStatus(204);
  } catch (err) {
    // exported as an OpenTelemetry log record,
    // with the trace_id of this request
    logger.error({ err, orderId: req.body.orderId }, 'charge failed');
    throw err;
  }
});

Express adds a second path for errors. When a route handler throws, or passes an error to next(), the Express instrumentation records the exception on that handler's span and marks the span as failed, so the error and its stack trace sit on the trace even when nothing is logged.9

Fastify: one extra package

The OpenTelemetry Fastify instrumentation was deprecated in January 2025 and removed from the bundle in March 2026, in favour of @fastify/otel, maintained by the Fastify authors.3 With the bundle alone, each Fastify request still gets a span from the HTTP instrumentation, but none of the Fastify route and hook spans.10

@fastify/otel can register itself through the Node SDK, so you swap the register file for a short telemetry file of your own and preload that instead:10

Terminal
npm install @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node @fastify/otel
telemetry.cjs
// telemetry.cjs
const { NodeSDK } = require('@opentelemetry/sdk-node');
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
const FastifyOtelInstrumentation = require('@fastify/otel');

// exporters and service name come from the OTEL_ variables
const sdk = new NodeSDK({
  instrumentations: [
    getNodeAutoInstrumentations(),
    new FastifyOtelInstrumentation({ registerOnInitialization: true }),
  ],
});

sdk.start();
Terminal
node --require ./telemetry.cjs server.js

The four variables from step three stay as they are. For an ES modules Fastify app, write the same file as telemetry.mjs with imports and start it with the loader hook and --import ./telemetry.mjs.2 For logs, turn Fastify's logger on with logger: true: it is off by default, and it is Pino underneath, so request.log.error(...) goes through the Pino bridge.11,6

Next.js API routes: instrumentation.ts

Next.js has its own place for this: an instrumentation.ts file in the project root, or in src/ if you use one. Its register function runs once when the server starts, before it handles requests. The Node SDK does not run in the edge runtime, so load it only when NEXT_RUNTIME is nodejs.12,13

Terminal
npm install @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node pino
instrumentation.node.ts
// instrumentation.node.ts
import { NodeSDK } from '@opentelemetry/sdk-node';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';

// exporters and service name come from the OTEL_ variables
const sdk = new NodeSDK({
  instrumentations: [getNodeAutoInstrumentations()],
});

sdk.start();
instrumentation.ts
// instrumentation.ts, in the project root (or in src/)
import type { Instrumentation } from 'next';

export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    await import('./instrumentation.node.ts');
  }
}

export const onRequestError: Instrumentation.onRequestError = async (err, request, context) => {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    const { logger } = await import('./lib/logger');
    logger.error({ err, path: request.path, route: context.routePath }, 'request failed');
  }
};

Next.js is already instrumented, so once an SDK is running you get a root span for each request and an "executing api route" span for each Route Handler. Set NEXT_OTEL_VERBOSE=1 to see more of its spans.12 The onRequestError export runs whenever the Next.js server catches an error, in Route Handlers, Server Components and Server Actions, which makes it the place to log server errors through Pino.13 lib/logger in the example stands for a module that exports your Pino logger.

Pick Pino here. Next.js bundles the dependencies of Route Handlers and Server Components by default, and keeps a short list of packages it leaves out of the bundle and loads with Node's own require. pino is on that list; winston is not.14 If you use Winston and your logs do not arrive, add winston to serverExternalPackages in next.config.js.14

What shows up as issues

Telemetry on its own is a pile of rows. What you want from it is a short list of what is broken. Fixter (fixter.dev) finds and fixes the issues in your app in production, from your coding agent: errors, failing infrastructure, slow requests and downtime. It finds the root cause and fixes it: in your agent over MCP, or as a pull request ready for your review. Nothing to learn, built for small teams.

With the setup above, this is what your Node app's data becomes:16

  • One issue for each error, not one row for each time it happened. Fixter parses the stack trace and groups every occurrence with the same cause, so a TypeError thrown thousands of times is one issue with a count, tagged with the Node runtime. Errors that differ only by an id, such as "Order 8f2c1a not found" and "Order b31e07 not found", stay together.
  • Error logs with no exception. An error-level line with no stack trace is grouped by its message.
  • Where to look. Each issue names the exception type and message, the frame that threw and the frame that called it, the service, when it was first and last seen, and a link to the trace and log of each occurrence.
  • A service that logs without trace ids. If a service sends spans but most of its logs carry no trace id, Fixter raises that as an issue of its own, so a logging setup that lost its trace context does not go unnoticed.
  • Staging and production kept apart. The environment name from step three is recorded on every occurrence.

There is no separate error SDK to add for this. The issues are built from the logs and traces you already send.16 You hear about a new one by email or Slack, and you can ask about them from your coding agent. For the agent side, see how to debug production with Claude Code and how to set up error monitoring with Claude Code. If your app also calls a model, Claude API tracing puts those calls in the same traces.

If nothing shows up

  • Traces but no logs. The app logs with console.log, or it is an ES modules app started with --require only, or it uses Winston without @opentelemetry/winston-transport.2,7,15
  • A 401 in the exporter output. The Authorization header is not reaching Fixter or the key was revoked. Check that the variable is set in the process's own environment, not only in your shell.15
  • Nothing at all, and no error. Set OTEL_LOG_LEVEL=debug for one run to see what the SDK is doing; it is very verbose, so turn it back off.1
  • No spans from one library. It is not in the bundle's list, or a dependency that is an ES module loads it. See the CommonJS and ES modules section.2,3
  • Fastify requests with no route names. @fastify/otel is missing.3,10
  • Install fails or the SDK will not start on an older Node. The current packages need Node.js 22.15.0 or newer.4
  • Data under the wrong name. Set OTEL_SERVICE_NAME.15

Key takeaways

  • One npm package, four environment variables, then the register file preloaded with --require or, for ES modules, --import plus the loader hook
  • Starting an ES modules app with --require fails silently: traces arrive, logs do not
  • console.log is never exported; Pino, Winston and Bunyan are, and Winston needs @opentelemetry/winston-transport
  • Fastify needs @fastify/otel; Next.js uses instrumentation.ts and onRequestError
  • The current packages need Node.js 22.15.0 or newer
  • Or paste "Read fixter.dev/llms.txt and set up Fixter." into your coding agent

Frequently asked questions

How do I add OpenTelemetry to a Node.js app without changing code?

Install @opentelemetry/auto-instrumentations-node, set the OTEL_ environment variables for your backend, and start the app with node --require @opentelemetry/auto-instrumentations-node/register app.js. For an app that runs as ES modules, add the loader hook: node --experimental-loader=@opentelemetry/instrumentation/hook.mjs --import @opentelemetry/auto-instrumentations-node/register app.js.

Why does my Node.js app send traces but no logs?

Two common causes. The app logs with console.log, which OpenTelemetry does not export: only Pino, Winston and Bunyan are bridged. Or the app runs as ES modules and was started with --require only, so libraries loaded through import, such as pino, are never patched. Winston also needs the @opentelemetry/winston-transport package installed before it sends logs.

How do I know if my Node.js app is CommonJS or ES modules?

Look at the package.json of the app you run, after the build. "type": "module" or .mjs files mean ES modules. For TypeScript, what counts is what tsconfig.json compiles to: import statements in your source can still compile to require calls.

Does auto-instrumentations-node cover Fastify?

Not any more. The OpenTelemetry Fastify instrumentation was deprecated in January 2025 and removed from the bundle in March 2026, in favour of @fastify/otel from the Fastify team. Without it, Fastify requests still get a span from the HTTP instrumentation, but no route or hook spans.

How do I add OpenTelemetry to Next.js API routes?

Create instrumentation.ts in the project root with a register function, and start the OpenTelemetry Node SDK from it only when process.env.NEXT_RUNTIME is nodejs. Next.js then emits its own span for each API route, and the auto-instrumentations add database and outbound calls. Export onRequestError from the same file to log server errors.

Which Node.js version does OpenTelemetry need?

The current release of @opentelemetry/auto-instrumentations-node, 0.83.1 from November 12, 2026, requires Node.js 22.15.0 or newer according to npm. So do @fastify/otel and @opentelemetry/winston-transport. Older Node versions need an older OpenTelemetry release.

Can my coding agent set up OpenTelemetry for my Node.js app?

Yes. Paste "Read fixter.dev/llms.txt and set up Fixter." into Claude Code, Cursor or another coding agent in your project. It adds standard OpenTelemetry to the app and points it at Fixter. Because it is standard OpenTelemetry, the same instrumentation works with any backend that accepts OTLP.

Sources (17), all checked November 19, 2026
  1. OpenTelemetry docs, JavaScript zero-code instrumentation (install, register, NODE_OPTIONS)
  2. opentelemetry-js, ECMAScript Modules vs. CommonJS (how to tell, the loader hook, the ESM start command)
  3. opentelemetry-js-contrib, auto-instrumentations-node README (supported instrumentations, Fastify removed, enabling and disabling instrumentations)
  4. npm, @opentelemetry/auto-instrumentations-node (version 0.83.1, November 12, 2026, requires Node.js 22.15.0 or newer)
  5. opentelemetry-js, sdk-node README (traces, metrics and logs exporters default to otlp, protocol defaults to http/protobuf)
  6. opentelemetry-js-contrib, Pino instrumentation README (log sending from pino 7, supported versions, trace_id on each record)
  7. opentelemetry-js-contrib, Winston instrumentation README (log sending needs @opentelemetry/winston-transport, Winston 3 only)
  8. opentelemetry-js-contrib, Bunyan instrumentation README (log sending, the err field as exception attributes)
  9. opentelemetry-js-contrib, Express instrumentation source (a thrown error or next(err) is recorded on the span)
  10. Fastify, @fastify/otel README (registerOnInitialization, Node.js 22.15.0 or newer, needs the HTTP instrumentation)
  11. Fastify docs, Logging (off by default, uses Pino)
  12. Next.js docs, How to set up instrumentation with OpenTelemetry (instrumentation.ts, NodeSDK only in the Node.js runtime, default spans)
  13. Next.js docs, instrumentation.js file convention (register, onRequestError)
  14. Next.js docs, serverExternalPackages (packages left out of the server bundle by default, pino among them)
  15. Fixter docs, Send data with OpenTelemetry (API key, four environment variables, Node.js recipe, environment name)
  16. Fixter docs, Issues (grouping, runtime tags, log errors, environments)
  17. Fixter, llms.txt (what the setup prompt tells your agent to do)