Vercel Logs

Stream Vercel deployment logs into Gonzo for real-time terminal analysis

Stream Vercel deployment logs into Gonzo for real-time terminal analysis — with your app-level fields (service, level, message) unwrapped from Vercel's double-encoded JSON and merged with platform metadata (domain, route, status code).

How It Works

The Vercel CLI's -j flag outputs each log line as JSON, but the actual app log is buried inside the message field as a stringified JSON object with a [function-name] prefix (e.g. [orders] for /api/orders). A jq normalizer in the pipe strips the prefix, parses the inner JSON, and merges it with the Vercel envelope — so Gonzo sees a flat, clean log line with all fields at the top level.

When you specify a deployment URL, Vercel auto-follows (streams in real time) by default.

Quick Start

Prerequisites

• Gonzo installed

• jq installed (brew install jq)

• Vercel CLI installed and authenticated (npm i -g vercel && vercel login)

• A Vercel deployment receiving traffic

Stream Logs

vercel logs <deployment_url_or_id> -j | jq --unbuffered '
  (.message | sub("^\\[.*?\\] "; "") | fromjson) + {source, requestPath, domain, requestMethod, responseStatusCode}
' | gonzo

Replace <deployment_url_or_id> with your deployment URL or ID. Find this in the Vercel dashboard or via vercel ls.

⚠️ --unbuffered on jq is mandatory. Without it, jq buffers output and the pipe appears to stall. This is the #1 setup issue.

What Gets Unwrapped

The normalizer produces a flat JSON line combining fields from two layers:

Source	Fields	Description
Your app (inner JSON)	ts, level, service, msg, reqId, value	The actual structured log your code emitted
Vercel envelope (outer)	source, requestPath, domain, requestMethod, responseStatusCode	Platform metadata from the edge

Gonzo sees the app-level level field, not Vercel's outer classification — so severity filtering reflects what your code actually logged.

Usage Patterns

Batch fetch (no streaming):

vercel logs <deployment_url_or_id> -j --no-follow | jq --unbuffered '
  (.message | sub("^\\[.*?\\] "; "") | fromjson) + {source, requestPath, domain, requestMethod, responseStatusCode}
' | gonzo

Write to file for external analysis:

vercel logs <deployment_url_or_id> -j --no-follow | jq --unbuffered '
  (.message | sub("^\\[.*?\\] "; "") | fromjson) + {source, requestPath, domain, requestMethod, responseStatusCode}
' > /tmp/vercel-logs.jsonl

With AI analysis:

export OPENAI_API_KEY="sk-your-key"
vercel logs <deployment_url_or_id> -j | jq --unbuffered '
  (.message | sub("^\\[.*?\\] "; "") | fromjson) + {source, requestPath, domain, requestMethod, responseStatusCode}
' | gonzo --ai-model="gpt-4"

Filter by branch:

vercel logs --follow -j -b main | jq --unbuffered '
  (.message | sub("^\\[.*?\\] "; "") | fromjson) + {source, requestPath, domain, requestMethod, responseStatusCode}
' | gonzo

Filtering in Gonzo

Press / to filter. Useful patterns:

Filter	What you'll see
error	App-level errors (from the inner level field)
payments	Logs from the payments service
auth	Authentication-related logs
/api/orders	Requests to a specific route
edge-function	Edge function logs only
timeout	Timeout-related messages

The [prefix] Explained

Vercel prepends the API route name to the message field as a bracket prefix:

• /api/noise → [noise] {...}

• /api/orders → [orders] {...}

• /api/auth/login → [auth/login] {...}

The normalizer's sub("^\\[.*?\\] "; "") strips any [...] prefix automatically, regardless of the route name.

Notes

• The -j flag is required. Without it, Vercel outputs plain text and the normalizer has nothing to parse.

• No log drain required. This uses the Vercel CLI directly, which is currently free on Hobby and Pro tiers. No Vercel-side configuration needed.

• Vercel log retention is limited. Runtime logs are retained for 1 hour (Hobby), 3 days (Pro/Enterprise). For longer retention, consider forwarding to Dstl8.

• Non-function logs may not have the [prefix] {json} format. Build logs or platform-level messages can appear in the stream without inner JSON. These will cause a jq parse error — they're safe to ignore.

Troubleshooting

Problem	Fix
Pipe appears to stall	Make sure --unbuffered is on the jq call
No logs appearing	Check you're authenticated (vercel whoami) and the deployment is receiving traffic
vercel: command not found	Install the CLI: npm i -g vercel
jq: error - Could not parse	A log line doesn't have the expected [prefix] {json} format — likely a build or platform log. Safe to ignore.
Logs appear but no inner fields	Make sure you're using the -j flag
Ctrl+C not killing the pipe	Use ctrl+\ (SIGQUIT) or kill $(pgrep -f "vercel logs") from another terminal

Time to complete: 5 minutes | Prerequisites: Vercel CLI, jq, Gonzo installed | Full guide: guides/VERCEL_USAGE_GUIDE.md