Registry / observability / opentelemetry-instrumentation-express

opentelemetry-instrumentation-express

JSON →
library0.41.0jsnpmunverified

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.

observabilityhttp-networkingweb-framework
npm install opentelemetry-instrumentation-express
github ↗package ↗
INSTALL
IMPORT
SIG · OPENTELEMETRY-INST
O
opentelemetry-instrumentation-express
observabilityjavascriptv0.41.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–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

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

ExpressInstrumentation
✓ import { ExpressInstrumentation } from 'opentelemetry-instrumentation-express';
✗ const ExpressInstrumentation = require('opentelemetry-instrumentation-express');
The library primarily uses named exports and is designed for ESM environments, though CommonJS `require` can still be used.

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'); });
Debug
Known issues
breakingThis 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.
affects: <4.9.0, >=5.0.0
gotchaThis 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.
affects: >=0.1.0
gotchaThe `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.
affects: >=0.1.0
Errors
Common errors & fixes
TypeError: tracerProvider.register is not a function
`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.
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.
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`.
Upgrade
Version history
0.41.0latest on npm
Audit
Dependencies
@opentelemetry/apirequiredPeer dependency and core OpenTelemetry API for defining and propagating traces.
expressrequiredThe web framework being instrumented.
Agent activity
9 hits · last 30 days
node
8
OpenAI (training)
1
Resources
githubhttps://github.com/aspecto-io/opentelemetry-ext-js ↗
packagehttps://www.npmjs.com/package/opentelemetry-instrumentation-express ↗