Vercel のログを調べる:Runtime Logs、CLI、Log Drains

Vercel の実行ログから失敗したリクエストを探す方法を解説。CLI の絞り込み、Log Drains の設定、受信時の署名検証まで扱います。

ベストプラクティス
ログイベントとデータ分析のイラスト

本番にデプロイした直後、あるリクエストが 500 を返した。まずプロジェクトの Logs で、対象のリクエストと処理したデプロイを確認します。そもそもデプロイが完了していなければ、見るべき場所はデプロイ詳細の Build Logs です。リクエストが関数まで届いたか、届いたならどの版が処理したか。この二点で調査の範囲が絞れます。

Runtime Logs で失敗したリクエストを探す

先に環境と時間帯を絞り、デプロイ、分かっていればリクエスト ID を指定します。Vercel Functions や Routing Middleware の実行ログは Logs にあります。ファイアウォールの遮断が疑わしいなら、Firewall も見ます。キャッシュから応答した場合は、新たな関数ログが出ないことがあります。Runtime Logs · Firewall の確認方法

次の例は、リンク済みプロジェクトの本番環境で、一つのデプロイのエラーログを調べます。dpl_example は実際のデプロイ ID に置き換えてください。

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

Vercel CLI v64 以降の書式です。level:error はログレベルの条件です。HTTP 500 を探す場合は、vercel logs requests で CDN のリクエスト記録を httpStatus で検索できます。--json を付けた場合、ログ本体は .data に入り、末尾に集計行が付きます。Vercel CLI のログコマンド

2026 年 11 月 10 日時点の公式資料では、Runtime Logs の保持期間は Hobby が 1 時間、Pro が 1 日、Enterprise が 3 日です。対象プロジェクトで Observability Plus を利用すると 30 日分を保持し、一度に選べる範囲は連続 14 日までです。保持期間を過ぎたログは、検索範囲を広げても戻りません。Observability Plus

関数ログに検索できる項目を持たせる

「決済に失敗」とだけ残しても、次の調査で絞り込みに使える情報は限られます。event や outcome のように、リリースをまたいでも意味が変わらない項目を用意します。以下は Next.js App Router の確認用 Route Handler です。顧客データを読まず、JSON を一行出力します。Next.js Route Handlers

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

この JSON は、外部転送時に message の文字列として届くことがあります。受信側で展開し、Vercel の level や HTTP ステータスとは別の項目として扱います。たとえば console.error の出力は error レベルになります。トークン、個人情報、リクエスト本文は出力しないようにします。Log Drain のデータ仕様

Log Drain の転送対象を一つずつ決める

Log Drains は Pro と Enterprise で利用でき、Pro Trial は対象外です。設定権限のあるチームで Team Settings → Drains を開き、Log と Custom Endpoint を選びます。まず調査したいプロジェクト、環境、ログのソースに絞ります。形式は JSON 配列か、一行に一オブジェクトを持つ NDJSON です。サンプリングルールがなければ指定範囲のすべてを転送します。ルールを設定した場合は先に一致したものが適用され、どのルールにも一致しないリクエストは転送されません。Vercel Drains · Drain の設定

受信側には HTTPS の POST が届きます。本文を加工・解析する前に、生のバイト列と x-vercel-signature を使って署名を検証します。次の Node.js の例には本文の Buffer とヘッダー値を渡します。シークレットはサーバー側の設定から読み込んでください。

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"));
}

受信サイズに上限を設けます。署名検証後に形式が壊れたバッチや、JSON オブジェクトではない要素を拒否し、バッチが失われない形で受け付けてから HTTP 200 を返します。必要に応じて Custom Headers でも認証できます。管理画面で転送エラーは確認できますが、固定の再試行間隔や過去分の再送は公式資料で保証されていません。受信の欠落を監視し、書き込みの重複を防ぐにはプロジェクト ID とレコード ID を使えます。受信エンドポイントのセキュリティ · 転送エラーの確認

受信先でどの項目が残ったか確認する

Drain の Test を実行したあと、対象の環境で新しいログを一件出し、デプロイ ID で探します。timestamp が Unix エポックからのミリ秒として解釈されているか、level と数値の statusCode を別々に検索できるかを確認します。statusCode は任意項目で、ビルドログには requestId がないことがあります。最上位の statusCode が -1 なら Lambda がクラッシュして応答を返していません。これに対し proxy.statusCode の -1 は ISR のバックグラウンド再検証を表します。どちらも実際の HTTP ステータスとは分けて扱います。Log Drain のデータ仕様

Guance に送る場合、DataKit の Log Streaming コレクターには /v1/write/logstreaming があります。先に入力形式と認証の要件を確認します。変換が必要なら HTTPS の受信側で署名を検証し、形式を整えてから DataKit へ渡します。ログエクスプローラーでデプロイ ID を絞れば、同じ版のエラーと応答状況を追えます。Guance の Log Streaming · Guance のログエクスプローラー

次の記事:Google Cloud Logging · 関連記事:AWS Lambda のログ(英語)

最適なプランを相談する

お問い合わせ

コミュニティに参加

WeChatでスキャンして
コミュニティに参加

Guanceを試す

オンラインですぐに始めて、使った分だけお支払いください。

利用を開始

Guanceのプランを選択

コードリポジトリ