使用方法
- 复制安装命令,在自己的智能体环境安装前先检查源码包。
- 从原始文档核对所需工具、凭据和支持的宿主。
- 说明输入材料与期望交付物,并对照来源检查输出。
npx skills add https://github.com/vercel/vercel-plugin --skill vercel-tracing开始前需了解
- 安装不包含模型订阅、API 额度或访问文件的权限。
- 仓库星数和安装量反映活跃情况,不等于独立质量或安全测试。
按源仓库内容呈现,保留标题、案例、代码、表格、链接以及原文引用的演示图片。
Vercel Tracing
Use Vercel Tracing to instrument server code with OpenTelemetry and inspect spans from deployed traffic. The workflow is register `@vercel/otel` from the framework's server startup hook → deploy and exercise a server route → search and inspect the trace with `vercel traces`. Use the same traces to debug failed requests and measure slow operations. Read only the references needed for the current task.
Tracing only covers server code: requests to dynamic routes, API routes, functions, and on-demand rendering, and daemons (Public Beta, production only) that export spans to the Unix socket at VERCEL_OTEL_SOCKET_PATH. In a Node.js daemon, call registerOTel from @vercel/otel 2.3.0+ at the top of the worker's entry file; in other languages, point an OpenTelemetry exporter that supports Unix sockets (OTLP/HTTP, not gRPC) at that path. Setting OTEL_EXPORTER_OTLP_TRACES_ENDPOINT or OTEL_EXPORTER_OTLP_ENDPOINT, or passing a custom traceExporter to registerOTel, bypasses the socket. Find daemon spans by the serviceName the daemon registers, with vercel traces search --project <project> --service <serviceName>. Static and prerendered pages and CDN cache hits run no application code, so traces cannot explain or speed them up; optimize those with caching, bundle size, and Core Web Vitals work instead.
Reference index
| Reference | Read when |
|---|---|
| Collection | Deciding which spans need application setup, or choosing always-on tracing, request capture, or a browser session |
| Instrumentation | Discovering a framework's startup hook, wiring and verifying SDK setup, or using Sentry |
| Next.js | Checking Next.js 16.5+ default tracing, setting up Next.js instrumentation, or enabling verbose spans |
| SvelteKit | Enabling server tracing and the instrumentation hook on SvelteKit 2 or 3 |
| Library spans | Turning on spans from the AI SDK, Flags SDK, Workflow, or database and cache clients |
| Custom spans | Measuring an application operation and recording failures |
| Context propagation | Connecting traces across services: outbound URL matching, non-fetch clients and queues, incoming requests |
| Configuration | Inspecting or changing always-on tracing sampling rules |
| Capture | Reproducing a request or tracing a browser flow |
| Search | Finding slow or failed spans, choosing filters, or parsing results |
| Inspection | Retrieving a request trace and choosing timeline, tree, or waterfall |
| Performance | Making a route, API, function, or server-rendered page faster: wrapping operations in custom spans, reading exact durations, comparing before and after |
| Troubleshooting | Investigating empty results, failed lookups, missing spans, or truncated attributes |
Setup workflow
- Check existing setup: framework and adapter versions, any registered OpenTelemetry provider or Sentry v8+, and framework tracing flags. Extend an existing provider; never register a second one.
- Decide what needs application setup. Infrastructure and outbound-fetch spans are automatic; framework, library, and custom spans need
@vercel/otel. On Next.js 16.5+, check default tracing first. When Vercel adds@vercel/otel, framework spans need no setup, and step 3 is only for custom or library spans. See collection. - Install
@vercel/oteland@opentelemetry/api, then register the SDK once from the framework's verified server startup hook. On Next.js, that isregister()ininstrumentation.ts:
import { registerOTel } from '@vercel/otel';
export function register() {
registerOTel({ serviceName: process.env.VERCEL_PROJECT_NAME });
}Under default tracing, Vercel stops adding @vercel/otel once this file exists, and VERCEL_PROJECT_NAME keeps the service name unchanged. For other frameworks, follow SvelteKit or another framework; see Next.js for default tracing, verbose spans, and prerendering. Next.js and SvelteKit join the incoming request trace automatically; other frameworks may need incoming-context extraction. Add custom spans and context propagation where needed.
- Turn on library spans for the libraries in the application's
package.json, such as the AI SDK, the Flags SDK, or a database client. - Build, deploy to preview or production, exercise a server-executed route, and inspect its trace. Confirm span names and parent relationships with
inspect, andservice.namewith search JSON. A local exporter check does not prove Vercel collection.
Investigation workflow
Investigate errors and improve application performance with traces. Measure before optimizing: don't claim a speedup until deployed spans confirm it.
When the cause looks obvious in the code, such as sequential awaits, still measure. Add spans around the suspected operations in the same change as the fix, or in a baseline deploy first when one is possible. Report the expected gain as an estimate until deployed traces confirm it, and name the spans the user should compare. Code reading finds candidates; it does not show which one dominates on Vercel, where database location, cold starts, and external APIs change the cost.
- Confirm the slow or failing route runs server code on each request; a static, prerendered, or cached response has no application spans. Verify preview or production deployment, collection mode, and traffic. Check application OpenTelemetry setup for framework and custom spans and sampling rules for always-on tracing. Reuse completed setup, and turn on library spans from the
vercel-tracingskill for installed libraries that are missing them. - Find slow or failed requests for the affected project, route, environment, and time window, or capture a reproduction.
- Wrap each suspected operation (database queries, external calls, cache reads, rendering, CPU-heavy work) in a custom span with
startActiveSpan, deploy, and read exact durations from traces. Save these as the baseline. - Inspect traces to locate failed operations, the slowest span on the critical path, sequential waits, and unmeasured gaps between a parent and its children; relate them to application code. Add spans to any gap and measure again.
- Change the measured cause, keeping its span. After deploying, compare that span and the whole request across equivalent requests under similar load and collection settings. Report before and after timings, sample counts, errors, and remaining uncertainty.
A limited span search is not a complete latency distribution. Use browser profiling alongside traces for rendering or interaction bottlenecks.
CLI scope
Confirm that vercel traces --help lists the subcommand needed. vc and vercel are equivalent.
The CLI runs with --non-interactive by default when it detects an agent and stdin is not a TTY. In that mode search and config print JSON, search --columns is rejected, production capture needs --yes, and config rm returns the command for the user to run instead of prompting.
Search covers all projects in the selected team, even from a linked directory. Use --scope for the team and --project for one application's search. inspect and config remain project-scoped; after a team search, use the result's project for retrieval.
Do not change sampling merely to investigate an issue. Empty sampled results do not prove a request never happened; distinguish authentication or API failures from successful empty searches.