@opentelemetry/instrumentation-express - Bare middleware can't resolve value for `http.route` attribute

[vitorvasc]

What version of OpenTelemetry are you using?

"dependencies": {
    "@opentelemetry/api": "^1.9.0",
    "@opentelemetry/instrumentation-express": "^0.57.0",
    "@opentelemetry/instrumentation-http": "^0.208.0",
    "@opentelemetry/sdk-metrics": "^2.2.0",
    "@opentelemetry/sdk-node": "^0.208.0",
    "@opentelemetry/sdk-trace-node": "^2.2.0",
    "express": "^5.1.0"
}

What version of Node are you using?

v24.11.0

This behavior was also reproduced in other applications using v18 and above.

What did you do?

When an Express application includes a bare middleware that returns a response before the route handler runs — such as an ETag cache check returning 304 Not Modified — the http.route attribute isn't populated with the full matched route.

The snippet below is a minimal example. Full code is available at: https://github.com/vitorvasc/js-otel-instrumentation-express.

main.js

// Bare Middleware that may return early (e.g., cache hit with 304)
apiRouter.use([(req, res, next) => {
  const etag = req.headers['if-none-match'];
  const currentETag = '"12345-abcdef"';

  if (etag && etag === currentETag) {
    res.status(304).end();  // Early return
    return;
  }
  next();
}]);

// Define routes
apiRouter.get('/users', handler);
apiRouter.get('/products', handler);

// Mount router
app.use('/', apiRouter);

cURL

curl http://localhost:${port}/api/users -H 'If-None-Match: "12345-abcdef"'

What did you expect to see?

Even if a middleware responds early, the http.route attribute should reflect the full matched route.

Expected behavior:

• Normal request (200): http.route = "/api/users"
• Bare middleware (304): http.route = "/api/users"

What did you see instead?

When a bare middleware finishes the request, the instrumentation captures only the router's mount path and loses the specific route information:

Actual behavior:

• Normal request (200): http.route = "/api/users"
• Bare middleware (304): http.route = "/api"

In this scenario, only /api is recorded instead of /api/users.

Metric output: `http.server.duration`

{
  descriptor: {
    name: 'http.server.duration',
    type: 'HISTOGRAM',
    description: 'Measures the duration of inbound HTTP requests.',
    unit: 'ms',
    valueType: 1,
    advice: {}
  },
  dataPointType: 0,
  dataPoints: [
    {
      attributes: {
        'http.scheme': 'http',
        'http.method': 'GET',
        'net.host.name': 'localhost',
        'http.flavor': '1.1',
        'http.status_code': 304,
        'net.host.port': 3000,
        'http.route': '/'
      },
      startTime: [ 1763685623, 177000000 ],
      endTime: [ 1763685624, 307000000 ],
      value: {
        min: 12.619138,
        max: 12.619138,
        sum: 12.619138,
        buckets: {
          boundaries: [
               0,    5,    10,   25,
              50,   75,   100,  250,
             500,  750,  1000, 2500,
            5000, 7500, 10000
          ],
          counts: [
            0, 0, 0, 1, 0, 0,
            0, 0, 0, 0, 0, 0,
            0, 0, 0, 0
          ]
        },
        count: 1
      }
    }
  ]
}

Additional context

I'm not sure whether this could be related to #1947.

Although the example uses an ETag scenario, this behavior appears in any application where bare middleware finishes the request before reaching an actual router — such as cached endpoints (HTTP 304), authentication (HTTP 401/403), rate limiting (HTTP 429), or request validation errors (HTTP 400).

If this is confirmed to be a valid issue from @opentelemetry/instrumentation-express, I'm happy to open a PR and contribute with a fix.

_{Tip: React with 👍 to help prioritize this issue. Please use comments to provide useful context, avoiding +1 or me too, to help us triage it. Learn more here.}

[JohannesHuster]

@vitorvasc Yeah, the current behavior is also described in the ticket you linked to. I posted an update there, as well.

I also didn't expect the current behavior, but I expected still another behavior 😅 In this case, I expected:

• Normal request (200): http.route = "/api/users"
• Bare middleware (304): http.route = "/api(/*)?" or something similar that correctly expresses how apiRouter.use matches.

I appreciate that the behavior you expected would be more helpful in this case to compare 304s to other status codes, by having http.route be the same.

My two cents on why people might expect http.route to behave differently: http.route is "The matched route template for the request [...]". However, that can be ambiguous when applying it to express, because you can match the request multiple times and dynamically decide whether to respond (res.send()) or allow later matches (next()) (or even do neither or both). I expected that the match of the handler that responds should go into http.route. In your case that would be two different handlers with two different matches, leading to different values in http.route.

[vitorvasc]

Hi @JohannesHuster, thanks for bringing this update here! I just read your last comment in #1947, and I also feel like this isn't completely fixed.

Even though I used the example to reproduce both the traces and metrics scenarios, the main issue we're seeing in our application actually comes from the metrics. By default, we always mount the router at '/' — and that's where the problem shows up. For a practical (and very simplified) example of how we ran into this, here's the scenario:

const app = express();
app.use(authenticationMiddleware);                 // Validate if user is authenticated. We can respond 401 here.
app.use(userHasPermissionsMiddleware);       // User is authenticated, but we check the permissions. We can respond 403 here.
app.use(validateETagMiddleware);                    //  Validate the If-None-Match header. We can respond 304 here.

app.use(simpleMiddleware);

const apiRouter = express.Router();

apiRouter.get('/users', (req, res) => {
  res.json({ success: true });
});

apiRouter.get('/products', (req, res) => {
  res.json({ success: true });
});

app.use(apiRouter);

We have several monitors watching the http.server.duration metric to track application health by grouping endpoints using the http.route attribute along with the status code.

An user may call /users and pass the validationi in the authenticationMiddleware, but later, in the userHasPermissionsMiddleware, we might validate that they only have permissions to access /products. In that case we return a 403. Since the router is mounted at '/', we lose visibility into which endpoint the user was actually trying to reach — the metric won't report the final route behind that 403.

On the other hand... I can't disagree that this becomes very, very ambiguous in Express. When I first said I was willing to work on a fix and submit a PR, I started digging into both Express and the instrumentation-express implementation to understand how it actually works. I've learned A LOT — and it's clear that, technically, the behavior makes sense: the request never reaches the route-handler layer. The only layer it reaches is '/', because that's where the middleware is mounted.

I'm also preparing a PR to propose a possible fix for this. I just haven't had the chance to do a final review before submitting it, but I can already see this probably requires more discussion, it's a tricky situation. 😅

[JohannesHuster]

Hi @vitorvasc, I see 🙂 I'm curious to see what you have in mind for a fix! And if it doesn't work out with a solution here, I have a few ideas that might help with your use case. Let me know, if you want any additional ideas.