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.

referencestroubleshooting.md

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

Missing or incomplete traces

Use this reference when search is empty, retrieval fails, or expected span details are missing.

Search returns no spans

  1. Confirm vercel traces --help lists search. Distinguish authentication or API errors and rejected KQL from successful empty results.
  2. Check the selected team, project, environment, and query window. Search is team-wide unless --project is provided; retention may be shorter than accepted time bounds.
  3. Verify collection and traffic after it was enabled. For always-on tracing, check first-match rules, excluded paths, and the inbound sampling decision. For targeted capture, check that the request or session was captured.
  4. Check deployed instrumentation for framework and custom spans. Under Next.js 16.5+ default tracing, Vercel skips adding @vercel/otel, and framework spans go missing, when the project has an instrumentation file that doesn't call registerOTel, depends on @opentelemetry/api 1.10+ directly or through another package, or has an instrumentationInject entry. Incoming context and competing SDK providers can prevent collection; see propagation.
  5. Check the telemetry limits below and the search limits: search hides internal-kind spans from vercel.* services, which still appear in inspect. Custom spans from Edge runtime functions do not appear in traces.

Library or fetch spans are missing

  • A library emits no spans after registerOTel: most need an opt-in; see library spans.
  • Outbound fetch spans disappeared after adding instrumentations to registerOTel: the option replaces the default, so add 'auto' back to the list.
  • The build log reports Detected OpenTelemetry dependency, but no fetch spans appear: Vercel leaves fetch spans to the application when it finds @vercel/otel, @opentelemetry/api, or @opentelemetry/sdk-trace-node. Confirm that registerOTel runs in the deployed runtime, or remove the unused OpenTelemetry packages.

Inspect returns the wrong trace

When inspect <requestId> shows Endpoint: <unknown>, only a few spans, or custom spans as roots, find the request's own trace: run vercel traces search --request-id <id> --project <project> --json, take the .data.span.traceId of the GET <path> span, and inspect that trace ID. Two causes:

  • Startup spans share the request ID. Next.js emits register instrumentation and prepare route module as separate root traces.
  • The app does not extract incoming context, so each custom span starts its own trace and the request's trace has none. Enable tracing.server on SvelteKit, or follow context propagation for other frameworks.

Trace lookup returns 404

A searchable ID does not guarantee inspect can retrieve it; the CLI prints Trace not found (404) and exits 1. Request-ID lookup needs a matching root span in the same project within 30 minutes after the request-ID timestamp. Retry with the span's trace ID (.data.span.traceId in search JSON), which skips that request-ID resolution. Verify the ID, team, and the result's project. A missing root can cause 404; do not automatically attribute it to retention.

Oversized telemetry

inspect warns Trace is incomplete because it exceeded the span limit. when it returns a partial trace; treat its span tree and repeated-operation counts as incomplete. Spans over 1 MB compressed can have large attributes truncated; <attribute_name>.truncated: true identifies affected values. Spans still over 1 MB after truncation are dropped. Each traced request is limited to 10 MB compressed.

Inspect span attributes for truncation markers. Reduce large payload attributes in the instrumentation and deploy before reproducing; sampling changes do not fix oversized telemetry. See attribute truncation and trace limits.

For current retention and pricing, consult collection documentation rather than assuming the CLI's accepted window is retained.

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