vercel traces

The vercel traces command lets you search spans, inspect request traces, capture session traces, and manage trace sampling rules for a project.

For more information about tracing, see the Tracing documentation.

The vercel traces command supports the following operations:

• search - Search project spans
• get - Fetch a captured trace by request ID
• create - Capture a session trace for a request
• config - Manage trace sampling rules

vercel traces search returns up to 100 spans from one project, or up to 1,000 with --limit. By default, it searches the last hour and lists the newest spans first.

vercel traces search

Options:

• --project <name-or-id>, -p: Project name or ID, defaulting to the linked project
• --environment <environment>: Filter by production or preview, case-insensitive
• --service <name>: Filter by service name
• --name <name>: Filter by span name
• --kind <kind>: Filter by span kind name, case-insensitive, or its numeric value. See Span kinds
• --status <status>: Filter by error, ok, or unset, case-insensitive
• --deployment-id <id>: Filter by deployment ID
• --request-id <id>: Filter by request ID
• --trace-id <id>: Filter by trace ID
• --span-id <id>: Filter by span ID
• --root: Filter root spans only
• --since <time>: Start time. Defaults to one hour ago
• --until <time>: End time. Defaults to now
• --limit <number>, -n: Maximum spans to return, from 1 to 1,000. Defaults to 100
• --query <kql>, -q: Filter spans using a KQL field expression
• --columns <list>: Comma-separated column keys in display order. Cannot be combined with --json
• --json, -j: Output one span per line as JSON Lines

The command combines all filters, including --root and --query, with AND. Search accepts no positional arguments.

Examples:

# Find error spans from the last hour
vercel traces search --status error --since 1h
 
# Find production spans for one service
vercel traces search --environment production --service checkout-api
 
# Find every span in one trace
vercel traces search --trace-id 4bf92f3577b34da6a3ce929d0e0e4736
 
# Find one span in that trace
vercel traces search --trace-id 4bf92f3577b34da6a3ce929d0e0e4736 --span-id 00f067aa0ba902b7
 
# Find root spans
vercel traces search --root
 
# Search a specific team and project
vercel traces search --scope my-team --project my-app

Both --since and --until accept relative durations such as 30m, 4h, or 7d, ISO 8601 timestamps, or YYYY-MM-DD dates. Relative durations count backward from the current time. Date-only values mean midnight UTC, including for --until.

Search a one-hour window ending 30 minutes ago:

vercel traces search --since 90m --until 30m

The start must be before the end. Your plan determines how far back you can search. See trace retention.

Use field expressions in --query. Bare text search is unsupported. For example, find spans longer than two seconds and choose the table columns:

vercel traces search --query 'span.duration > 2000' --columns span.startTime,span.duration,span.name,span.kind,span.status.code

Results remain newest first. Search does not support sorting spans by duration.

Use NOT to exclude matches and a trailing * to match a prefix. Double-quote names containing spaces inside the shell-quoted query:

vercel traces search --query 'NOT span.name:app/lib/fetch-api*'
vercel traces search --query 'NOT span.name:("GET /screenshot/v2" OR "middleware GET")'

You can filter by these fields:

Other field names search span attributes and resource attributes.

Unquoted numbers use numeric comparison, and unquoted true or false match boolean values. Double-quoted values use string comparison. The :* expression checks whether an attribute key exists.

--kind accepts a name or its OpenTelemetry Protocol numeric value. Inside --query, use the numeric value:

vercel traces search --kind server
vercel traces search --query 'span.kind:(2 OR 3)'

The default table includes span.startTime, span.duration, span.name, span.status.code, service.name, trace.id, span.id, and parent.id, in that order. It excludes environment, request.id, and span.kind; add any of them with --columns, or select a smaller set:

vercel traces search --columns span.startTime,span.duration,span.name,span.kind,span.status.code

The environment column shows the deployment environment. Missing values display -.

Column names are case-sensitive and cannot repeat. Use only the keys listed above. Shorthand keys such as time, duration, and kind are rejected. Table timestamps use UTC. The table shortens long span names and removes routing-region prefixes from request IDs. JSON Lines keeps the full values.

--json writes one JSON object per span, with no enclosing array or response wrapper. Each object has span and resource fields. Span data is under .span, including .span.traceId, .span.duration, and .span.attributes. Events and links appear as .span.events and .span.links when present. Resource attributes are under .resource.attributes.

vercel traces search --status error --limit 500 --json > spans.jsonl

When no spans match, table output prints No spans found for this period. and JSON Lines output is empty. Both exit successfully. When more spans match than the limit, the command prints a notice to stderr. Narrow the query or increase --limit, up to 1,000. Search does not support cursor pagination.

Fetch a captured trace by request ID. The command prints a summary in the terminal by default.

vercel traces get req_1234567890

get is the default subcommand, so vercel traces req_1234567890 returns the same trace.

Options:

• --project <name-or-id>: Project name or ID, defaulting to the linked project
• --json: Output the raw trace as JSON instead of a terminal summary
• --open: Open the trace in the Vercel Dashboard instead of printing it
• --view <view>: Dashboard view to open. Accepts timeline, tree, or waterfall, and requires --open. Defaults to timeline

--open cannot be combined with --json.

Examples:

# Fetch a trace from a specific team and project
vercel traces get req_1234567890 --scope my-team --project my-app
 
