Session tracing

Session tracing provides insights into your application's interaction with Vercel infrastructure, including routing, middleware, caching, and function startup.

Tracing is available on all plans with a limit up to 1 million spans per month, per team.

In this guide, you'll learn how to get started with session tracing on Vercel. Session tracing allows you to analyze the performance of your application and understand how it interacts with Vercel's infrastructure.

Session tracing lets you:

• Understand routing, middleware, caching, and function startup.
• Inspect user-instrumented spans without external tracing tools.
• Identify performance bottlenecks in your application.
• View Vercel infrastructure spans alongside your application spans.

Each trace displays:

• Vercel infrastructure spans in black and white with a triangle icon.
• If you have instrumented your application with OpenTelemetry, user spans will be displayed in color. Next.js 13.4+ contributes top-level spans for routes and rendering tasks.
• Fetch spans

Click any span to view details in the sidebar. Infrastructure spans include a "What is this?" explanation.

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.

• A Vercel account. If you don't have one, you can sign up for free.
• A Vercel project. If you don't have one, you can create a new project.
• The toolbar enabled in your preview or production environment.

1. In the Vercel toolbar on your deployment, click (or search for) Tracing.
2. Select Run Page Trace.
3. The page will reload, and a toast will indicate the status of the trace. Once the trace has propagated, the toast will indicate that the trace is complete and ready to view.
4. Click the toast to view the trace in a new browser tab under the Logs tab of the dashboard.

1. In the Vercel toolbar on your deployment, click (or search for) Tracing.
2. Select View Previous Session Traces.
3. The dashboard will open to the Logs tab, filtered to the session ID, and the tracing filter applied - indicated by the lightning icon in the filter bar.

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 lightning icon in the filter bar.

Zoom Image

With the tracing filter applied, you can view traces in the Logs tab of the dashboard.

Select a request from the list and click the Trace button at the bottom of the request details panel. This will open the traces for that request in an accordion and has the same functionality as viewing traces on the full page.

Zoom Image

1. In the Vercel toolbar on your deployment, click (or search for) Tracing.
2. Select Start Tracing Session.

Once enabled, the page reloads, and the toolbar turns blue, indicating the session trace is active.

You can then select any of the following options:

• View Page Trace: View the trace for the current page.
• View Session Traces: View all traced requests from your active session.
• Stop Tracing Session: Stop tracing the current session.
• Restart Tracing Session: Restart tracing the current session.

Selecting View Page Trace will open the trace for the current page in a new tab. This is the same as running a page trace.

While selecting View Session Traces will open the dashboard to the Logs tab, filtered to the session ID, and the tracing filter applied - indicated by the lightning icon in the filter bar.

To add custom spans to your traces, you can use the @opentelemetry/api package. This allows you to instrument your code and capture additional spans that are relevant to your application.

import { trace } from '@opentelemetry/api';
 
const tracer = trace.getTracer('custom-tracer');
 
async function performOperation() {
  const span = tracer.startSpan('operation-name');
  try {
    // Your operation logic here
    span.setAttributes({
      'custom.attribute': 'value',
    });
  } finally {
    span.end();
  }
}

See the OpenTelemetry documentation steps three and four for more details on how to use the @opentelemetry/api package.

• Learn about the Vercel toolbar
• Explore Observability on Vercel
• Learn about the Vercel OpenTelemetry integration