Logging エージェントを構成する

このページでは、Cloud Logging エージェントのデフォルト構成とカスタム構成の詳細について説明します。

大部分のユーザーは、このページをお読みいただく必要はありません。次の場合には、このページをお読みください。

• Cloud Logging エージェントの構成に関する詳細な技術情報を学ぶ場合。

• Cloud Logging エージェントの構成を変更する必要がある場合。

デフォルト構成

Logging エージェント google-fluentd は、fluentd ログデータ コレクタに変更を加えたものです。ほとんどの場合、Logging エージェントのデフォルト構成を変更する必要はありません。

デフォルトの構成では、Logging エージェントはデフォルトのログのリストにあるログを Cloud Logging にストリーミングします。追加のログをストリーミングするようにエージェントを構成できます。詳細については、このページの Logging エージェント構成のカスタマイズをご覧ください。

Logging エージェントは、fluentd 入力プラグインを使用して外部ソース（ディスク上のファイルなど）からイベントログを取得または pull します。また、受信したログレコードの解析を行います。入力プラグインはエージェントにバンドルされています。また、Ruby Gems で別途インストールすることもできます。詳細は、バンドル プラグインのリストをご確認ください。

エージェントは、VM インスタンスで fluentd の組み込み in_tail プラグインを介して、ログファイルに保存されているログレコードを読み取ります。ログレコードのそれぞれが、Cloud Logging のログエントリ構造に変換されます。ログレコードのコンテンツの大半はログエントリのペイロードに記録されますが、ログエントリには、タイムスタンプや重大度などの標準要素も含まれています。Logging エージェントで処理するには、各ログレコードに文字列形式のタグが付いている必要があります。クエリと出力プラグインは一連のタグを照合します。通常、ログの名前は projects/[PROJECT-ID]/logs/[TAG] という形式になります。次のログの名前には structured-log というタグが付いています。

projects/my-sample-project-12345/logs/structured-log

出力プラグインは、内部構造メッセージを Cloud Logging のログエントリに変換します。ペイロードはテキストまたは JSON ペイロードになります。

以降のセクションでは、デフォルト構成について詳しく説明します。

デフォルト構成の定義

以降のセクションでは、syslog、転送入力プラグイン、サードパーティのアプリケーション ログ（デフォルトログのリストにあるログなど）の入力構成、Google Cloud fluentd 出力プラグインのデフォルト構成の定義について説明します。

ルート構成ファイルの場所

• Linux: /etc/google-fluentd/google-fluentd.conf

  このルート構成ファイルは、/etc/google-fluentd/config.d フォルダからのすべての構成ファイルも読み込みます。

• Windows: C:\Program Files (x86)\Stackdriver\LoggingAgent\fluent.conf

  v1-5 以前の Logging エージェントを実行している場合、場所は C:\GoogleStackdriverLoggingAgent\fluent.conf です。

syslog の構成

• 構成ファイルの場所: /etc/google-fluentd/config.d/syslog.conf

• 説明: このファイルには、syslog をログ入力として指定する構成が含まれています。

• config リポジトリをご覧ください。

in_forward 入力プラグインの構成

• 構成ファイルの場所: /etc/google-fluentd/config.d/forward.conf

• 説明: このファイルには、in_forward fluentd 入力プラグインの構成が含まれています。in_forward 入力プラグインを使用すると、TCP ソケット経由でログを渡すことができます。

• このプラグインと config リポジトリの詳細については、fluentd のドキュメントをご覧ください。

サードパーティのアプリケーション ログの入力構成

• 構成ファイルの場所: /etc/google-fluentd/config.d/[APPLICATION_NAME].conf

• 説明: このディレクトリには、サードパーティ アプリケーションのログファイルをログ入力として指定する構成ファイルが保存されています。syslog.conf と forward.conf 以外のファイルは、1 つのアプリケーションを表します（たとえば、apache.conf は Apache アプリケーションを表します）。

• config リポジトリをご覧ください。

¹ <parse> スタンザを使用している場合は、@type を使用してログの形式を指定します。

Google Cloud fluentd 出力プラグインの構成

