最終更新日 2025年02月18日(火)

アドオンパートナーは、アプリのログストリームにデータを挿入することによって、アドオンの開発エクスペリエンスを向上させることができます。この記事では、Logplex​ 経由でアプリのログストリームにサービスを接続する方法について説明します。

セットアップ

アプリの Logplex​ エンドポイントへのアクセス (これにより、アプリのログストリームに書き込む機能が与えられる) を取得するには、まずアドオンのプロビジョニングリクエストで送信した URL を保存する必要があります。マニフェストの requires​ フィールドに "log_input"​ 値を追加すると、その URL は最初のプロビジョニングリクエストとアプリ情報 API​ で使用できるようになります。プロビジョニングリクエストについての詳細は、「アドオンパートナー API の仕様​」を参照してください。以前にプロビジョニングリクエストの log_input_url​ を保存していない場合は、アプリ情報 API を使用してクエリを実行してください。

トランスポート

Logplex にデータを送信するには、HTTP 経由で行う必要があります。keep-alive​ 接続と高密度のペイロードを使用して、顧客のログのすべてを HTTP 経由で Logplex に効率的に配信できます。単純な HTTP リクエストを示す cURL の例を次に示します。

$ URL="https://token:t.01234567-89ab-cdef-0123-456789abcdef@1.us.logplex.io/logs"
$ curl $URL \
  -d "89 <190>1 2013-03-27T20:02:24+00:00 01234567-89ab-cdef-0123-456789abcdef app procid - - foo89 <190>1 2013-03-27T20:02:24+00:00 01234567-89ab-cdef-0123-456789abcdef app procid - - bar" \
  -X "POST" \
  -H "Content-Length: 130" \
  -H "Content-Type: application/logplex-1" \
  -A 'MyAddonName (https://elements.heroku.com/addons/my-addon-name; Ruby/2.1.2)'

この例の URL はあくまでも説明を意図したものです。この URL はアプリによって異なり、資格情報も常に異なります。これらの URL は、ログの書き込みや アプリ情報 API​ からのフェッチを必要とするインストール済みのアドオンごとに保存する必要があります。

特定のアプリの log_input_url​ フィールドは変更される場合があります (資格情報をローテーションする必要がある場合など)。HTTP リクエストで 4xx​ 応答コードが返された場合は、アプリ情報 API​ を使用してアプリの log_input_url​ が変更されていないかどうかを確認してください。変更されている場合は、アプリのレコードを更新して再試行します。

形式

リクエストのヘッダーには、Content-Length​ と Content-Type​ が含まれます。Content-Length​ の値は本体のバイト長を表す整数値です。Content-Type​ の値は application/logplex-1​ です。

HTTP リクエストの本体には、長さで区切られた Syslog パケットが含まれます。Syslog パケットは RFC5424​ で定義されています。次の行は、RFC プロトコルを要約しています。

<prival>version time hostname appname procid msgid structured-data msg

prival​ には <190>​ (local7.info) を、version には 3​ を使用できます。

time​ フィールドはログ行が作成された時刻 (rfc3339​ 形式) に設定されます。

hostname​ はアドオンが関連付けられているアプリの ID に設定されます。

appname​ フィールドは app​ に設定されます。

Logplex は procid​ を使用しませんが、ログを出力しているプロセスを識別するのに最適な方法です。たとえば、heroku-postgres​ とします。

同様に、Logplex は msgid​ や structured-data​ を使用せず、代わりに値 -​ を使用します。

最後に、msg​ はログメッセージが保存されるパケットのセクションです。

メッセージの規則

ログメッセージを、人間が読みやすく、マシンが解析しやすい形式にします。次のようなメッセージを作成してください。

• 1 つのメッセージで構成されるようにします。
• 形式 status=delivered​ のキーと値のペアを使用します。
• マシンまたは環境を区別するためのログ行には source​ のキーと値のペアを使用します。たとえば、source=us-east measure#web.latency=4ms​ とします。
• 具体性の低いものから高いものへの順に、ドットで階層を示します (例: ​measure#queue.backlog=​)。
• 単位は数値のすぐ後に置く必要があり、a-zA-Z​ のみで構成されている必要があります。たとえば、10ms​ とします。

頻度の高いイベント

以下のログイベントは、ログコンシューマーによる統計的な集計でメリットが得られます。

measure#elb.latency.sample_count=67448s source=elb012345.us-east-1d

事前に集計された統計

サービスは定期的に、事前に集計されたメトリクスをユーザーのログストリームに挿入できます。このイベントには、データベーステーブルの合計数、アクティブな接続数、キャッシュの使用状況が含まれます。

sample#tables=30 sample#active-connections=3
sample#cache-usage=72.94 sample#cache-keys=1073002

増分カウンタ

count#db.queries=2 count#db.snapshots=10