Index of every page on this site: llms.txt
All skills
vercel avatar

/vercel-tracing

@250769d official
by vercelvercel/vercel-plugin340 stars
82
Run it yourself

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, turning on spans from libraries such as the AI SDK, Flags SDK, or database clients, propagating trace context between services, configuring always-on tracing sampling, searching or inspecting spans with `vercel traces`, or debugging failed or slow server requests.

Use this Skill: https://skilld.dev/gh/vercel/vercel-plugin/vercel-tracing

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

referencesperformance.md

≈1.4k tokens on demand. Your agent reads this file only when SKILL.md points to it.

Measure and improve performance with custom spans

Use this reference when a user wants to make a server route, API, function, or server-rendered page faster. Measure first: wrap each suspected operation in a custom span, deploy, read exact durations from traces, change the slowest operation on the critical path, then measure again. Do not optimize from intuition or from total request time alone.

This only works for routes that run server code on each request. Static and prerendered pages and CDN cache hits produce no server spans, so tracing cannot speed them up. Browser rendering, bundle size, and Core Web Vitals need browser profiling, not server spans.

1. Pick the request and list its operations

  1. Identify the slow route or function, its environment, and an example input. Find recent slow requests with search when collection is already on:

    vercel traces search --scope my-team --project my-app --environment production --query 'span.duration > 1000' --kind server --since 1h --json
  2. Read the handler and list each awaited operation that could cost time: database queries, external API calls, cache reads, file or blob I/O, rendering, serialization, and CPU-heavy loops. Note which run sequentially and which run in parallel.

  3. Check what is already measured. Automatic outbound-fetch spans time the function's outbound HTTP requests; Next.js emits route and render spans once instrumented. Turn on library spans for installed libraries that are missing them, such as AI SDK calls or database queries. Add custom spans only for operations that are not already visible.

2. Wrap each operation in a span

Add the measure helper from custom spans, then wrap the operations in the existing handler, keeping their order and concurrency:

import { measure } from './lib/measure';

const user = await measure('checkout.load-user', { 'user.id': userId }, () => getUser(userId));
const [cart, prices] = await Promise.all([
  measure('checkout.load-cart', { 'cart.id': cartId }, () => getCart(cartId)),
  measure('checkout.fetch-prices', { 'price.count': skus.length }, () => fetchPrices(skus)),
]);
const order = await measure('checkout.create-order', {}, () => createOrder(user, cart, prices));

Adapt names and calls to the application, following the naming and attribute rules in custom spans. For measurement:

  • Add attributes that explain cost, such as row counts, payload bytes, or item counts.
  • Wrap operations, not tight inner loops; time the whole loop once instead.

3. Collect durations from deployed traffic

Local timing does not reflect Vercel regions, cold starts, or network distance. Deploy to preview, or production when authorized, then capture requests:

vercel traces create /api/checkout --deployment https://my-app-abc123.vercel.app --scope my-team --json

Repeat the capture several times with the same input to see variance, or let always-on tracing gather real traffic. Then read the measured spans. span.duration is in milliseconds:

vercel traces search --scope my-team --project my-app --query 'span.name:checkout.*' --since 1h --limit 500 --json \
  | jq -r 'select(.type == "span") | [.data.span.name, .data.span.duration] | @tsv'

The final summary line reports pagination.hasMore; when it is true, continue with --next before treating the durations as complete. See search.

For one request, start with the default summary:

vercel traces inspect 0870e4ead46aafba39ccfbcb001835db --scope my-team --project my-app

To sort every span by duration, use --json, which reports durations as [seconds, nanoseconds]:

vercel traces inspect 0870e4ead46aafba39ccfbcb001835db --scope my-team --project my-app --json 2>/dev/null \
  | jq -r '.spans[] | [((.duration[0] * 1000) + (.duration[1] / 1e6)), .name] | @tsv' | sort -rn

To see which spans are sequential, add --open --view=waterfall; see inspection.

4. Find the operation to change

  • Fix the critical path. A slow span that overlaps a slower one does not shorten the request.
  • Compare each span with its parent. A large gap between the parent's duration and its children means unmeasured work: add another span there and measure again before changing code.
  • Look for these common causes: sequential awaits that could run in parallel, the same query or fetch repeated per item (N+1), uncached repeated calls, large payloads, and cold connections to a database or API.
  • Write down a baseline for each key span from equivalent requests: route, input, environment, and request count. A few samples are not a full latency distribution; say how many you used.

5. Change one thing and compare

Change the slowest operation on the critical path, keep its span in place, deploy, and capture equivalent requests with the same input and collection settings. Report before and after durations for that span and for the whole request, the sample counts, and any errors. If the fix ships before deployed numbers exist, name the spans to compare and the expected result, for example "checkout.handler should drop from about the sum of the three child spans to about the longest one." If the time moved to another span instead of disappearing, say so.

Keep spans that will be useful later. Remove only noisy, temporary spans after the investigation.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 alert4d3 checks · Risk SAFE
  • Gen Agent Trust Hub4d

    This skill provides tools for instrumenting and debugging Vercel applications using OpenTelemetry. It involves installing official instrumentation packages and using the Vercel CLI to search and inspect traces. While these operations involve external dependencies and network queries, they are standard for observability tasks. The skill also includes specific guidance on avoiding the recording of sensitive data.

  • Socket4d

    No alerts

  • Snyk4d

    Risk: CRITICAL · 2 issues

Signed by skilld at 250769d. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 5 days ago
Other metadata
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/configure-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",
      "registertelemetry",
      "experimental_telemetry",
      "settracerprovider",
      "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"
      ],
      [
        "ai sdk",
        "spans"
      ],
      [
        "ai sdk",
        "telemetry"
      ],
      [
        "ai sdk",
        "tracing"
      ],
      [
        "flags sdk",
        "spans"
      ],
      [
        "flags sdk",
        "tracing"
      ],
      [
        "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",
    "turn on spans from the AI SDK, Flags SDK, or database clients",
    "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"
  ]
}

README badge

README badge for vercel/vercel-plugin/vercel-tracing