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

Heroku 日志中文实战:Logplex 日志总线工作原理、heroku logs 命令(--tail/--source/--dyno)、日志保留限制、Log Drains 外送机制、结构化日志最佳实践,以及如何用观测云接收并告警 Heroku 应用日志。

最佳实践
事件记录与日志数据分析主题插画

Heroku 的 Cedar 代际通常通过 Logplex 汇集应用 dyno、路由器和平台的日志流;它是传输与短期缓冲设施,不是长期日志存储。Fir 代际则使用 OpenTelemetry/OTLP,不使用 Logplex,也没有同样的日志历史;启用 Private Space Logging 的 Shield Space 也属于例外。本文以 Cedar 的 Logplex 和 Log Drain 为主,标明与 Fir 不同的地方,讲解日志查看、外送与结构化最佳实践。

文中日志与命令是文档示例,未连接实际 Heroku 应用或配置外送。平台边界依据 Heroku Logging 与 Heroku Telemetry(英文)。

核心要点速览

  • Logplex 是日志总线而非长期存储:适用的 Cedar 应用最多保留最近 1500 行,且日志在 1 周后过期;行数淘汰与时间过期先到者生效,不是“1500 行大约等于一周”。可靠的长期留存需提前外送。
  • 区分 source 与 dyno:Cedar 应用输出通常是 app source,平台组件是 heroku source;路由日志里的 router 是 dyno/组件字段,不是单独的 source。构建日志还需从相应构建记录查看,不能把运行日志流当作所有日志的全集。
  • heroku logs --tail 是排障起点,Cedar 可用 --source、--dyno、--num 过滤或取短期历史;Fir 没有历史,heroku logs 默认实时跟踪。
  • 外送验收:Cedar 的 HTTPS/syslog drain 与 Fir 的 OTLP telemetry drain 不同,接收端需兼容对应封装、字段与失败处理,不能保证零丢失。

1. Logplex 工作原理

Cedar 将纳入采集的 stdout/stderr、路由器请求和平台事件汇聚到 Logplex。下面是 CLI 展示格式的合成示例,不是 HTTP drain 的原始请求体:

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],再后面才是正文。第二行在文本后附了 JSON,并不代表整行已经是可直接解析的 JSON。日志来自不同节点,接收顺序也不保证事件时间严格有序。

Logplex 历史受 1500 行与 1 周两项上限约束。忙碌应用可能很快把较早记录挤出缓冲;长期留存与检索应交给已配置的 logging add-on 或 Log Drain 接收端。Fir 使用 OTLP telemetry drain,不能沿用这套 Logplex 历史假设。

2. heroku logs 命令

以下以有权读取的 Cedar 应用 my-app 为例,替换为实际应用名:

heroku logs --app my-app --tail                         # 实时跟踪
heroku logs --app my-app --num 500                      # 取仍在缓冲中的最近 500 行
heroku logs --app my-app --source heroku --dyno router   # 只看路由组件日志
heroku logs --app my-app --source app                   # 查看 app source
heroku logs --app my-app --dyno web.1                   # 只看某个 dyno
heroku logs --app my-app --source app --dyno worker.1 --tail

排障时,用 --source heroku --dyno router 看请求状态和路由耗时,再用 --source app 看应用记录;平台崩溃信息及适用环境下的 R14 等运行时事件则查看 heroku source。Cedar 默认取 100 行,--num 最大 1500,不能取回已淘汰的记录。实时 tail 也不是完整归档;闲置 1 小时会自动结束。

Fir 的 heroku logs 默认 tail,可用 heroku logs --app my-fir-app --process-type web 按进程类型过滤;Heroku 内部日志的 source 使用 heroku- 前缀,例如 heroku-router。不要把 Cedar 的 web.1 命名、source 或历史过滤行为直接套用到 Fir。CLI 过滤说明(英文)

3. 五条 Heroku 日志最佳实践

  1. 写 stdout/stderr:平台会采集标准输出与标准错误。文件日志不会自动进入该日志流,需要框架配置或显式转发;并非写入文件就立即消失,但 dyno 临时文件系统不能承担可靠长期留存。
  2. 结构化输出:使用 JSON 或 logfmt,并配置接收端解析规则;Heroku 外层封装与应用正文仍需分开处理,不是输出 JSON 后所有字段就自动入库。
  3. 关键事件带上下文:记录适当的用户标识、request_id 和业务事件,而不是一行裸消息;标识符需按数据最小化与脱敏要求处理。HTTP request_id 也不能直接当作 APM 的 trace_id。
  4. 正确分级:INFO 记业务事件、ERROR 记失败;路由的 H12 与运行时的 R14 属于不同组件和条件,不应都归到 router 日志中,也不能只凭单条错误确定根因。
  5. 敏感数据不入日志:避免输出密码、可直接使用的认证凭据和完整卡号,按实际政策处理用户数据。接收配置中需区分 drain 身份标识与应用认证凭据,避免把可用凭据混入日志正文。