# Open a trace in the dashboard tree view
vercel traces get req_1234567890 --open --view tree
 
# Output the raw trace as JSON
vercel traces get req_1234567890 --json

A request ID in search results does not guarantee that get can retrieve the trace. Lookup requires a matching root span in the same project within 30 minutes after the request ID timestamp. If no matching root span exists, get returns 404. Use the same --scope and --project values for search and get.

Send a request and capture its session trace. vercel traces create is an alias for vercel curl --trace.

vercel traces create /api/hello

Options:

• --deployment <id-or-url>: Deployment ID or URL to target
• --protection-bypass <secret>: Protection bypass secret for a protected deployment
• --json: Output the response and request ID as JSON
• --yes, -y: Skip the production confirmation prompt

Pass curl flags after --.

Examples:

# Target a specific deployment
vercel traces create /api/status --deployment https://your-project-abc123.vercel.app
 
# Send a POST request with a JSON body
vercel traces create /api/test -- --request POST --data '{"name": "John"}'

Sampling rules decide which requests always-on tracing collects a trace for. Each rule pairs an environment and an optional path prefix with a rate, and a project holds at most 10 rules.

The vercel traces config subcommands read and write those rules for the linked project, or for the project you name with --project. Changing rules requires a role with project update access. Running vercel traces config with no subcommand prints help.

The vercel traces config command supports the following operations:

• config ls - List every rule on the project
• config set - Add a rule or change the rate of an existing rule
• config rm - Remove one rule or every rule for an environment

Two details differ from the dashboard:

• The dashboard Rate field accepts 0, but the CLI accepts whole percentages from 1 to 100 and rejects both 0 and fractions such as 2.5. To add a 0% rule that matches requests and collects nothing, use the dashboard.
• The dashboard calls a rule that covers every environment All Environments. On the command line, that environment is any.

Vercel uses the first matching rule shown by ls. set adds new rules to the bottom, so an earlier broad rule can override a later narrow rule. The CLI cannot reorder rules. To change the order, remove the rules and add them back in the order you want. See Sampling for overlap behavior.

Alias: config list.

List the trace sampling rules for a project.

vercel traces config ls

The command prints one row per rule, along with the count against the 10-rule limit:

> Trace sampling rules for my-app (3 of 10 rules)

  environment  path         rate
  any          (all paths)  1%
  preview      /api         100%
  production   /api         25%

A project with no rules collects no traces. In that case, ls says so, names the command that adds a rule, and exits successfully.

Options:

• --json: Output the rules as JSON
• --project <name-or-id>: Project name or ID, defaulting to the linked project

Add a trace sampling rule or change the rate of an existing rule.

vercel traces config set <environment> <rate> [requestPath]

A rule is identified by its environment and path prefix together. Running set again with the same pair changes that rule's rate instead of adding a second rule, so changing a rate takes one command. Because the pair includes the environment, any /api and production /api are two separate rules.

set never prompts. Its success message prints the rate the rule held before, so you can put the old value back with one more set:

> Success! Set production /api to 75% (was 10%). 3 of 10 rules.

Set a rate for every path in an environment by leaving the path prefix off:

Examples:

# Trace a quarter of production traffic
vercel traces config set production 25
 
# Trace every preview request to one path prefix
vercel traces config set preview 100 /api
 
# Trace 1% of traffic in every environment
vercel traces config set any 1

When the project already holds 10 rules, set refuses the write before it changes anything and names the command that removes a rule.

Options:

• --json: Output the new rule as JSON
• --project <name-or-id>: Project name or ID, defaulting to the linked project

Aliases: config remove, config delete.

Remove one trace sampling rule or every rule for an environment.

vercel traces config rm <environment> [requestPath]

The path prefix decides how many rules the command removes:

Combining --default with a path prefix is an error, because the two select different rules.

rm any removes the rules that match every environment, not every rule on the project. To clear a project and turn always-on tracing off, run rm once for each of any, preview, and production.

rm always asks you to confirm. One command can remove up to 10 rules, and nothing records what those rules held afterwards, so the command lists every rule it matched with its path and rate before it asks:

> The following 2 rules will be removed from my-app:
  production (all paths) 25%
  production /api 75%
? Remove 2 trace sampling rules? (y/N)

No option skips that prompt. A session that cannot show one, such as a CI job or a coding agent, fails without changing the project and prints the command to run in a terminal instead.

When nothing matches the environment and path prefix you passed, rm reports that no rule matched and leaves the project unchanged.

Options:

• --default: Remove only the rule without a path prefix, keeping the per-path rules
• --json: Output the removed rules as JSON
• --project <name-or-id>: Project name or ID, defaulting to the linked project

With --json, each subcommand prints only the rules it read or changed, so you can pipe the output into another tool:

vercel traces config ls --json

[
  {
    "environment": "production",
    "requestPath": "/api",
    "sampleRate": 25
  }
]

Each field maps onto a set argument, so a rule from ls --json can go straight back in:

vercel traces config set production 25 /api

With --non-interactive, the subcommands print JSON whether or not you pass --json, and the object carries the project, a status, a message, and the commands to run next.

The following global options can be passed when using the vercel traces command:

• --cwd
• --debug
• --global-config
• --help
• --local-config
• --no-color
• --non-interactive
• --scope
• --team
• --token
• --version

For more information on global options and their usage, refer to the options section.

• Tracing overview
• Always-on tracing
• Session tracing