Heroku 日志实战：Logplex 体系、heroku logs 与日志外送

Heroku 的日志体系围绕 Logplex 构建：一个面向流的日志总线，汇总应用 dyno、路由器、平台的全部日志。理解 Logplex 的"只流不存"特性，是管好 Heroku 日志的关键。本文讲解日志查看、外送与结构化最佳实践，并说明外送接收端的格式验证方法。

核心要点速览

• Logplex 是日志总线而非存储：默认只保留最近约 1500 行/一周——长期存储必须外送（Log Drain）。
• 日志来源分三类：app（应用输出）、router（HTTP 请求路由）、heroku（平台事件：部署/重启/崩溃）。
• heroku logs --tail 是排障起点，--source、--dyno、--num 精细过滤。
• 外送验收：确认接收端兼容 Log Drain 的封装、字段及重试行为。

1. Logplex 工作原理

Heroku 把每个 dyno 的 stdout/stderr、路由器请求日志、平台事件汇聚到 Logplex 流中：

2026-08-25T14:55:22.123+00:00 heroku[router]: at=info method=GET path="/api/orders" host=example.com request_id=7f3a status=200 ...
2026-08-25T14:55:22.456+00:00 app[web.1]: INFO 订单创建成功 {"order_id":1024}
2026-08-25T14:55:30.000+00:00 heroku[web.1]: Restarting

每条带时间戳、来源（source）、进程（dyno）三元组。Logplex 默认只缓存最近约 1500 行——它是传输层，不是存储层。要长期保留与检索，必须配置 Log Drain 外送。

2. heroku logs 命令

heroku logs --tail                 # 实时跟踪
heroku logs --num 500              # 拉取最近 500 行
heroku logs --source router        # 只看路由日志（HTTP 请求）
heroku logs --source app           # 只看应用输出
heroku logs --dyno web.1           # 只看某个 dyno
heroku logs --source app --dyno worker.1 --tail

排障组合拳：--source router 看请求面（状态码、耗时），--source app 看业务面，平台事件（崩溃 H10、内存超限 R14）看 heroku source。

3. 五条 Heroku 日志最佳实践

1. 写 stdout/stderr：Heroku 只收集标准输出流——写文件等于丢日志；
2. 结构化输出：JSON 或 logfmt，让平台自动解析字段；
3. 关键事件带上下文：用户操作日志带 user_id、request_id，而不是一行裸消息；
4. 正确分级：INFO 记业务事件、ERROR 记失败——router 日志里的 H/R 系列错误码（H12 超时、R14 内存超限）要单独关注；
5. 敏感数据不入日志：密码、卡号、Token 立法禁止。

4. Log Drains：日志外送

# 添加 HTTP(S) drain：日志实时推送到指定端点
heroku drains:add https://<接收端点> -a <应用名>
heroku drains                     # 查看已配置 drain

Drain 支持 HTTP(S) 与 syslog 两种协议。Heroku 的日志以 syslog 帧格式（或 HTTPS 批次）发出，接收端解析后入库。

验证外送日志的接收格式

外送前先用测试应用检查接收端是否识别 Logplex 的批次与 syslog 帧，确认应用名、dyno、来源和时间戳都保留下来，再配置正式流量。

向观测云转送时，DataKit Log Streaming提供 HTTP 日志接收端点，但其文档列出的格式不能直接等同于 Heroku Drain。应由兼容 Logplex 的接收程序解包，转换为接收端支持的格式，再验证入库记录数、解析字段及失败重试。

常见问题（FAQ）

Heroku 日志默认保留多久？

Logplex 只缓存最近约 1500 行（大致相当于一周的滚动窗口，先到先出）。任何"昨天出了什么问题"级别的事后排查都必须依赖 Log Drain 外送到日志平台。

router 日志里的 H12、R14 是什么？

Heroku 平台错误码：H12 = 请求超时（30 秒未响应），R14 = 内存超限（dyno 开始使用 swap）。H 系列是路由/请求问题，R 系列是运行时资源问题，应按各自错误码排查请求或资源问题。

多个 Heroku 应用的日志能统一吗？

可以让各应用的 Drain 发往同一兼容接收端，保留应用标识，再按应用查询验证日志没有混淆。

Log Drain 推不出去会怎样？

Heroku 会丢弃无法送达的日志（Logplex 无持久缓冲）。选接收端时考虑可用性；应在测试环境验证接收程序的持久化、重试与重复记录处理。

系列阅读

• 上一篇：Docker Compose 日志指南
• 下一篇：Vercel 日志实战
• 相关阅读：什么是日志聚合 ｜ 日志最佳实践总论

---