Next.js 15 app gives "GET unknown route" for transaction name

Elastic Observability APM
1

I am building API endpoints using Next.js API Routes (Next.js v15.x). I've instrumented my app using elastic-apm-node as described in the Getting started with Next.js guide. When invoking my API endpoint, a trace shows up in Elastic Observability, but the transaction name is GET unknown route. I saw this note about unknown routes in Next.js apps, and some other general troubleshooting tips regarding unknown routes, and it seems there are two possible causes:

  1. I'm using an unsupported framework.
  2. There is an issue with how I've configured the agent.

#2 is entirely possible, but I suspect the issue may be #1, since Elastic APM's "Getting started with Next.js" guide explicitly says:

This Next.js instrumentation is a technical preview while we solicit feedback from Next.js users. Currently next versions >=12.0.0 <13.3.0 are supported

Can someone please confirm: is the "unknown route" problem to be expected, given that I'm running Next.js 15? Or would you have expected the transaction name to accurately reflect the route that handled the request?

If the issue is #1 (an agent/framework compatibility issue), when can we expect to see an updated APM agent that supports newer Next.js versions?

APM Agent language and version:
elastic-api-node v4.11.2

Next.js version:
15.2.3

2

Hi @azach-ewtn,

The issue is 1. I'm using an unsupported framework.
The current Next.js instrumentation looks at the next version and will not instrument at all if it is outside of the >=12.0.0 <13.3.0 range.

The Next.js instrumentation in elastic-apm-node unfortunately never got out of being a technical preview. Our focus now is on OpenTelemetry-based APM agents, for which we have a new and separate agent: EDOT Node.js. This is a separate package, @elastic/opentelemetry-node, rather than elastic-apm-node.

For Next.js instrumentation, our recommendation is to look into using the native OpenTelemetry support in Next.js itself. See Guides: OpenTelemetry | Next.js

We don't yet have a Next.js-related getting start document with our OpenTelemetry-based agent (EDOT Node.js). Unfortunately, our older Node.js APM agent (package elastic-apm-node) is not expected to get updated Next.js instrumentation.

3

Thank you for the quick reply, Trent! I'll look into EDOT and report back.

For the benefit of future readers, it might be nice to note in the Elastic APM "Getting started with Next.js" docs that no further investment is being made in that solution for instrumenting Next.js apps, and that EDOT is the way to go.

4

I ended up implementing the instrumentation using @vercel/otel as recommended in the Next.js OpenTelemetry guide. For what it's worth, I had tried that before, and seen that it was missing a few of the things that the elastic-apm-node agent provided out of the box, namely:

  • propagating trace context to downstream services, allowing for a true distributed trace view
  • populating the service.environment attribute to allow for proper environment filtering.

After a bit more research on the @vercel/otel configuration options, I was able to get both of those features working to my satisfaction. And of course, most importantly for this discussion, the transaction names are properly named after the route as well!