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つの習慣

  1. stdout/stderrに出す。 ファイルのログは自動ではプラットフォームのストリームに入りません。フレームワークの設定や明示的な転送が必要です。ファイルに書いた瞬間に消えるわけではありませんが、dynoの一時ファイルシステムを長期保存には使えません。
  2. 構造化と解析をセットで考える。 JSONやlogfmtは、受信側の解析ルールがあって役立ちます。Herokuの外側の形式とアプリの本文を分け、フィールドが自動で抽出されるとは仮定しません。
  3. 文脈を残す。 適切なユーザー識別子、request_id、業務イベントを記録し、必要な最小化やマスキングを行います。HTTPのrequest IDがAPMの trace_id になるわけではありません。
  4. レベルとコンポーネントのエラーを分ける。 INFOは適切な業務イベント、ERRORは失敗に使います。ルーターのH12とランタイムのR14は別の条件であり、1件だけで根本原因は確定しません。
  5. 認証情報を出さない。 パスワード、利用可能な認証情報、完全なカード番号を避け、ユーザーデータは適用される方針に従います。受信設定では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日。


最適なプランを相談する

お問い合わせ

コミュニティに参加

WeChatでスキャンして
コミュニティに参加

Guanceを試す

オンラインですぐに始めて、使った分だけお支払いください。

利用を開始

Guanceのプランを選択

コードリポジトリ