Instrumentation

Observability is crucial for understanding and optimizing the behavior and performance of your app. Vercel supports OpenTelemetry instrumentation out of the box, which can be used through the package.

To get started, install the following packages:

Next, create a (or ) file in the root directory of the project, or, on Next.js it must be placed in the directory if you are using one. Add the following code to initialize and configure OTel using :

Context propagation connects operations across service boundaries so you can trace a request through your entire system. When your app calls another service, context propagation passes trace metadata (for example,trace IDs, span IDs) along with the request, typically through HTTP headers like . This lets OpenTelemetry link all the spans together into a single, complete trace.

Without context propagation, each service generates isolated spans you can't connect. With it, you see exactly how a request flows through your infrastructure—from the initial API call through databases, queues, and external services.

For more details on how context propagation works, see the OpenTelemetry context propagation documentation.

You can configure context propagation by configuring the option in the option.

Next.js 13.4+ supports automatic OpenTelemetry context propagation for incoming requests. For other frameworks, that do not support automatic OpenTelemetry context propagation, you can refer to the following code example to manually inject the inbound context into a request handler.

After installing , you can add custom spans to your traces to capture additional visibility into your application. Custom spans let you track specific operations that matter to your business logic, such as processing payments, generating reports, or transforming data, so you can measure their performance and debug issues more effectively.

Use the package to instrument specific operations:

Custom spans from functions using the Edge runtime are not supported.

For the full list of configuration options, see the @vercel/otel documentation.

• If your app uses manual OpenTelemetry SDK configuration without the usage of , you will not be able to use Session Tracing or Trace Drains.