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.

referenceslibrary-spans.md

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

Library spans

Use this reference when the application depends on libraries that can emit their own spans, such as the AI SDK, the Flags SDK, Workflow, or database clients. Library spans reach Vercel through the provider that registerOTel registers; complete SDK setup first.

Check dependencies

Match dependencies in the application's package.json, or in each server app's package.json in a monorepo, against this table, and apply the row for each match. Registering @vercel/otel is enough only for the first two rows; the others emit no spans until they are turned on.

Library After registerOTel alone Turn on
Workflow (workflow) Workflow runtime spans Nothing to add; WORKFLOW_TRACE_MODE only changes how step traces link
SDKs that call HTTP APIs (OpenAI, Stripe, Upstash, Supabase) Outbound HTTP spans Nothing to add; they have no spans of their own
AI SDK 7 (ai) No AI SDK spans registerTelemetry(new OpenTelemetry()) from @ai-sdk/otel
AI SDK 6 and earlier No AI SDK spans experimental_telemetry: { isEnabled: true } on each call
Flags SDK (flags) on Next.js No flag spans setTracerProvider(trace)
Database and cache clients (pg, mysql2, ioredis, mongodb, Prisma) No query spans An OpenTelemetry instrumentation package; Prisma 4.2 to 6.0 also needs previewFeatures = ["tracing"] in schema.prisma

For other installed server libraries, check their docs or published dist for a telemetry option, a tracer setter, or an instrumentation package, and turn on any that exist. A dependency on @opentelemetry/api does not prove the library emits spans by default.

Report which library spans were turned on and which installed libraries have none.

Turn on built-in spans

When ai 7 is installed, install @ai-sdk/otel. Call each opt-in once in the same startup hook, after registerOTel. On Next.js, with both the AI SDK and the Flags SDK installed:

import { trace } from '@opentelemetry/api';
import { OpenTelemetry } from '@ai-sdk/otel';
import { registerOTel } from '@vercel/otel';
import { registerTelemetry } from 'ai';
import { setTracerProvider } from 'flags';

export function register() {
  registerOTel({ serviceName: process.env.VERCEL_PROJECT_NAME });
  registerTelemetry(new OpenTelemetry());
  setTracerProvider(trace);
}

AI SDK 7 then traces every call; pass telemetry: { functionId: 'checkout-assistant' } to name a call, or telemetry: { isEnabled: false } to skip one.

Add instrumentation packages

When a database or cache client is installed, install its instrumentation package: @opentelemetry/instrumentation-<client> for pg, mysql2, ioredis, and mongodb, or @prisma/instrumentation for Prisma. Pick the release whose @opentelemetry/instrumentation dependency fits the range in npm view @vercel/otel peerDependencies; the latest release can need a newer OpenTelemetry API than @vercel/otel supports and fail next build. Check a release with npm view @opentelemetry/instrumentation-pg@<version> dependencies. Pass it to registerOTel and keep 'auto' in the list; the option replaces the default, so a list without 'auto' or 'fetch' drops outbound fetch spans:

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

export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    const { PgInstrumentation } = await import('@opentelemetry/instrumentation-pg');
    registerOTel({ serviceName: process.env.VERCEL_PROJECT_NAME, instrumentations: ['auto', new PgInstrumentation()] });
  } else {
    registerOTel({ serviceName: process.env.VERCEL_PROJECT_NAME });
  }
}

These packages run only in the Node.js runtime, and they patch a library when it loads, so the library must not be bundled. Next.js leaves pg, mongodb, mongoose, and @prisma/client unbundled by default; add other clients, such as ioredis and mysql2, to serverExternalPackages in next.config.

Verify after deployment

Deploy, exercise a route that calls the library, and inspect its trace. Confirm the library's spans appear beneath the request and that outbound fetch spans are still present.

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