4. Log Drains:日志外送

以下新增 drain 的命令会修改 Cedar 应用配置。先准备兼容接收端,替换示例 URL 与应用名;本文未执行这些命令:

# Cedar HTTPS drain 配置示例
heroku drains:add https://logs.example.com/heroku --app my-app
heroku drains --app my-app          # 查看已配置 drain

Cedar 支持 HTTPS 与基于 TCP 的 syslog drain,后者可使用 TLS。syslog 消息使用 octet-counting 分帧;HTTPS 则以 POST 批量发送 application/logplex-1 请求体,批次内也按字节长度分帧,不是一个 JSON 数组,也不宜只按换行拆分。Heroku 的 HTTPS 格式还省略了标准 syslog 的部分结构,不能假定任意 RFC 5424 解析器都直接兼容。

接收端应核对 Logplex-Msg-Count,保留 Logplex-Frame-Id 用于识别重试批次,并用 Logplex-Drain-Token 关联已配置的应用身份。非 2xx 或网络错误可能触发重试,重试也可能带来重复;接收端应按官方响应要求返回无正文、Content-Length: 0 的响应,并明确确认发生在接收、持久化还是入库之后。Logplex 是尽力交付,有限缓冲仍可能溢出丢弃记录。

Fir 只使用 telemetry drain 输出 OTLP,管理命令是 heroku telemetry,不是把上面的 HTTPS Logplex drain 换一个 URL。Heroku Log Drains(英文)

验证外送日志的接收格式

外送前用获准的测试应用核对批次数、帧数和实际入库数,保留应用身份、dyno、Heroku source 与事件时间。多个应用共用接收端时,可维护 drain token 到应用的配置映射;删除并重建 drain 后 token 会变化,不能只凭 app source 区分应用。日志时间与接收时间也要分开,以便检查乱序和延迟。

向观测云转送时,DataKit Log Streaming提供 HTTP 日志接收端点,但不是已声明兼容 Heroku Logplex drain 的原生接收器。应由兼容接收程序解包,再转换成其文档支持的格式与字段。可用独立字段保留 heroku_app、heroku_source、dyno 等上下文;这些是映射示例,不是自动生成的内置字段。DataKit 的 source 表示日志采集源/measurement,也不能与 Heroku 的 source 不加区别地混用。

随后验证事件时间解析、持久化与重试边界、去重和溢出告警。DataKit 有 HTTP 接口不等于端到端可靠入库;Fir 的 OTLP 接收兼容性也需另按双方支持的信号、传输和端点核对,不能复用 Logplex 适配假设。

常见问题(FAQ)

Heroku 日志默认保留多久?

使用 Logplex 的 Cedar 应用最多保留最近 1500 行,同时在 1 周后过期,先触及的限制生效。昨日记录可能还在,也可能已被挤出,不能保证固定保留一周。Fir 没有日志历史;启用 Private Space Logging 的 Shield Space 也不提供相同的 CLI 历史。可靠的事后检索应事先配置外送与存储,已经淘汰且未另存的记录不能补采回来。

日志里的 H12、R14 是什么?

Cedar 日志中的 H12 是路由请求超时:通常指初始 30 秒窗口内没有返回响应数据,并非所有流式响应都必须在 30 秒内结束;发送首字节后还有滚动空闲超时规则。路由器返回错误后,应用进程仍可能继续处理。Fir 的日志来源与可用错误码应按当前代际文档核对,不要套用所有 Cedar 规则。

R14 是内存配额超限,在适用的 Cedar Common Runtime 中与使用 swap 有关;Private Spaces 不使用 swap,因此不发出 R14。当前 Fir 也不发出 R14,不能把“没有 R14”当作内存正常的证据。错误码 · 请求超时(英文)

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

可以让各应用的兼容 drain 发往同一接收端,保留每个应用的身份和相应的 drain/资源标识,再按应用核对查询结果。Cedar 与 Fir 的协议不同,需要相应接收或适配路径,不能仅因共用 URL 就视为已经统一。

Log Drain 推不出去会怎样?

Logplex 有有限缓冲与重试行为,但不提供保证交付的持久日志队列。接收端持续跟不上时,缓冲可能溢出并丢弃记录,可见 L10 等缺失提示。接收程序应验证持久化、失败重试与重复处理;不要承诺无丢失或恰好一次交付,也不要把这些 Cedar L 系列提示当作 Fir 必有的错误码。

系列阅读

资料核对日期:2026-11-05。


获取专属方案

联系我们

加入社区

微信扫码
加入官方交流群

立即体验

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

立即开始

选择观测云版本

代码托管平台