OpenTelemetry Express Instrumentation (Enhanced)

0.41.0 · active · verified Sun Apr 19

opentelemetry-instrumentation-express is an enhanced instrumentation library for the `express` web framework, designed to integrate seamlessly with OpenTelemetry for Node.js applications. Currently at version 0.41.0, it is actively maintained and part of the `aspecto-io/opentelemetry-ext-js` project, which sees frequent updates. This package differentiates itself from the standard `@opentelemetry/instrumentation-express` by providing more granular and accurate route information through custom span attributes like `express.route.full`, `express.route.configured`, and `express.route.params`, which capture the full path and parsed parameters. It also tracks `express.unhandled` requests, offering better insights into unhandled routes and 404s. The instrumentation supports Express versions `^4.9.0` and is suitable for detailed tracing of Express applications where precise route context is crucial for observability.

Common errors

```
TypeError: tracerProvider.register is not a function
```
cause `NodeTracerProvider` (or similar provider) was instantiated but its `register()` method was not called, preventing the global OpenTelemetry API from being configured.

fix Ensure `tracerProvider.register()` is called after creating your `NodeTracerProvider` instance to initialize the global tracer provider.
```
No Express spans appear in my telemetry data.
```
cause The `ExpressInstrumentation` might not be correctly registered, or OpenTelemetry is not fully set up. This can also happen if the Express version is unsupported.

fix Verify that `registerInstrumentations` is called with `ExpressInstrumentation`, that a `tracerProvider` is registered, and that your `express` package version is `^4.9.0`. Ensure OpenTelemetry environment variables (e.g., `OTEL_SERVICE_NAME`) are correctly set.
```
My route parameters (e.g., `:id`) are not showing in `http.route` on spans.
```
cause The `http.route` attribute often reports the parameterized route template. If you expect specific values for `id` or other params, you need to look at other attributes.

fix The specific matched parameter values for a request are available in the `express.route.params` attribute (as a JSON stringified map). For the full resolved path, consider `express.route.full`.

Warnings

breaking This instrumentation explicitly supports Express versions `>=4.9.0` and `<5.0.0`. It will not work with Express v5.0.0 or higher once it is officially released and may not function correctly with older Express versions.
Fix: Ensure your `express` dependency is within the `^4.9.0` range. Monitor for updates to this instrumentation that explicitly add Express v5.x support.
gotcha This package, `opentelemetry-instrumentation-express` from Aspecto, is an *alternative* to the `@opentelemetry/instrumentation-express` package from the OpenTelemetry Contrib repository. Using both simultaneously can lead to conflicting or duplicated spans.
Fix: Choose one Express instrumentation library and ensure only one is installed and registered in your application. This package provides enhanced route attribute capturing.
gotcha The `http.route` attribute, while conventional, may not always contain the complete path if the request is terminated early or handled by middlewares that accept partial paths. For the full or more specific route details, consult `express.route.full` or `express.route.configured`.
Fix: When analyzing traces, understand the nuances of `http.route` and leverage the `express.route.full`, `express.route.configured`, and `express.route.params` attributes for a comprehensive understanding of the Express route.

Install

npm install opentelemetry-instrumentation-express npm
yarn add opentelemetry-instrumentation-express yarn
pnpm add opentelemetry-instrumentation-express pnpm

Imports

ExpressInstrumentation

wrong:

const ExpressInstrumentation = require('opentelemetry-instrumentation-express');

correct:

import { ExpressInstrumentation } from 'opentelemetry-instrumentation-express';

The library primarily uses named exports and is designed for ESM environments, though CommonJS `require` can still be used.

Quickstart

Demonstrates how to set up and register the ExpressInstrumentation with a NodeTracerProvider to automatically trace Express routes, including custom options.

const express = require('express');
const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
const { registerInstrumentations } = require('@opentelemetry/instrumentation');
const { ExpressInstrumentation } = require('opentelemetry-instrumentation-express');

const tracerProvider = new NodeTracerProvider();
tracerProvider.register();

registerInstrumentations({
  tracerProvider,
  instrumentations: [
    new ExpressInstrumentation({ 
      // Optional: include HTTP attributes on spans
      includeHttpAttributes: true,
      // Optional: custom hook for adding attributes before request handling
      requestHook: (span, { moduleVersion, req, res }) => {
        span.setAttribute('my.custom.attribute', 'value');
      }
    })
  ]
});

const app = express();

app.get('/', (req, res) => {
  res.send('Hello OpenTelemetry Express!');
});

app.get('/users/:id', (req, res) => {
  res.send(`User ID: ${req.params.id}`);
});

app.listen(3000, () => {
  console.log('Server running on port 3000');
});

view raw JSON →