/vercel-tracing

name: vercel-tracing
description: Set up OpenTelemetry instrumentation for Vercel Tracing and query the resulting spans. Use when adding or fixing `@vercel/otel`, wiring a framework's server startup hook (Next.js, SvelteKit, and others), adding custom spans, propagating trace context between services, configuring always-on tracing sampling, searching or inspecting spans with `vercel traces`, or debugging failed or slow server requests.
summary: Instrument server code with @vercel/otel, then debug and optimize requests with vercel traces
metadata:
  priority: 8
  docs:
    - "https://vercel.com/docs/tracing"
    - "https://vercel.com/docs/tracing/always-on-tracing"
    - "https://vercel.com/docs/tracing/session-tracing"
    - "https://vercel.com/docs/cli/traces"
    - "https://vercel.com/docs/tracing/instrumentation"
  sitemap: "https://vercel.com/sitemap/docs.xml"
  pathPatterns: []
  bashPatterns:
    - '\b(?:vercel|vc)\s+traces\b'
    - '\b(?:vercel|vc)\s+curl\b[^\n]*--trace\b'
  importPatterns:
    - '@vercel/otel'
    - '@opentelemetry/api'
  promptSignals:
    phrases:
      - "vercel traces"
      - "vc traces"
      - "@vercel/otel"
      - "registerotel"
      - "instrumentation hook"
      - "opentelemetry"
      - "open telemetry"
      - "enable tracing"
      - "set up tracing"
      - "add tracing"
      - "distributed tracing"
      - "always-on tracing"
      - "session tracing"
      - "trace sampling"
      - "sampling rule"
      - "context propagation"
      - "traceparent"
      - "custom span"
      - "measure how long"
      - "ttfb"
      - "time to first byte"
      - "high latency"
      - "reduce latency"
      - "performance regression"
      - "failed requests"
      - "production errors"
    allOf:
      - [vercel, tracing]
      - [vercel, traces]
      - [vercel, spans]
      - [vercel, instrument]
      - [otel, instrument]
      - [sentry, otel]
      - [sveltekit, otel]
      - [always, tracing]
      - [traces, disconnected]
      - [api, slow]
      - [endpoint, slow]
      - [route, slow]
      - [function, slow]
      - [page, slow]
      - [request, slow]
      - [query, slow]
      - [database, slow]
      - [loader, slow]
      - [action, slow]
      - [server, slow]
      - [app is, slow]
      - [app feels, slow]
      - [app got, slow]
      - [app loads, slow]
      - [take, seconds, route]
      - [take, seconds, endpoint]
      - [take, seconds, api]
      - [take, seconds, page]
      - [take, seconds, dashboard]
      - [take, seconds, request]
      - [take, seconds, loader]
      - [take, seconds, query]
      - [take, seconds, server]
      - [p95, latency]
      - [slow, since, deploy]
      - [slower, since, deploy]
      - [sluggish, deploy]
      - [performance, degraded]
      - [performance, api]
      - [performance, endpoint]
      - [performance, route]
      - [performance, server]
      - [performance, function]
      - [speed up, api]
      - [speed up, route]
    noneOf:
      - "the build"
      - "my build"
      - "slow build"
      - "build time"
      - "build takes"
      - "to build"
      - "vercel deploy"
      - "deploy is slow"
      - "deploys are slow"
      - "deployments are slow"
      - "deploy takes"
      - "ci pipeline"
      - "github actions"
      - "test suite"
      - "dev server"
      - "hmr"
      - "hot reload"
      - "re-render"
      - "re-renders"
      - "spinner"
      - "animation"
      - "scroll"
      - "scrolling"
      - "interaction"
      - "file tracing"
      - "bundle size"
      - "lcp"
      - "core web vitals"
      - "lighthouse"
    minScore: 4
retrieval:
  aliases:
    - Vercel Tracing
    - always-on tracing
    - vc traces
    - Vercel OpenTelemetry
  intents:
    - set up OpenTelemetry for a Vercel project
    - wire @vercel/otel into a framework's server startup hook
    - add custom spans around application operations
    - connect disconnected traces across services
    - configure trace sampling
    - verify instrumentation by inspecting a collected trace
    - debug failed requests or production errors using traces
    - make a slow API route or server function faster
  entities:
    - "@vercel/otel"
    - "@opentelemetry/api"
    - vercel traces search
    - vercel traces inspect
    - vercel traces config
    - vercel traces create
    - vercel curl --trace
  examples:
    - add OpenTelemetry to my app deployed on Vercel
    - set up @vercel/otel in my SvelteKit app
    - propagate trace context to my backend API
    - debug production errors in my Vercel app
    - this endpoint is slow, make it faster

Vercel Tracing

Use Vercel Tracing to instrument server code with OpenTelemetry and inspect spans from deployed traffic. The workflow is **register `@vercel/otel` from the framework's server startup hook → deploy and exercise a server route → search and inspect the trace with `vercel traces`**. Use the same traces to debug failed requests and measure slow operations. Read only the references needed for the current task.

Tracing only covers requests that run server code: dynamic routes, API routes, functions, and on-demand rendering. Static and prerendered pages and CDN cache hits run no application code, so traces cannot explain or speed them up; optimize those with caching, bundle size, and Core Web Vitals work instead.

Reference index

| Reference | Read when | | --- | --- | | [Collection](references/collection.md) | Deciding which spans need application setup, or choosing always-on tracing, request capture, or a browser session | | [Instrumentation](references/instrumentation.md) | Discovering a framework's startup hook, wiring and verifying SDK setup, or using Sentry | | [Next.js](references/nextjs.md) | Setting up Next.js instrumentation or enabling verbose spans | | [SvelteKit](references/sveltekit.md) | Enabling server tracing and the instrumentation hook on SvelteKit 2 or 3 | | [Custom spans](references/custom-spans.md) | Measuring an applic