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を中心に、手順が変わる世代差を示します。
ログとコマンドはドキュメントに基づく例で、実際のアプリへの問い合わせやdrain設定は行っていません。Heroku Logging(英語)・Heroku Telemetry(英語)
最初に押さえること
- Logplexは転送基盤であり、長期ストレージではありません。 対象のCedarアプリでは最新1,500行までを保持し、ログは1週間後に期限切れになります。先に達した制限で古いデータが失われるので、1,500行が約1週間分という意味ではありません。
- sourceとdynoを区別します。 アプリ出力は通常
app、Cedarの基盤コンポーネントはherokuです。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]、その後がメッセージです。2行目は通常の文字列にJSONを付けているため、行全体がJSONオブジェクトではありません。複数ノードから集めるので、到着順がイベント時刻順になる保証もありません。
Logplexの履歴には1,500行と1週間の両方の制限があります。出力量が多ければ、古い行は短時間で入れ替わります。長期検索に使うなら、事前にlogging add-onやLog Drainの保存先を設定します。FirのOTLP経路に同じ履歴バッファーがあると考えてはいけません。
2. heroku logsでtailと絞り込みを行う
以下は読み取りを許可された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は既定でtailになり、heroku logs --app my-fir-app --process-type web でプロセスタイプを絞れます。内部sourceは heroku-router のような heroku- プレフィックスです。Cedarの web.1、source、履歴取得の挙動をそのまま当てはめないでください。CLIのフィルター(英語)
3. ログを使える形にする5つの習慣
- stdout/stderrに出す。 ファイルのログは自動ではプラットフォームのストリームに入りません。フレームワークの設定や明示的な転送が必要です。ファイルに書いた瞬間に消えるわけではありませんが、dynoの一時ファイルシステムを長期保存には使えません。
- 構造化と解析をセットで考える。 JSONやlogfmtは、受信側の解析ルールがあって役立ちます。Herokuの外側の形式とアプリの本文を分け、フィールドが自動で抽出されるとは仮定しません。
- 文脈を残す。 適切なユーザー識別子、
request_id、業務イベントを記録し、必要な最小化やマスキングを行います。HTTPのrequest IDがAPMのtrace_idになるわけではありません。 - レベルとコンポーネントのエラーを分ける。 INFOは適切な業務イベント、ERRORは失敗に使います。ルーターのH12とランタイムのR14は別の条件であり、1件だけで根本原因は確定しません。
- 認証情報を出さない。 パスワード、利用可能な認証情報、完全なカード番号を避け、ユーザーデータは適用される方針に従います。受信設定では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に対応し、syslogではTLSも使えます。syslogはoctet countingでフレームを区切ります。HTTPSは application/logplex-1 のPOST本文でバッチを送り、内部もバイト長で区切ります。JSON配列ではなく、改行だけで分割してよいとも限りません。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は変わります。sourceが app というだけではアプリを区別できません。イベント時刻と受信時刻も分け、順序や遅延を調べられるようにします。
Guanceの DataKit Log Streaming(英語) はHTTPログ受信口を提供しますが、Heroku Logplex drainのネイティブ受信対応を示すものではありません。互換受信プログラムでバッチを展開し、文書化された入力形式とフィールドへ変換します。例えば heroku_app、heroku_source、dyno に文脈を残せますが、これらはマッピング例であり、自動生成される組み込みフィールドではありません。DataKitの source はログの収集元/measurementなので、Herokuのsourceとは区別します。
イベント時刻の解析、永続化と再試行の境界、重複除去、バッファー超過の通知を確認します。HTTP受信口が存在するだけでは、確実な取り込みは証明できません。FirのOTLPも、両側の対応シグナル、転送方式、エンドポイントを別途照合する必要があり、Logplex用の変換だけで対応を確認したことにはなりません。
よくある質問
ログはどれくらい保持されますか?
Logplexを使うCedarでは最新1,500行までで、1週間後にも期限切れとなり、先に達した制限が適用されます。昨日のログが残る場合も、すでに除去されている場合もあります。Firには履歴がなく、Private Space Loggingを有効にしたShield Spaceも同じCLI履歴は提供しません。事後調査に備え、外部転送と保存を事前に設定します。別に保存していない削除済みの記録は、後から取り戻せません。
H12とR14は何を意味しますか?
Cedarの例でH12はルーターのリクエストタイムアウトです。通常は最初の30秒以内に応答データを返さなかった場合で、ストリーミング応答全体を30秒で終える意味ではありません。最初の1バイト以降にはローリングのアイドルタイムアウトがあります。ルーターがエラーを返しても、アプリの処理は続く場合があります。Firは現行の世代別ルーティングとエラー定義を確認し、Cedarのルールすべてを引き継ぐと考えないでください。
R14はメモリ割り当て上限の超過で、該当するCedar Common Runtimeではswap使用に関係します。Private Spacesはswapを使わずR14を出しません。現在のFirもR14を出さないため、記録がないことをメモリが正常な証拠にはできません。エラーコード(英語)・リクエストタイムアウト(英語)
複数アプリのログをまとめられますか?
互換drainを共通受信先へ送り、各アプリの識別とdrain/リソースIDを保持して、アプリ別の検索結果を確認できます。CedarとFirではプロトコルが違うので、対応する受信・変換経路が必要です。同じURLに送るだけでは統一できません。
drainが送信できないとどうなりますか?
Logplexには有限のバッファーと再試行があり、配信を保証する永続キューではありません。受信側が追い付かなければ、バッファー超過でログが失われ、L10などの警告が出る場合があります。受信側の永続化、再試行、重複処理を確認し、無欠落やexactly-onceを約束しないようにします。CedarのL系コードをFirも出すとは限りません。
関連記事
資料確認日:2026年11月5日。
