Debugging Vercel From the Terminal: When traces search Beats the Dashboard

Vercel added vercel traces search in its September 29, 2026 changelog. The command queries trace spans from the terminal and returns up to 100 spans from the last hour by default.

It offers filters for status, deployment and trace ID, a subset of KQL for ad-hoc queries, and --json output for scripts and coding agents. For a recent incident, that gives you a useful first probe without opening a dashboard. Whether it is enough depends on the incident’s age, the spans returned, and the query you need.

What the command actually does, and what it doesn’t promise

The headline behavior is deliberate breadth without prerequisites, as Vercel’s changelog puts it: “By default, vercel traces search returns up to 100 spans from the last hour, newest first, so you can search without first finding a request or trace ID.” That matters operationally. The old terminal path against Vercel started with an identifier you had to find somewhere else, usually the dashboard. This command inverts the order: you sweep first, then identify.

On top of the default sweep sit dedicated flags. The changelog lists filters for “environment, service, span name, status, deployment ID, request ID, trace ID, or span ID,” plus --since and --until to narrow the time range. For everything those flags don’t cover, there is --query, which accepts “Vercel’s supported subset of Kibana Query Langugage (KQL).” Supported fields include duration and span and resource attributes. The changelog’s own example targets slowness directly:

vercel traces search --query 'span.duration > 2000'

That returns spans slower than two seconds, a useful starting point when latency is the complaint.

The output contract completes the picture. “Add --json to output one JSON object per span, giving scripts and agents structured data to analyze.” One object per span is pipe-friendly: jq can group, count, or filter it without parsing tables, and an agent can consume it without screenshots. This is the same pattern Vercel applied when it moved feature-flag segments into the terminal with scriptable --json output, and it signals a consistent direction: the CLI is being built for programmatic consumers, and humans at a keyboard get the same structure.

Before relying on the command, check two things the changelog leaves open: how far back traces are retained, and which parts of KQL the query interface supports.

A reproducible terminal procedure

For a fresh incident, start with a short terminal sequence. Move to the dashboard when the returned spans or supported queries do not cover the question you are investigating.

Step 1: error-span sweep. Query the last hour for failed spans across the affected service or environment:

vercel traces search --status error --json

Narrow by service or environment if the project is noisy. The changelog does not print those flag spellings, so check vercel traces search --help for the exact names. You can use --json output to count spans by name or deployment ID and start distinguishing a bad deployment from a broader regression.

Step 2: slow-span query. If errors are absent but latency is the complaint:

vercel traces search --query 'span.duration > 2000' --since 1h --json

Adjust the threshold to the endpoint’s baseline. One check before you script this: the changelog says only “one JSON object per span” and never enumerates the fields, so run a single --json call and confirm the span objects actually carry duration values and trace IDs. The handoff to the next step depends on both.

Step 3: query by trace ID. Once you have a trace ID from the verified output of steps 1 or 2, query the spans belonging to that request. Check the returned scope rather than assuming the result includes every span:

vercel traces search --trace-id <id> --json

A structured trace artifact can go straight into an issue, a comparison with a healthy trace, or an agent’s context. That can be convenient when the alternative is copying a waterfall screenshot into a discussion.

Step 4: check scope before escalating. An empty sweep does not establish that the system is healthy. Check the one-hour window and the 100-span cap against the incident you are investigating. For an older incident, the CLI’s reach is undocumented in this changelog; check the dashboard or an external trace store and verify their retention too.

The silent defaults: a short window and a hard cap

The changelog frames the defaults as convenience, and they are. They are also a truncation mechanism, and the changelog does not spell out the failure mode.

If the relevant spans are ninety minutes old, they fall outside a default sweep; that is different from an incident that started earlier but is still producing new spans. Whether the terminal can reach further back is undocumented in the changelog, so you may need the dashboard or an external trace store.

In a high-traffic service, the relevant spans can also fall beyond the 100-span cap within minutes. Newest-first results may show the tail of an incident without its onset. The changelog does not describe a truncation warning. Without checking the scope, it would be easy to read an empty or partial result as “nothing is wrong.”

These are consequences to consider from the stated defaults, not documented bugs. The changelog describes “up to 100 spans from the last hour”. What happens to span 101, or to a span from minute 61, remains undocumented here. It describes --since and --until only as ways to narrow the time range in the changelog, without saying whether you can widen the default hour or how far back the store goes.

Retention windows, plan gating, and sampling behavior are also unspecified. Verify your plan’s retention before using an empty sweep as an all-clear. When Runtime Logs gained CDN cache fields, our coverage discussed a similar limit: useful telemetry can still be constrained by the window in which it remains available.

The practical rule: treat the default sweep as a probe for the last hour, never as evidence about anything older.

Retention costs and older incidents

Retention has a cost, although that does not establish why Vercel chose this default. A study of log retention economics in small-scale cloud deployments found that cutting retention from 90 days to 14 days reduced log storage costs by up to 78 percent while preserving more than 97 percent of operationally useful logs. The study says retention policies are “frequently configured far beyond operational requirements,” often defaulting to 90 days in small and early-stage deployments.