• 構成ファイルの場所:

  • Linux: /etc/google-fluentd/google-fluentd.conf

  • Windows: C:\Program Files (x86)\Stackdriver\LoggingAgent\fluent.conf

    v1-5 以前の Logging エージェントを実行している場合、場所は C:\GoogleStackdriverLoggingAgent\fluent.conf です。

• 説明: このファイルには、Google Cloud fluentd 出力プラグインの動作を制御するための構成オプションが含まれます。

• config リポジトリに移動します。

モニタリング構成

出力プラグイン テレメトリー

enable_monitoring オプションは、Google Cloud fluentd 出力プラグインが内部テレメトリーを収集するかどうかを制御します。true に設定した場合、Logging エージェントは、Cloud Logging に送信するようリクエストされているログエントリの数と、Cloud Logging によって正常に取り込まれたログエントリの数を追跡します。false に設定すると、出力プラグインによって指標が収集されなくなります。

monitoring_type オプションは、エージェントによってこのテレメトリーを公開する方法を制御します。指標のリストについては、以下をご覧ください。

prometheus に設定すると、Logging エージェントは Prometheus エンドポイントの Prometheus 形式で指標を公開します（デフォルトでは localhost:24231/metrics。このデフォルトのカスタマイズについて詳しくは、prometheus プラグインと prometheus_monitor プラグインの構成をご覧ください）。Compute Engine VM で、これらの指標が Monitoring API に書き込まれるようにするには、Monitoring エージェントをインストールして実行する必要があります。

opencensus（デフォルトは v1.6.25 以降）に設定すると、Logging エージェントは独自の健全性の指標を Monitoring API に直接書き込みます。この場合、Monitoring エージェントがインストールされていなくても、roles/monitoring.metricWriter ロールを Compute Engine のデフォルトのサービス アカウントに付与する必要があります。

次の指標は、Monitoring エージェントと Logging エージェントの両方により、opencensus モードで Monitoring API に書き込まれます。

• version ラベルを持つ agent.googleapis.com/agent/uptime: Logging エージェントの稼働時間。
• response_code ラベルを持つ agent.googleapis.com/agent/log_entry_count: Logging エージェントによって書き込まれたログエントリの数。
• response_code ラベルを持つ agent.googleapis.com/agent/log_entry_retry_count: Logging エージェントによって書き込まれたログエントリの数。
• response_code ラベルを持つ agent.googleapis.com/agent/request_count: Logging エージェントからの API リクエストの数。

これらの指標の詳細については、エージェントの指標のページをご覧ください。

さらに、次の Prometheus 指標は、prometheus モードで出力プラグインにより公開されます。

• version ラベルを持つ uptime: Logging エージェントの稼働時間。
• grpc ラベルと code ラベルを持つ stackdriver_successful_requests_count: Logging API への成功したリクエストの数。
• grpc ラベルと code ラベルを持つ stackdriver_failed_requests_count: Logging API に対する失敗したリクエストの数。エラーコードで分類されます。
• grpc ラベルと code ラベルを持つ stackdriver_ingested_entries_count: Logging API によって取り込まれたログエントリの数。
• grpc ラベルと code ラベルを持つ stackdriver_dropped_entries_count: Logging API で拒否されたログエントリの数。
• grpc ラベルと code ラベルを持つ stackdriver_retried_entries_count: 一時的なエラーで Google Cloud fluentd 出力プラグインが取り込みに失敗し、再試行されたログエントリの数。

prometheus プラグインと prometheus_monitor プラグインの構成

• 構成ファイルの場所: /etc/google-fluentd/google-fluentd.conf

• 説明: このファイルには、prometheus プラグインと prometheus_monitor プラグインの動作を制御する構成オプションが含まれています。prometheus_monitor プラグインは、Fluentd のコア インフラストラクチャをモニタリングします。prometheus プラグインは、prometheus_monitor プラグインの指標と上記の google_cloud プラグインの指標を含む指標を、Prometheus 形式でローカルポートから公開します。詳しくは、https://docs.fluentd.org/deployment/monitoring-prometheus をご覧ください。

• config リポジトリに移動します。

Fluentd をモニタリングするため、組み込みの Prometheus http 指標サーバーはデフォルトで有効になります。このエンドポイントの起動を停止するには、構成から次のセクションを削除します。

