Vercel 日志实战:运行时日志、Log Drains 与 Serverless 排障

Vercel 日志中文实战:构建日志与运行时日志的区别、Vercel Dashboard 日志查看、Log Drains 外送配置(JSON/NDJSON 与接收端验签)、Serverless/Edge 函数的结构化日志写法、日志保留与限制,以及观测云接收告警落地方案。

最佳实践
Vercel 日志实战:运行时日志、Log Drains 与 Serverless 排障技术指南封面

Vercel 作为 Serverless/Edge 部署平台,其日志体系围绕"构建 + 运行时"两条线展开,运行时保留期有限,需要更长留存或集中分析时可按套餐配置日志外送。本文讲清 Vercel 日志的查看、外送与结构化实践,并给出观测云平台落地方案。

核心要点速览

  • 两类日志:构建日志(Build Logs,部署过程)与运行时日志(Runtime Logs,函数执行)。
  • 运行时日志保留有限:保留期取决于套餐与 Observability Plus;超过平台窗口的留存可以通过外送和下游存储实现。
  • Log Drains 需要 Pro/Enterprise 套餐:Pro Trial 不支持。自定义端点经 HTTPS 接收 JSON 数组或 NDJSON 批次。
  • 结构化 JSON 方便解析:函数可以输出普通文本;需要稳定检索业务字段时,可输出单行 JSON 并在接收端解析。

1. Vercel 的日志类型

类型 内容 查看位置
Build Logs 依赖安装、编译、静态生成过程 部署详情页
Runtime Logs 预览或生产中 Vercel Functions、Routing Middleware 的运行时记录 项目 Logs 面板
Firewall 防火墙流量和规则事件;Log Drain 可选择 firewall 来源 项目 Firewall 面板 / 适用的 Drains

Runtime Logs 按请求展示可用日志,可按时间、部署和请求 ID 缩小范围。字段依来源而异,保留期与单请求输出限制也会影响能查到的记录;请求 ID 不能还原未采集或已过期的数据。

2. Serverless 函数的日志写法

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

上面是 Next.js App Router 的合成探测 Route Handler,不读取订单或请求正文。单次 console.log 输出紧凑 JSON 可减少拆分;它仍可能作为平台日志的 message 字符串,需要接收端按样本解析。只保留必要且允许记录的业务关联标识,避免密码、令牌、原始请求体及个人信息。平台级别按输出方式映射,例如 console.error 对应 error;JSON 内部级别和 HTTP 状态码是独立字段。Edge Runtime 要核对运行时支持的 API 和具体日志来源。

3. Log Drains:外送到日志平台

Vercel Dashboard → Team Settings → Drains → Add Drain:

  1. 选择 Log 数据类型和 Custom Endpoint;
  2. 选择项目、环境和日志源,如 lambda、edge、build 或 firewall;
  3. 选择接收端支持的 JSON 数组或每行一个对象的 NDJSON;
  4. 填写可达的 HTTPS 接收端,按文档接收 POST 并在可靠接收后返回 HTTP 200;
  5. 使用 Drain 签名密钥验证 x-vercel-signature;按需使用 Custom Headers 做附加鉴权或路由。签名按原始请求字节计算,密钥不得写入代码或日志。验签后拒绝格式错误的批次或非 JSON 对象的条目;
  6. 创建时确认自定义端点测试通过,再用 Drains 的 Test 功能及选定项目的新日志核对格式和实际入库。

注意:Log Drains 需要 Pro 或 Enterprise 套餐,Pro Trial 不支持。需要相应团队配置权限。若启用采样规则,按顺序匹配,未命中规则的请求不会转发;未配置规则时转发所选范围的全部数据。

验证外送日志是否正确入库

接入前先用 Drains 的 Test 功能核对接收端协议。观测云 DataKit 的 Log Streaming提供 /v1/write/logstreaming 接口;先核对 TLS、批次格式和鉴权。若接口不能直接验证签名或处理所选格式,用接收服务先验证原始字节再转发,不要公开不带鉴权的采集端。

适配后保留项目、部署 ID 及已提供的请求标识。按 Drain timestamp 的毫秒口径解析事件时间,将 level 映射到支持的日志状态,选填的 HTTP 状态码单独存放。顶层 statusCode 为 -1 表示 Lambda 崩溃且未返回响应,proxy.statusCode 为 -1 则表示后台 ISR 再验证,两者均应与实际 HTTP 状态码区分。构建日志等来源可能缺少请求 ID。先核对一条已知函数错误及已记录的堆栈,再在日志查看器按部署查找同类失败,避免把不同发布批次混在一起。

常见问题(FAQ)

免费版 Vercel 日志保留多久?

截至 2026-11-10 的 Vercel 文档,Hobby 的 Runtime Logs 保留 1 小时,Pro 1 天,Enterprise 3 天。适用项目启用 Observability Plus 后可保留 30 天,单次最多选择连续 14 天。构建日志不是这个口径。Hobby 不支持 Log Drains。

Edge 函数和 Serverless 函数日志有区别吗?

都可在 Runtime Logs 中调查,但执行环境、日志来源及字段不完全相同。Log Drain 可分别选择 lambda 和 edge;以实际捕获的样本判断可用字段。

为什么我的 console.log 在 Vercel 日志里看不到?

常见原因:函数该次调用根本没执行(缓存命中/静态化)、部署版本不对、日志面板过滤条件过严。用请求 ID 精确过滤定位。

Log Drain 推送给平台失败会重试吗?

当前 Drains 文档说明了失败状态与通知,没有给出可依赖的重试或历史补发保证。接收端应记录非成功响应和积压,使用日志条目的 id 做幂等处理,并核对预期收到的事件。

系列阅读


[1]: 观测云文档《DataKit 日志采集综述》https://docs.guance.com/integrations/datakit-logging/
[2]: 观测云文档《日志查看器》https://docs.guance.com/logs/explorer/
[3]: 观测云文档《监控》https://docs.guance.com/monitoring/

Vercel 官方参考:Runtime Logs · Observability Plus · 配置 Drains · 日志结构 · 接收端安全

获取专属方案

联系我们

加入社区

微信扫码
加入官方交流群

立即体验

在线开通,按量计费,真正的云服务!

立即开始

选择观测云版本

代码托管平台