vercel traces

The vercel traces command helps you inspect request traces for a linked project or a specific project.

Use vercel traces get <request-id> to inspect a request trace, and vercel traces config to manage which requests Vercel traces.

# Get a specific trace
vercel traces get req_1234567890
 
# `get` is the default subcommand
vercel traces req_1234567890
 
# Open a trace in the Vercel Dashboard
vercel traces get req_1234567890 --open
 
# List the trace sampling rules for the linked project
vercel traces config ls

The get subcommand returns details for a single trace by request ID.

vercel traces get req_1234567890
vercel traces get req_1234567890 --json

The config subcommand group reads and writes the sampling rules that decide which requests Vercel traces. See Manage trace sampling rules.

vercel traces config ls

These options apply to vercel traces get.

The --project option specifies the project name or ID.

vercel traces get req_1234567890 --project my-app

The --json option returns machine-readable output.

vercel traces get req_1234567890 --json

The --open option opens the trace in the Vercel Dashboard instead of printing the trace in the terminal.

vercel traces get req_1234567890 --open

--open cannot be combined with --json.

Use --view with --open to set the initial Dashboard view. Supported values are timeline, tree, and waterfall.

vercel traces get req_1234567890 --open --view=tree
vercel traces get req_1234567890 --open --view=waterfall

--view requires --open.

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

Get JSON output for automation:

vercel traces get req_1234567890 --json

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.

ls also accepts list, and rm also accepts remove and delete.

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 evaluates rules in the order ls prints them and applies the first rule that matches a request. Because set adds a new rule to the bottom of that list, a broad rule you added earlier still wins over a narrower rule you add later. The CLI cannot reorder rules, so to change the order, remove the rules with rm and add them back in the order you want. To learn how overlapping rules are resolved, see Sampling.

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.

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:

# 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.

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.

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.