# Prometheus monitoring.
<source>
  @type prometheus
  port 24231
</source>
<source>
  @type prometheus_monitor
</source>

ペイロードの処理

Logging エージェントのデフォルト構成でサポートされているログのほとんどは、ログファイルからのもので、ログエントリに非構造化（テキスト）ペイロードとして取り込まれます。

ただし、デフォルトで有効になっている in_forward 入力プラグインは、構造化ログのみを受け入れ、ログエントリに構造化（JSON）ペイロードを取り込みます。詳細については、このページの構造化（JSON）ログレコードを in_forward プラグインでストリーミングするをご覧ください。

ログ行がシリアル化された JSON オブジェクトであり、detect_json オプションが有効になっている場合、出力プラグインによってログエントリが構造化（JSON）ペイロードに変換されます。このオプションは、App Engine フレキシブル環境と Google Kubernetes Engine で実行されている VM インスタンスにおいて、デフォルトで有効になっています。App Engine スタンダード環境で実行される VM インスタンスでは、デフォルトで有効にはなりません。すべての JSON を detect_json で解析するオプションは、常に jsonPayload で取り込まれます。

追加のリソースから構造化ログを取り込むように、エージェントの構成をカスタマイズできます。詳細については、Cloud Logging に構造化（JSON）ログレコードをストリーミングするをご覧ください。

カスタム構成の Logging エージェントでストリーミングされるログレコードのペイロードは、単一の非構造化テキスト メッセージ（textPayload）か、構造化 JSON メッセージ（jsonPayload）のいずれかになります。

構造化ペイロードの特殊フィールド

Logging エージェントは、構造化されたログレコードを受け取ると、次の表に一致するすべてのキーを LogEntry オブジェクトの対応するフィールドに移動します。それ以外の場合、キーは LogEntry.jsonPayload フィールドの一部になります。これにより、LogEntry オブジェクト内に特定のフィールドを設定できます。このオブジェクトは Logging API に書き込まれます。たとえば、構造化ログレコードに severity というキーが含まれている場合、Logging エージェントはこの値を LogEntry.severity フィールドに設定します。

時間関連フィールド

一般に、ログエントリに関する時間関連の情報は、LogEntry オブジェクトの timestamp フィールドに格納されます。

{
insertId: "1ad8d08f-6529-47ea-832e-467f869a2da4"
...
resource: {2}
timestamp: "2023-10-30T16:33:15.505196Z"
}

ログエントリのソースが構造化データの場合、Logging エージェントは次のルールを使用して、jsonPayload エントリのフィールドで時間関連の情報を検索します。

1. JSON オブジェクトである timestamp フィールドを検索します。これには seconds フィールドと nanos フィールドが含まれます。前者は UTC エポックからの経過秒数を示す符号付き秒数、後者は値が負でない小数点以下の秒数を表します。

   jsonPayload: {
     ...
     "timestamp": {
       "seconds": CURRENT_SECONDS,
       "nanos": CURRENT_NANOS
     }
   }
   

2. 前の検索が失敗した場合は、timestampSeconds フィールドと timestampNanos フィールドのペアを検索します。

   jsonPayload: {
     ...
     "timestampSeconds": CURRENT_SECONDS,
     "timestampNanos": CURRENT_NANOS
   }
   

3. 前の検索が失敗した場合は、RFC 3339 形式の文字列である time フィールドを検索します。

   jsonPayload: {
     ...
     "time": CURRENT_TIME_RFC3339
   }
   

時間関連の情報が見つかると、Logging エージェントはその情報を使用して LogEntry.timestamp の値を設定します。その情報は構造化レコードから LogEntry.jsonPayload オブジェクトにコピーされません。

LogEntry.timestamp フィールドの値の設定に使用されていない時間関連フィールドは、構造化レコードから LogEntry.jsonPayload オブジェクトにコピーされます。たとえば、構造化レコードに timestamp JSON オブジェクトと time フィールドが含まれている場合、timestamp JSON オブジェクト内のデータを使用して LogEntry.timestamp フィールドを設定します。LogEntry.jsonPayload オブジェクトには time フィールドが含まれています。これは、このフィールドが LogEntry.timestamp 値の設定に使用されなかったためです。

