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 @vercel/otel package.

To get started, install the following packages:

pnpm i @opentelemetry/api @vercel/otel

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

import { registerOTel } from '@vercel/otel';
 
export function register() {
  registerOTel({ serviceName: 'your-project-name' });
}
// NOTE: You can replace `your-project-name` with the actual name of your project

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 traceparent. 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 fetch option in the instrumentationConfig option.

import { registerOTel } from '@vercel/otel';
 
export function register() {
  registerOTel({
    serviceName: `your-project-name`,
    instrumentationConfig: {
      fetch: {
        // This URLs will have the tracing context propagated to them.
        propagateContextUrls: [
          'your-service-domain.com',
          'your-database-domain.com',
        ],
        // This URLs will not have the tracing context propagated to them.
        dontPropagateContextUrls: [
          'some-third-party-service-domain.com',
        ],
        // This URLs will be ignored and will not be traced.
        ignoreUrls: ['my-internal-private-tool.com'],
      },
    },
  });
}
// NOTE: You can replace `your-project-name` with the actual name of your project

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.

import { propagation, context, trace } from "@opentelemetry/api";
 
const tracer = trace.getTracer('custom-tracer');
 
// This function injects the inbound context into the request handler
function injectInboundContext(f: (request: Request) => Promise<Response>): (request: Request) => Promise<Response> {
  return (req) => {
    const c = propagation.extract(context.active(), Object.fromEntries(req.headers))
    return context.with(c, async () => {
      return await f(req);
    })
  }
}
 
export const GET = injectInboundContext(async (req: Request) => {
  const span = tracer.startSpan('your-operation-name');
  // The above ^ span will be automatically attached to incoming tracing context (if any)
  try {
    // Your operation logic here
    span.setAttributes({
      'custom.attribute': 'value',
    });
    return new Response('Hello, world!');
  } finally {
    span.end();
  }
});

After installing @vercel/otel, 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 @opentelemetry/api package to instrument specific operations:

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();
  }
}

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 @vercel/otel, you will not be able to use Session Tracing or Trace Drains.