Vercel logs: Runtime Logs, CLI, and Log Drains

Find failed requests in Vercel Runtime Logs, query them with the CLI, and verify JSON or NDJSON delivery to a log drain receiver.

Best practices
Illustration of log events and data analysis

A production request returns 500 just after a deploy. Start in the project's Logs view and look for the request and the deployment that served it. If the deployment failed before it could take traffic, open Build Logs on the deployment instead. The useful question is whether the request reached your code, and which version ran when it did.

Find the failing request in Runtime Logs

Set the environment and time window first. Filter by deployment, then by request ID if you have one. Runtime Logs cover execution output from Vercel Functions and Routing Middleware. For a suspected firewall block, check the Firewall view as well. A response served from cache may leave no new function log for you to find. Runtime Logs · Firewall observability

From a linked project, this example looks for production runtime errors in one deployment. Replace dpl_example with your deployment ID.

vercel logs runtime --deployment dpl_example --environment production \
  --since 30m --query 'level:error' --limit 50

This syntax is for Vercel CLI v64 or later. The filter matches log severity, so it won't return every HTTP 500. For CDN request records, use vercel logs requests with an httpStatus filter. If you add --json, read log entries under .data and handle the final summary line separately. Vercel CLI logs reference

As documented on November 10, 2026, Runtime Logs retention is one hour on Hobby, one day on Pro, and three days on Enterprise. Eligible projects with Observability Plus get 30 days, with up to 14 consecutive days per selection. If the request has aged out, widening the filter cannot recover it. Observability Plus

Give the next failure a searchable field

A line like “checkout failed” can tell you where to look. It rarely tells you which part of checkout failed. Use a small set of stable fields, such as event and outcome, that have the same meaning across deployments. This synthetic Next.js App Router handler emits one compact JSON line and reads no customer data. Next.js Route Handlers

export async function POST() {
  console.log(JSON.stringify({
    event: "checkout_probe",
    outcome: "ok",
  }));
  return Response.json({ ok: true });
}

In a drain record, that line can arrive as a string in message. Parse it at the receiver and keep the platform's level separate from any app-level field. Vercel maps console.error output to error, while HTTP status describes the response. Leave raw request bodies, tokens and personal data out of the event. Vercel log drain schema

Start the Log Drain with one project

Log Drains are available on Pro and Enterprise, excluding Pro Trial. With the appropriate team permissions, open Team Settings → Drains, add a Log drain and choose Custom Endpoint. Select the project, environments and log sources you actually need. Choose either batches as JSON arrays or NDJSON, where each line is one object. Without sampling rules, the drain forwards its selected scope. If you add rules, the first match applies and unmatched requests aren't forwarded. Vercel Drains · Configure a drain

Vercel sends an HTTPS POST. At the receiver, verify x-vercel-signature against the raw body before parsing or transforming it. This Node.js helper expects a buffer and the header value. Read the secret from server-side configuration.

import { createHmac, timingSafeEqual } from "node:crypto";

export function validDrainSignature(rawBody, signature, secret) {
  if (!Buffer.isBuffer(rawBody) ||
      typeof signature !== "string" || !/^[0-9a-f]{40}$/i.test(signature) ||
      typeof secret !== "string" || !secret.length) {
    return false;
  }
  const expected = createHmac("sha1", secret).update(rawBody).digest();
  return timingSafeEqual(expected, Buffer.from(signature, "hex"));
}

Bound the request size. After verification, reject malformed batches or entries that aren’t JSON objects. Return HTTP 200 once you’ve durably accepted the batch. Custom Headers can add another authentication check. The drain dashboard shows delivery failures, but the current docs don't promise historical replay or a fixed retry schedule. Check gaps in received records and make writes idempotent, for example using project ID and record ID. Vercel drain security · Delivery setup and errors

Check the record you actually stored

Run the drain's Test action, then trigger a new log from a selected environment and look for its deployment ID at the destination. Confirm that timestamp is interpreted as epoch milliseconds. Keep level and the optional numeric statusCode separately searchable. Build logs may lack requestId. A top-level statusCode of -1 marks a crashed Lambda that returned no response. A proxy.statusCode of -1 marks background ISR revalidation. Keep both separate from actual HTTP status codes. Vercel log drain schema

For Guance, DataKit's Log Streaming collector exposes /v1/write/logstreaming. Check the supported input format and authentication before wiring it up. Where an adapter is needed, verify the drain signature on the HTTPS receiver and forward normalized events to DataKit. In the logs explorer, filter on the deployed ID and compare the error event and response fields for that release. Guance Log Streaming · Guance Logs Explorer

Next in the series, Google Cloud Logging · Related guide, AWS Lambda logs

Get a tailored plan

Contact us

Join the community

Scan with WeChat
to join the community

Try Guance

Start online and pay only for what you use.

Get started

Choose a Guance plan

Code hosting