エージェント設定のカスタマイズ

デフォルトで Logging エージェントがストリーミングするデフォルトのログのリストだけでなく、Logging エージェントをカスタマイズして、Logging に追加のログを送信できます。また、入力構成を追加してエージェント設定を調整することもできます。

ここで説明する定義は fluent-plugin-google-cloud 出力プラグインにのみ適用されます。この構成では、ログが変換されて Cloud Logging に取り込まれる方法を指定します。

• メイン構成ファイルの場所:

  • Linux: /etc/google-fluentd/google-fluentd.conf

  • Windows: C:\Program Files (x86)\Stackdriver\LoggingAgent\fluent.conf

    v1-5 以前の Logging エージェントを実行している場合、場所は C:\GoogleStackdriverLoggingAgent\fluent.conf です。

• 説明: このファイルには、fluent-plugin-google-cloud 出力プラグインの動作を制御する構成オプションが含まれています。

• config リポジトリをご覧ください。

追加入力からログをストリーミングする

Logging エージェントをカスタマイズして入力構成を追加し、Logging に追加のログを送信できます。

ログファイルを使用して非構造化（テキスト）ログをストリーミングする

1. Linux のコマンド プロンプトで、ログファイルを作成します。

   touch /tmp/test-unstructured-log.log
   

2. 追加の構成ディレクトリ /etc/google-fluentd/config.d に test-unstructured-log.conf のラベルを付した新しい構成ファイルを作成します。

   sudo tee /etc/google-fluentd/config.d/test-unstructured-log.conf <<EOF
   <source>
       @type tail
       <parse>
           # 'none' indicates the log is unstructured (text).
           @type none
       </parse>
       # The path of the log file.
       path /tmp/test-unstructured-log.log
       # The path of the position file that records where in the log file
       # we have processed already. This is useful when the agent
       # restarts.
       pos_file /var/lib/google-fluentd/pos/test-unstructured-log.pos
       read_from_head true
       # The log tag for this log input.
       tag unstructured-log
   </source>
   EOF
   

   新しいファイルを作成する代わりに、既存の構成ファイルに構成情報を追加することもできます。

3. エージェントを再起動して、構成の変更を適用します。

   sudo service google-fluentd restart
   

4. ログファイルにログレコードを生成します。

   echo 'This is a log from the log file at test-unstructured-log.log' >> /tmp/test-unstructured-log.log
   

5. ログ エクスプローラで、取り込んだログエントリを確認します。

   {
     insertId:  "eps2n7g1hq99qp"
     labels: {
     compute.googleapis.com/resource_name:  "add-unstructured-log-resource"
     }
     logName:  "projects/my-sample-project-12345/logs/unstructured-log"
     receiveTimestamp:  "2018-03-21T01:47:11.475065313Z"
     resource: {
     labels: {
       instance_id:  "3914079432219560274"
       project_id:  "my-sample-project-12345"
       zone:  "us-central1-c"
     }
     type:  "gce_instance"
     }
     textPayload:  "This is a log from the log file at test-unstructured-log.log"
     timestamp:  "2018-03-21T01:47:05.051902169Z"
   }
   

ログファイルを使用して構造化ログ（JSON）をストリーミングする

特定のログ入力の各ログエントリを構造化するように Logging エージェントを構成できます。Logging エージェントをカスタマイズして、ログファイルから JSON 形式のコンテンツを取り込むこともできます。エージェントが JSON コンテンツを取り込むように構成する場合、各 JSON オブジェクトが改行されるように、入力をフォーマットする必要があります。

    {"name" : "zeeshan", "age" : 28}
    {"name" : "reeba", "age" : 15}

JSON 形式のコンテンツを取り込むように Logging エージェントを構成するには、次のようにします。

1. Linux のコマンド プロンプトで、ログファイルを作成します。

   touch /tmp/test-structured-log.log
   

