{"id":11500,"library":"opentelemetry-instrumentation-express","title":"OpenTelemetry Express Instrumentation (Enhanced)","description":"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.","status":"active","version":"0.41.0","language":"javascript","source_language":"en","source_url":"https://github.com/aspecto-io/opentelemetry-ext-js","tags":["javascript","typescript"],"install":[{"cmd":"npm install opentelemetry-instrumentation-express","lang":"bash","label":"npm"},{"cmd":"yarn add opentelemetry-instrumentation-express","lang":"bash","label":"yarn"},{"cmd":"pnpm add opentelemetry-instrumentation-express","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency and core OpenTelemetry API for defining and propagating traces.","package":"@opentelemetry/api","optional":false},{"reason":"The web framework being instrumented.","package":"express","optional":false}],"imports":[{"note":"The library primarily uses named exports and is designed for ESM environments, though CommonJS `require` can still be used.","wrong":"const ExpressInstrumentation = require('opentelemetry-instrumentation-express');","symbol":"ExpressInstrumentation","correct":"import { ExpressInstrumentation } from 'opentelemetry-instrumentation-express';"}],"quickstart":{"code":"const express = require('express');\nconst { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');\nconst { registerInstrumentations } = require('@opentelemetry/instrumentation');\nconst { ExpressInstrumentation } = require('opentelemetry-instrumentation-express');\n\nconst tracerProvider = new NodeTracerProvider();\ntracerProvider.register();\n\nregisterInstrumentations({\n  tracerProvider,\n  instrumentations: [\n    new ExpressInstrumentation({ \n      // Optional: include HTTP attributes on spans\n      includeHttpAttributes: true,\n      // Optional: custom hook for adding attributes before request handling\n      requestHook: (span, { moduleVersion, req, res }) => {\n        span.setAttribute('my.custom.attribute', 'value');\n      }\n    })\n  ]\n});\n\nconst app = express();\n\napp.get('/', (req, res) => {\n  res.send('Hello OpenTelemetry Express!');\n});\n\napp.get('/users/:id', (req, res) => {\n  res.send(`User ID: ${req.params.id}`);\n});\n\napp.listen(3000, () => {\n  console.log('Server running on port 3000');\n});","lang":"javascript","description":"Demonstrates how to set up and register the ExpressInstrumentation with a NodeTracerProvider to automatically trace Express routes, including custom options."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"<4.9.0, >=5.0.0"},{"fix":"Choose one Express instrumentation library and ensure only one is installed and registered in your application. This package provides enhanced route attribute capturing.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"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`.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure `tracerProvider.register()` is called after creating your `NodeTracerProvider` instance to initialize the global tracer provider.","cause":"`NodeTracerProvider` (or similar provider) was instantiated but its `register()` method was not called, preventing the global OpenTelemetry API from being configured.","error":"TypeError: tracerProvider.register is not a function"},{"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.","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.","error":"No Express spans appear in my telemetry data."},{"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`.","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.","error":"My route parameters (e.g., `:id`) are not showing in `http.route` on spans."}],"ecosystem":"npm"}