The authors tested 7, 14, 30, and 90-day windows on synthetic log datasets designed to mimic real volume and access patterns. Those figures are useful background, not measurements of Vercel or any other production tracing product. In that study, longer windows brought diminishing operational returns while increasing storage cost and query overhead. It does not follow that a CLI’s default query window is its storage-retention limit.

If your team regularly investigates week-old incidents, check retention and sampling before relying on a terminal flag to recover the evidence. A longer retention tier or an external trace store may be necessary. First establish which traces still exist and which interface can query them.

Terminal or dashboard: the decision table

Choose the terminal when precise recent queries and reusable structured output are what you need. The dashboard remains useful for history, aggregation, and showing the incident to someone who does not work in the terminal; its available history still depends on retention. When redirect and rewrite telemetry landed in the dashboard, routing behavior became easier for whoever is on call to see. Start with the surface that fits the question.

Wiring observability into an agent’s toolset

The changelog’s phrase “giving scripts and agents structured data to analyze” is an explicit invitation, and it forces a permission decision most teams have not made deliberately.

If a coding agent can run vercel traces search, its access comes from the CLI credentials behind it. I would first check whether those credentials can be restricted to read-only observability: sweeping error spans, running duration queries, and querying traces, without deployment, environment-variable, or production-configuration access.

That would let an agent do repetitive grouping work while a human inspects the shortlist. It is a design recommendation, not a scope the changelog confirms. Vercel’s CLI has disrupted CI scripts through a quiet breaking change under a UX-framed changelog entry, another reason to check what automation can invoke rather than assume its defaults are suitable.

Here is the caveat the changelog does not supply: it says nothing about scopes, tokens, or permissions. The read-only recommendation is design judgment, not documented capability. Whether Vercel’s token model actually supports a scope narrow enough for this pattern is a question for the docs, and it should be the first thing you verify before handing an agent the keys.

There is also a quieter benefit to --json as the agent interface. Research on CLI agents documents a selective-observation bottleneck: the agent starts with a partial view of a large workspace and must find the task-relevant evidence in it. One paper proposes σ-Reveal, a mechanism that selects token-budgeted workspace context before the agent’s first action. The setting differs from querying a trace store, but the lesson transfers: context selection is a first-class problem for terminal agents, and one-object-per-span JSON applies the same principle at the source.

Does the KQL subset cover your queries?

This is the loose thread that decides whether the command survives contact with production. The changelog says --query accepts Vercel’s supported subset of KQL and names duration plus span and resource attributes as supported fields. It never enumerates the subset.

An incident query may need a duration threshold, status filter, route-attribute match, and a way to exclude health checks. The changelog does not provide the field list needed to know which combinations parse, error, or behave differently from what you expect. Test your three or four common production queries against --query before putting them in a runbook or agent prompt. For dedicated flags, confirm their spellings and behavior with the command’s help output.

The counter-evidence: agents may prefer the GUI anyway

Everything above assumes the terminal is the right surface for agents. A matched benchmark complicates that assumption. In a 440-task desktop benchmark spanning 18 applications, GUI and skill-mediated CLI agents received identical user goals, initial states, and executable final-state verifiers. The strongest GUI agent (GPT-5.4) achieved a 59.1% full pass rate; the strongest CLI agent (Codex GPT-5.5) reached 48.2% under the original skill layer.

Those are desktop tasks, not Vercel tracing. The result cautions against assuming that terminal access alone makes an agent better at finding useful evidence. Here, --json gives the agent structured span data rather than screenshots or unstructured scrollback, but that difference does not prove a tracing advantage. Check whether the agent can select the relevant spans and interpret them correctly before treating this interface as its preferred route.

For a human or supervised agent with a precise query, a command that returns a reusable artifact may still be the convenient starting point. The desktop benchmark does not settle that tracing-specific choice.

The verdict, and what to verify first

Try vercel traces search --json as a first probe for a recent Vercel incident: sweep for errors, query span.duration for slowness, then query by trace ID after confirming that the JSON carries the fields you need. Check whether the returned spans cover the incident. Keep the dashboard available for older events, aggregate trends, and visual explanations. Before giving an agent this command, verify that you can restrict its credentials to the observability access you intend.

The limits on all of this are real. Every feature fact in this article traces to Vercel’s own changelog; the cited evidence contains no independent user reports. Retention windows, plan gating, sampling behavior, the --json field list, and the full KQL field list are unverified. The default query window does not establish what the service retains or what an explicit time range can return. The retention-economics numbers come from synthetic datasets measuring storage cost, not debuggability, and the GUI-versus-CLI benchmark measures desktop tasks, not tracing. Check Vercel’s documentation for retention and the KQL subset before you build a runbook on this command, and treat an empty sweep as a question about scope, not an answer about your system.