2. 追加の構成ディレクトリ /etc/google-fluentd/config.d に test-structured-log.conf のラベルを付した新しい構成ファイルを作成します。

   sudo tee /etc/google-fluentd/config.d/test-structured-log.conf <<EOF
   <source>
       @type tail
       <parse>
           # 'json' indicates the log is structured (JSON).
           @type json
       </parse>
       # The path of the log file.
       path /tmp/test-structured-log.log
       # The path of the position file that records where in the log file
       # we have processed already. This is useful when the agent
       # restarts.
       pos_file /var/lib/google-fluentd/pos/test-structured-log.pos
       read_from_head true
       # The log tag for this log input.
       tag structured-log
     </source>
     EOF
   

   新しいファイルを作成する代わりに、既存の構成ファイルに構成情報を追加することもできます。

3. エージェントを再起動して、構成の変更を適用します。

   sudo service google-fluentd restart
   

4. ログファイルにログレコードを生成します。

   echo '{"code": "structured-log-code", "message": "This is a log from the log file at test-structured-log.log"}' >> /tmp/test-structured-log.log
   

5. ログ エクスプローラで、取り込んだログエントリを確認します。

   {
     insertId:  "1m9mtk4g3mwilhp"
     jsonPayload: {
     code:  "structured-log-code"
     message:  "This is a log from the log file at test-structured-log.log"
     }
     labels: {
     compute.googleapis.com/resource_name:  "add-structured-log-resource"
     }
     logName:  "projects/my-sample-project-12345/logs/structured-log"
     receiveTimestamp:  "2018-03-21T01:53:41.118200931Z"
     resource: {
     labels: {
       instance_id:  "5351724540900470204"
       project_id:  "my-sample-project-12345"
       zone:  "us-central1-c"
     }
     type:  "gce_instance"
     }
     timestamp:  "2018-03-21T01:53:39.071920609Z"
   }
   

   ログ エクスプローラで、リソースタイプと structured-log の logName でフィルタします。

一般的なサードパーティ アプリケーションのログ入力形式をカスタマイズする方法については、一般的なログ形式と解析方法をご覧ください。

in_forward プラグインを使用して構造化ログ（JSON）をストリーミングする

fluentd in_forward プラグインを使用してログを送信することもできます。fluentd-cat は、in_forward プラグインにログを簡単に送信できる組み込みツールです。このツールについて詳しくは、fluentd のドキュメントをご覧ください。

fluentd in_forward プラグインを使用してログを送信するには、以下の説明をお読みください。

1. Logging エージェントがインストールされている VM で、次のコマンドを実行します。

   echo '{"code": "send-log-via-fluent-cat", "message": "This is a log from in_forward plugin."}' | /opt/google-fluentd/embedded/bin/fluent-cat log-via-in-forward-plugin
   

2. ログ エクスプローラで、取り込んだログエントリを確認します。

   {
     insertId:  "1kvvmhsg1ib4689"
     jsonPayload: {
     code:  "send-log-via-fluent-cat"
     message:  "This is a log from in_forward plugin."
     }
     labels: {
     compute.googleapis.com/resource_name:  "add-structured-log-resource"
     }
     logName:  "projects/my-sample-project-12345/logs/log-via-in-forward-plugin"
     receiveTimestamp:  "2018-03-21T02:11:27.981020900Z"
     resource: {
     labels: {
       instance_id:  "5351724540900470204"
       project_id:  "my-sample-project-12345"
       zone:  "us-central1-c"
     }
     type:  "gce_instance"
     }
     timestamp:  "2018-03-21T02:11:22.717692494Z"
   }
   

アプリケーション コードから構造化ログ（JSON）レコードをストリーミングする

アプリケーション コードから構造化ログを送信するには、さまざまな言語のコネクタを有効にします。詳細については、fluentdドキュメントをご覧ください。 これらのコネクタは、in_forward プラグインをベースに作成されています。

ログエントリにラベルを設定する

以下の構成オプションを使用すると、Cloud Logging にログを取り込むときに、LogEntry ラベルと MonitoredResource ラベルをオーバーライドできます。すべてのログエントリはモニタリング対象リソースに関連付けられます。詳しくは Cloud Logging のモニタリング対象リソースの種類のリストをご覧ください。

Logging エージェント出力プラグインでは、次の 3 つの方法で LogEntry ラベルを設定できます。

