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.

referencescontext-propagation.md

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

Context propagation

Use this reference when related operations appear in disconnected traces or beneath an unexpected parent. Propagation needs both sides: the caller injects traceparent into the outgoing request, and the receiver extracts it. If either side is missing, each service produces its own trace.

Outgoing requests

@vercel/otel instruments global fetch and Node's http/https modules, so libraries built on them, such as axios on Node, are covered too. By default it sends context only to the deployment's own host (VERCEL_URL, VERCEL_BRANCH_URL, or the incoming request's host). Calls to another Vercel project, any other domain, or an external service need an explicit allow rule.

Merge fetch settings into the existing registerOTel call, using the application's actual destinations:

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

registerOTel({
  serviceName: 'checkout',
  instrumentationConfig: {
    fetch: {
      propagateContextUrls: ['https://api.example.com/', /^https:\/\/[a-z0-9-]+\.example\.com\//],
      dontPropagateContextUrls: ['https://api.example.com/public/'],
      ignoreUrls: ['https://health.example.com/'],
    },
  },
});

String matchers are prefixes of the full URL, including the scheme. 'api.example.com' never matches https://api.example.com/orders, so headers are silently not sent. Use a full origin such as 'https://api.example.com/' or a regular expression. Use '*' only when every destination is trusted.

  • propagateContextUrls sends context headers to matching URLs.
  • dontPropagateContextUrls blocks headers and wins over propagateContextUrls; the call is still traced.
  • ignoreUrls skips tracing the call entirely.

To override one call, pass fetch(url, { opentelemetry: { propagateContext: true } }). Next.js needs version 14.1.1 or later for this option. See the @vercel/otel options.

Avoid sending traceparent to third parties that do not need it; it exposes trace IDs and can make their tracing join yours.

Clients and transports that are not instrumented

Inject the context manually for clients that do not use fetch or node:http, such as gRPC, WebSocket messages, queue messages (including Vercel Queues), and workflow steps:

import { context, propagation } from '@opentelemetry/api';

const carrier: Record<string, string> = {};
propagation.inject(context.active(), carrier);
await queue.send({ payload, trace: carrier });

Adapt queue.send to the actual client. Put the carrier where the transport carries metadata: message attributes, gRPC metadata, or a field in the payload. Inject while the active span is the one that should become the parent. The consumer extracts the carrier with propagation.extract and runs its work inside context.with, as shown below.

Incoming requests

Next.js 14.0.1+ and SvelteKit with tracing.server enabled extract incoming context automatically. Prefer the framework's tracing integration when it already does this. Otherwise, extract the headers and run the existing handler inside that context:

import { context, propagation } from '@opentelemetry/api';
import { handleCheckout } from './checkout-handler';

export function handleRequest(request: Request): Promise<Response> {
  const parent = propagation.extract(
    context.active(),
    Object.fromEntries(request.headers),
  );
  return context.with(parent, () => handleCheckout(request));
}

Adapt the handler and the header carrier to the framework; not every framework exposes a Web Headers object. For middleware, call the framework's next() or equivalent inside the context.with callback, keeping awaited work and the existing middleware chain inside it, so later handlers and their spans inherit the extracted parent.

Sampling across services

When a request arrives with traceparent, Vercel combines the inbound decision with its own sampling rules. An unsampled parent drops the trace. A sampled parent is still dropped unless a Vercel rule also samples the request. Both services need matching collection rules for a connected trace. Manual SDK setup without @vercel/otel lacks session tracing and Trace Drains support. See Vercel sampling behavior.

Verify

Deploy both services, send one request through the caller, and inspect it with inspection. The receiver's server span should share the caller's trace ID and sit under the caller's outbound span. If it starts a new trace, check the URL matcher first, then that the receiver extracts the context.

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