Tim Nolet

This guide goes into the fundamentals, practical applications and tips & tricks of using OpenTelemetry (OTel) to monitor your Next.js application.

OpenTelemetry is gaining (a lot) of momentum outside of its historical niche of distributed, micro services based application stacks. But, as it turns out you can just as well use it for more traditional, three tiered, web applications and it comes with a host of benefits.

There are many great resources explaining what OTel is, how it came to be and what its purposes are. Here is quick recap:

OpenTelemetry is an open-source observability (o11y) framework for cloud-native software. OTel gives you a collection of tools, APIs, and SDKs to instrument, generate, collect, and export telemetry data — metrics, logs, and traces — for analysis in order to understand your apps’ and infrastructure’s performance and behavior.

Language-agnostic implementation. Note that not all SDKs support all of the telemetry types yet.

Support for distributed tracing, e.g. from your browser, to your API backend to databases, queues etc.

Automatic instrumentation for many popular frameworks and libraries, Next.js being one of them.

Installing the OpenTelemetry SDK in your app

The most foolproof way of installing OTel in a Next app is using the fairly recent @vercel/otel wrapper package which has some ✨ magic ✨ in dealing with the following:

It recognises if your Next app is running in a Node.js environment or Edge environment. This is pretty specific to Vercel. You might not need this when deploying your app to a standard Node server. For instance, Node.js standard modules like stream are not available in the Edge environment.

It replaces the standard OTel exporter package with a custom rewrite that is compatible with Vercel’s Edge runtime and also takes up less space MB wise.

Note that all code examples here use Next.js 14.x. OTel instrumentation is available in Next.js version 13.4 and higher.

First, you need to enabled the the Next.js specific OTel instrumentation by setting the instrumentationHook property to true in your next.config.js|ts file.

And create a file in the root of your project called instrumentation.ts|js.

The example above is the most simple way to get started. We will expand on it a little bit later to add some more customization.

This configuration auto-instruments all the basic HTTP handlers for page routes and API routes and emits traces with Next.js and /or Vercel specific tags. For instance, you might find a trace with the following properties:

operation.name: next_js.AppRender.getBodyResult

The official JS/TS OTel SDK does not support logging yet as of the time of writing.

This configuration only instruments the server-side. No traces or metrics are recorded for any browser-side interactions.

The configuration only records traces by default. You can add metrics though with a a custom setup.

Ok, instrumentation code done. This is where you normally hit npm run dev and see if things work locally before pushing commits. I recommend adding the the OTEL_LOG_LEVEL=debug environment variable in the beginning so you can make sure all things are wired up correctly.

Open your app on your http://localhost/ and click around. You will notice two things:

Your console should get filled up with OTel debug messages.

You’s see a line indicating that traces are exported to http://localhost:4318. This means you can conveniently test your OTel instrumentation locally. All you have to do is spin up a local Docker container with some OTel tools so you can debug. Vercel actually provide the useful repo https://github.com/vercel/opentelemetry-collector-dev-setup for this. Just clone it and run it.

This should spin up some containers. We are mostly interested in the otel-collector and jaeger-all-in-one containers. Now open the local Jaeger web UI on http://localhost:16686/ and you should find your Next app and some collected traces.

Your app is probably connecting to some other backend services like Postgres, MySQL, Redis or using a popular libraries like Prisma or the AWS SDK. We can instrument these package and generate traces for them using the @opentelemetry/auto-instrumentations-node package.

However, this is where we need to reconfigure our Nextjs app a bit, as these instrumentations are not compatible with the Vercel edge runtime. If you are not using Vercel to host your app, you can blissfully ignore this extra config.

We then create a dedicated instrumentation.node.ts file and configure it as follows:

And we modify the instrumentation.ts file we already have to only import this file if we are not running on the nodejs runtime.

If you restart your Next app now and visit it on your localhost, you will see A LOT of extra spans and traces. Probably way too much to make sense of. This is because we are now instrumentation all file system reads, network socket creations and a bunch of other things. You might want to keep them, or remove them for now. Keep reading 👇

I recommended adding the following exclusions to the auto instrumentation configuration. It pretty simple. Just pass in an object with the following structure to the getNodeAutoInstrumentations() function and set enabled to false.

Automatic Instrumentation is super useful, but you might want to track some metric, function call or 3rd party API call explicitly. So let’s create a custom trace and test it locally.

Have a look at the basic page.tsx example below. It should be reminiscent of a typical async fetching of some JSON data from some backend.

We are fetching a list of placeholder text from a 3rd party service in an async function called fetchData() .

We want to explicitly trace this call to this 3rd party service. We do this by importing the global trace object and starting and ending a custom span.

The startActiveSpan() function wraps the actual fetching of the 3rd party JSON.

We are also adding an Event to the span. Events are standard “markers” on OpenTelemetry traces to indicate some event happening during the recording of a span.

We are rendering the resulting JSON to a simple list.

Running the above code should result in a trace and span similar to this. Note that events are called "logs" in Jaeger 🤷

We’ve been working locally up till now, and one of the great benefits of OTel is that you actually CAN fully configure, instrument and debug it completely on your own machine.

Getting this into production typically requires at least these two steps.

1. Keeping cost down by head sampling on prod

Sending and storing OTel data (or any o11y data really) can get very expensive if your app has a lot of traffic or you are just generating a lot of traces. It can also get really noisy.

However, on our local development environment we actually DO want to keep all traces. We can do this by adding two sampling strategies.

Ratio based: only sample a percentage of traces.

Modify your instrumentation.ts as follows. Note we import the AlwaysOnSampler and the TraceIdRatioBasedSampler . We are using the ratio 0.1 here, so 10% of traces are sampled.

Using the default Vercel wrapper, this looks as follows:

If you added more customization in the instrumentation.node.ts file it looks as follows:

As you deploy your app to production, you will need an OTel compatible backend to export your data to. There are many players out there on the market, but they all have two things in common:

You send your data to some URL, typically on the standard OTel ports.

You need to configure an API key in some header.

You can configure this in your config file, but “the OTel way of doing things” is to use environment variables for this. I prefer using the environment variable way of doing things as we explicitly want to leverage the defaults in our local environment. So after picking a vendor, or maybe a self-hosted solution, export the following headers:

You can get started with tracing and OpenTelemetry on Checkly and get backend traces for all your synthetic monitoring checks. This works out-of-the-box with any Nextjs project. With Checkly Traces, you will have access to traces in all the places where it matters to more quickly resolve issues:

Check results: resolve production outages faster by correlating failing checks with backend traces.

Test sessions: understand any failures during test session execution.

Check Editors get a live trace while building, editing and debugging check code.

Sign up for a free Checkly account as https://app.checklyhq.com.

Check our docs on how to instrument your app and you should be tracing in 2 minutes.

An in-depth guide to monitoring Next.js apps with OpenTelemetry

Detect

Communicate

Resolve

Monitoring as Code

Developers

Resources

Community

An in-depth guide to monitoring Next.js apps with OpenTelemetry