• 構造化エントリの特定のラベルを別のラベルに動的に置き換える。詳細しくは、このページの構造化ログエントリのラベルの設定をご覧ください。
• 値が出現するたびに、静的にラベルを設定する。詳しくは、このページのラベルを静的に設定するをご覧ください。

構造化ログエントリにラベルを設定する

次のような構造化ログエントリのペイロードを作成したとします。

{ "message": "This is a log message", "timestamp": "Aug 10 20:07:00", "env": "production" }

また、上記のペイロード フィールド env をメタデータ ラベル environment に変換します。これを行うには、メインの構成ファイル（Linux の場合は /etc/google-fluentd/google-fluentd.conf、Windows の場合は C:\Program Files (x86)\Stackdriver\LoggingAgent\fluent.conf）の出力プラグイン構成に以下を追加します。

# Configure all sources to output to Cloud Logging
<match **>
  @type google_cloud
  label_map {
    "env": "environment"
  }
  ...
</match>

ここで、label_map 設定は、ペイロードの env ラベルを environment に置き換えるため、ログエントリに値が production のラベル environment が生成されます。

ラベルを静的に設定する

ペイロードにこの情報がなく、単に environment という静的メタデータ ラベルを追加する場合は、メイン構成ファイル（Linux の場合は /etc/google-fluentd/google-fluentd.conf、Windows の場合は C:\Program Files (x86)\Stackdriver\LoggingAgent\fluent.conf）の出力プラグイン構成に以下を追加します。

# Configure all sources to output to Cloud Logging
<match **>
  @type google_cloud
  labels {
    "environment": "production"
  }
  ...
</match>

この場合、マップを使用して別のラベルに置き換えるのではなく、既存のラベルがあるかどうかにかかわらず、labels 設定を使用して特定のリテラル値にラベルを添付します。このアプローチは、非構造化ログの送信中でも使用できます。

labels、label_map、その他の Logging エージェント設定の構成方法については、このページのログエントリにラベルを設定するをご覧ください。

ログレコードの変更

Fluentd の組み込みフィルタ プラグインを使用して、ログエントリを変更できます。

最も一般的なフィルタ プラグインは filter_record_transformer です。これを使用して、次のことが可能になります。

• ログエントリに新しいフィールドを追加する
• ログエントリのフィールドを更新する
• ログエントリのフィールドを削除する

ログエントリの変更が可能な出力プラグインは他にもあります。fluent-plugin-record-reformer 出力プラグインは、filter_record_transformer フィルタ プラグインに似た機能を提供するだけでなく、ログのタグを変更することもできます。このプラグインではリソースの使用量が多くなります。ログのタグが更新されるたびに、新しいタグが含まれる新しいログエントリが生成されるためです。なお、構成には tag フィールドが必要であるので注意してください。このフィールドに変更を加えて、デッドループを回避することもおすすめします。

fluent-plugin-detect-exceptions 出力プラグインは、複数行の例外スタック トレースのログストリームをスキャンします。ログストリームは非構造化（テキスト）ログレコードまたは JSON 形式のログレコードです。一連のログエントリから例外スタック トレースが形成される場合、ログエントリは結合された 1 つのログメッセージとして転送されます。それ以外の場合、ログエントリはそのまま転送されます。

デフォルト以外の高度な構成の定義

Logging エージェントの構成をカスタマイズして、デフォルトの構成を変更する場合は、このページを引き続きご覧ください。

バッファ関連の構成オプション

以下の構成オプションを使用すると、Logging エージェントの内部バッファ機構を調整できます。

プロジェクト関連の構成オプションとモニタリング対象リソース関連の構成オプション

以下の構成オプションでは、MonitoredResource オブジェクトからプロジェクトと特定のフィールドを手動で指定できます。これらの値は、Logging エージェントによって自動的に収集されます。手動で指定することはおすすめしません。

その他の出力プラグイン構成オプション

¹ この機能は、App Engine フレキシブル環境と Google Kubernetes Engine で実行されている VM インスタンスにおいて、デフォルトで有効になっています。

カスタマイズされたエージェント構成を適用する

Logging エージェントをカスタマイズすると、独自の fluentd 構成ファイルを追加できるようになります。

fluentd 構成ファイルについての詳細は、fluentd の構成ファイル構文のドキュメントをご覧ください。