Tracing
In observability, tracing is the process of collecting and analyzing how a request or operation flows through your application and through Vercel's infrastructure. Traces are used to explain how your application works, debug errors, and identify performance bottlenecks.
You can think of a trace as the story of a single request:
Request arrives at Vercel CDN -> Middleware executes -> Function handler processes request -> Database query runs -> Response returns to client
Each step in this process is a span. A span is a single unit of work in a trace. Spans are used to measure the performance of each step in the request and include a name, a start time, an end time, and a duration.
Vercel automatically instruments your application without needing any additional code changes. When you have set up Trace Drains or enabled Session Tracing for your Vercel Functions, you'll be able to visualize traces for:
- Vercel infrastructure: You'll be able to view spans showing the lifecycle of each invocation of your Vercel Functions and how it moves through Vercel's infrastructure, including routing, middleware, caching, and other infrastructure details.
- Outbound HTTP calls: The HTTP requests made from your function will be displayed as fetch spans, displaying information on the length of time, location, and other attributes.
For additional tracing, such as framework spans, you can install the @vercel/otel package to use the OpenTelemetry SDK. In addition, you can add custom spans to your traces to capture spans and gain more visibility into your application.
To visualize traces in your dashboard, you need to enable session tracing using the Vercel toolbar. Session tracing captures infrastructure, framework, and fetch spans for requests made during your individual session, making them available in the logs dashboard for debugging and performance monitoring.
You can initiate a session trace in two ways:
- Page Trace: Trace a single page load to see how that specific request flows through your application.
- Session Trace: Start an ongoing trace that captures all requests from your browser until you stop it or clear cookies.
For detailed instructions on starting traces, managing active sessions, and viewing previous traces, see the Session Tracing documentation.
Vercel uses OpenTelemetry, an open standard for collecting traces from your application. In order to capture framework and custom spans, install the @vercel/otel package. This package provides helper methods to make it easier to instrument your application with OpenTelemetry.
See the Instrumentation guide to set up OpenTelemetry for your project.
Once you have enabled session tracing, you can visualize traces in your dashboard:
- Select your team from the scope selector and select your project.
- Select the Logs tab.
- Use the tracing icon in the filter bar to filter to traces. You can filter traces using all the same filters available in the Logs tab of the dashboard. To view traces for requests to your browser, press the user icon next to the Traces icon.
- Find the request you want to view traces for and click the Trace button at the bottom of the request details panel. This will open the traces for that request:
When you view a trace in the dashboard, you see a timeline visualization of how a request flows through your application and Vercel's infrastructure. Each horizontal bar in the visualization is a span, which represents a single unit of work with a start time, end time, and duration.
When session tracing is enabled, your traces display the following types of spans:
| Span type | Visual appearance | Description |
|---|---|---|
| Infrastructure spans | Black and white with a triangle icon | Capture how requests move through Vercel's infrastructure, including routing, middleware, and caching. |
| Fetch spans | Green | Represent HTTP requests made from your functions. |
| Framework spans | Blue | Appear when you instrument your application with OpenTelemetry. Next.js 13.4+ automatically contributes spans for routes and rendering tasks. |
| Custom spans | Blue | Custom instrumentation you can add to your application using OpenTelemetry. |
To view details of a span, click on the span in the trace. The sidebar will display the span's details. For infrastructure spans, a "what is this?" explanation will be provided.
To view trace spans in more detail, click and drag to zoom in on a specific area of the trace. You can also use the zoom controls in the bottom right corner of the trace.
You can export traces to a third party observability provider using Vercel Drains. This can be done either by sending traces to a custom HTTP endpoint, or by using a native integration from the Vercel Marketplace.
See the Vercel Drains page to learn how to set up a Drain to export traces to a third party observability provider.
If you want to trace your Vercel application using @vercel/otel while also using Sentry SDK v8+, you need to configure them to work together. The Sentry SDK automatically sets up OpenTelemetry by default, which can conflict with Vercel's OpenTelemetry setup and break trace propagation.
To use both together, configure Sentry to work with your custom OpenTelemetry setup by following the Sentry custom setup documentation.
Using Vercel OTel instead of Sentry: If you prefer to use Vercel's
OpenTelemetry setup instead of Sentry's OTel instrumentation, add
skipOpenTelemetrySetup: true to your Sentry initialization in your
instrumentation.ts file. This resolves conflicts between Vercel's OTel and
Sentry v8+ that can prevent traces from reaching downstream providers.
Was this helpful?