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.

referencesinstrumentation.md

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

Application SDK setup

Use this reference when framework and custom spans are needed, or when SDK registrations conflict. Infrastructure and outbound-fetch spans need no application OpenTelemetry setup; see collection.

Check existing setup

Check framework and adapter versions, SDK registration, and tracing flags. Enable built-in framework spans where available; they still need SDK and exporter setup to reach Vercel, unless Next.js 16.5+ default tracing adds it. Extend the existing provider rather than registering a second one.

Install @vercel/otel and @opentelemetry/api with the application's package manager as needed. If the package manager does not install peer dependencies automatically, also install the peers listed by npm view @vercel/otel peerDependencies. Follow Next.js or SvelteKit setup for those frameworks.

Integrate another framework

  1. Identify the installed framework and adapter versions, target runtime, and how the affected route executes. Verify that the operation runs on the server for the requests being investigated; prerendered or cached responses may skip application code. Custom spans require a supported runtime.
  2. Find the framework's native tracing flags and documented server startup, preload, or initialization hook. Use version-appropriate official docs; inspect adapter source when the integration is unclear. Record which entrypoint loads initialization and when it runs. A special filename alone does not prove it is loaded.
  3. Wire one server-only SDK setup module, such as the one below, into that verified hook. Initialize automatic instrumentations before loading the libraries they instrument. See OpenTelemetry initialization order.
  4. Check whether the framework already establishes incoming trace context. When it does not, map its request headers and handler or middleware continuation to context propagation. Preserve existing middleware and configuration.
  5. Build and verify the expected spans using the checks below. If no supported initialization path can be established, report the missing integration and source evidence before proceeding.

For a new SDK setup, a module such as telemetry.ts can contain:

import { registerOTel } from '@vercel/otel';

registerOTel({ serviceName: 'checkout' });

Import it from the verified server entrypoint or hook, adapting the relative path:

import './telemetry';

This import must execute in the deployed server runtime and register once per runtime instance. Keep it out of client bundles, using the framework's server-only file convention when it has one. See Vercel instrumentation.

Some adapters supply a default server entry when the project has none. Before creating that file to add the import, start from the adapter's documented template for Vercel so streaming and response handling keep working; a generic framework template can differ. If the file exists, add only the import line.

Without native framework spans, a slow loader or handler appears as one long function span; add custom spans around its operations.

Coexist with Sentry

Sentry v8+ initializes OpenTelemetry automatically, which can conflict with @vercel/otel. Decide which integration owns setup before changing it. When Vercel owns OpenTelemetry setup, merge skipOpenTelemetrySetup: true into the existing Sentry initialization:

import * as Sentry from '@sentry/node';

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  skipOpenTelemetrySetup: true,
});

Use the application's existing Sentry package and preserve its other options. If Sentry tracing must also use the shared provider, follow Sentry's custom OpenTelemetry integration; disabling its automatic setup alone does not implement that integration. See Vercel's Sentry guidance.

Deploy and verify

  1. Run the application's framework or adapter build and available type checks. A prompt to install a checker is not a completed check. When startup loading is uncertain, inspect emitted server output to confirm the setup module executes before the instrumented operation.
  2. Verify the expected operation's span. Use native framework spans where available, or add a small custom span. An isolated local exporter check can verify SDK initialization and parent context; it does not prove Vercel collection.
  3. Deploy to preview or production and choose a collection mode. Exercise a server-executed operation, then inspect its collected trace in the same project and environment. Confirm the span's name, service, timing, and parent relationships; verify error status when reproducing a failure.

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