Heroku 日誌實務:Logplex、heroku logs 與外部傳送
掌握 Heroku 日誌 tail 與篩選、Cedar Logplex 保留上限及 Fir OTLP 差異,並核對外送分幀、重試、應用識別與 DataKit 轉換前提。
篩選不到路由器日誌,不一定是路由器沒有輸出。在 Heroku Cedar 的 heroku[router] 裡,source 是 heroku,router 則是元件欄位。這個差別既影響事件當下的 tail,也影響外送至日誌平台時的欄位對應。
Cedar 通常以 Logplex 彙集應用、路由器與平台的日誌流,提供傳送與短期緩衝,並非長期儲存。Fir 改用 OpenTelemetry/OTLP,不使用 Logplex,也沒有同樣的日誌歷史;啟用 Private Space Logging 的 Shield Space 亦屬例外。本文以 Cedar 的 Logplex 與 Log Drain 為主,標明會改變操作方式的代際差異。
文中日誌與命令均為文件範例,未查詢實際 Heroku 應用,也未設定 drain。Heroku Logging(英文)・Heroku Telemetry(英文)
核心重點
- Logplex 是傳送設施,不是長期儲存。 適用的 Cedar 應用最多保留最新 1,500 行,日誌也會在 1 週後到期;先碰到的限制生效,不是 1,500 行約等於一週流量。
- 分清 source 與 dyno。 應用輸出通常是
appsource,Cedar 平台元件是herokusource。router屬於 dyno/元件欄位。建置日誌另從對應建置記錄查看,執行期串流並不涵蓋所有日誌。 - 由
heroku logs --tail開始調查。 Cedar 可依 source/dyno 篩選,或用--num查短期歷史。Fir 沒有歷史,heroku logs預設即為即時 tail。 - 先確認接收格式。 Cedar 的 HTTPS/syslog drain 與 Fir 的 OTLP telemetry drain 不同,封裝、欄位、失敗與缺漏都需核對。
1. 讀懂 Logplex 外層格式
Cedar 把已納入收集的 stdout/stderr、路由請求與平台事件彙入 Logplex。以下為 CLI 顯示格式的合成範例,並非 HTTPS 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 歷史受 1,500 行及 1 週兩項上限限制。繁忙應用可能很快就把舊記錄擠出。若要長期檢索,須預先設定 logging add-on 或 Log Drain 儲存端;Fir 的 OTLP 路徑不能套用同一歷史緩衝假設。
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 最多 1,500 行,不能找回已淘汰記錄。即時 tail 也不是封存,閒置 1 小時就會結束。
Fir 的 heroku logs 預設即時跟蹤,可用 heroku logs --app my-fir-app --process-type web 篩選程序類型。內部來源使用 heroku- 前綴,例如 heroku-router。不能直接套用 Cedar 的 web.1 命名、source 或歷史查詢方式。CLI 篩選(英文)
3. 五個讓日誌可用的做法
- 輸出至 stdout/stderr。 檔案日誌不會自動進入平台串流,需框架設定或明確轉送。寫入檔案並非立刻遺失,但 dyno 的暫存檔案系統不適合可靠長期保留。
- 結構化輸出搭配解析。 JSON、logfmt 仍需要接收端規則。Heroku 外層封裝與應用訊息分開處理,不能預期所有欄位自動抽出。
- 保留上下文。 記錄適當的使用者識別、
request_id與業務事件,並依最小化與遮罩要求處理。HTTP 請求 ID 不會自動成為 APM 的trace_id。 - 區分等級與元件錯誤。 INFO 記適當業務事件、ERROR 記失敗;路由 H12 與執行期 R14 的元件和條件不同,單筆都不足以確定根因。
- 不要輸出認證憑據。 避免密碼、可直接使用的認證資訊及完整卡號,使用者資料依適用政策處理。接收設定應區分 drain 身分識別值與應用認證憑據,避免將可用憑據混入日誌正文。
4. Log Drain:向外傳送
新增 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 則以 application/logplex-1 POST 內容批次傳送,內部同樣按位元組長度分幀。它不是 JSON 陣列,也不應只依換行切割。Heroku HTTPS 格式另省略部分標準 syslog 結構,不能假設任意 RFC 5424 解析器都能直接使用。
核對 Logplex-Msg-Count,保留 Logplex-Frame-Id 以識別重試批次,並把 Logplex-Drain-Token 對應到已設定的應用身分。非 2xx 或網路失敗可能觸發重試,也可能重複。接收端須依官方要求傳回無內容、Content-Length: 0 的回應,並確認接收、持久保存或索引寫入的哪一步才算完成確認。Logplex 是盡力傳送,有限緩衝溢位時仍可能捨棄資料。
Fir 由 heroku telemetry 管理 telemetry drain,傳送 OTLP;不是只把 Logplex HTTPS 設定換一個 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 混為一談。
接著確認事件時間解析、持久化與重試邊界、去重及溢位告警。存在 HTTP 介面不代表已證明端到端可靠入庫。Fir OTLP 的相容性也需另外核對雙方支援的訊號、傳輸方式及端點,不能沿用 Logplex 轉接器的假設。
常見問題
Heroku 日誌預設保留多久?
使用 Logplex 的 Cedar 應用最多保留最新 1,500 行,同時在 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」不能作為記憶體正常的證據。錯誤碼(英文)・請求逾時(英文)
多個應用的日誌可以整合嗎?
可以讓相容 drain 共用接收端,保留各應用身分與對應的 drain/資源識別,再依應用核對查詢結果。Cedar 和 Fir 的協定不同,須有相應接收或轉換路徑,不能僅因共用 URL 就認為完成整合。
Log Drain 送不出去怎麼辦?
Logplex 有有限緩衝與重試行為,但不是保證傳送的持久佇列。接收端持續跟不上時,緩衝可能溢位並捨棄記錄,可看到 L10 等缺漏提示。需確認接收程式的持久化、失敗重試與重複處理,不應承諾無損或恰好一次傳送,也不能假設 Fir 一定產生 Cedar 的 L 系列提示。
延伸閱讀
文件核對日期:2026 年 11 月 5 日。
