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

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

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

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

デフォルト構成

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

デフォルトの構成では、この Logging エージェントがデフォルトのログリストにあるログを Cloud Logging にストリーミングします。追加のログをストリーミングするようにエージェントを構成できます。詳細については、このページの 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 リポジトリをご覧ください。

構成名	型	デフォルト	説明
`format`	string	`/^(?<message>(?<time>[^ ]\s[^ ]* [^ ]) .)$/`	syslog の形式。
`path`	string	`/var/log/syslog`	syslog ファイルのパス。
`pos_file`	string	`/var/lib/google-fluentd/pos/syslog.pos`	このログ入力の位置ファイルのパス。`fluentd` は、このファイルに最後の読み込み場所を記録します。詳細については、`fluentd` ドキュメントをご確認ください。
`read_from_head`	bool	`true`	ログの読み取りをファイルの先頭から始めるかどうか。詳細については、`fluentd` ドキュメントをご確認ください。
`tag`	string	`syslog`	このログ入力のタグ。

`in_forward` 入力プラグインの構成

構成ファイルの場所: /etc/google-fluentd/config.d/forward.conf
説明: このファイルには、in_forward fluentd 入力プラグインの構成が含まれています。in_forward 入力プラグインを使用すると、TCP ソケット経由でログを渡すことができます。
このプラグインと config リポジトリの詳細については、fluentd のドキュメントをご覧ください。

構成名	型	デフォルト	説明
`port`	int	`24224`	モニタリングするポート。
`bind`	string	`127.0.0.1`	モニタリングするバインドアドレス。デフォルトでは、localhost からの接続だけが受け入れられます。この制限を解放するには、この構成を `0.0.0.0` に変更する必要があります。

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

構成ファイルの場所: /etc/google-fluentd/config.d/[APPLICATION_NAME].conf
説明: このディレクトリには、サードパーティアプリケーションのログファイルをログ入力として指定する構成ファイルが保存されています。syslog.conf と forward.conf 以外のファイルは、1 つのアプリケーションを表します（たとえば、apache.conf は Apache アプリケーションを表します）。
config リポジトリをご覧ください。

構成名	型	デフォルト	説明
`format`¹	string	アプリケーションごとに異なる	ログの形式。詳細については、`fluentd` ドキュメントをご確認ください。
`path`	string	アプリケーションごとに異なる	ログファイルのパス。複数のパスを指定する場合は、パスを「,」で区切ります。ウォッチファイルを動的に追加または削除するには、* と strftime 形式を追加します。詳細については、`fluentd` ドキュメントをご確認ください。
`pos_file`	string	アプリケーションごとに異なる	このログ入力の位置ファイルのパス。`fluentd` は、このファイルに最後の読み込み場所を記録します。詳細については、`fluentd` ドキュメントをご確認ください。
`read_from_head`	bool	`true`	ログの読み取りをファイルの先頭から始めるかどうか。詳細については、`fluentd` ドキュメントをご確認ください。
`tag`	string	可変。アプリケーションの名前。	このログ入力のタグ。

¹ <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 リポジトリに移動します。

構成名	型	デフォルト	説明
`buffer_chunk_limit`	string	`512KB`	ログレコードを受信したときに、ダウンストリームコンポーネントに高速で書き込めないレコードは、キューのチャンクに push されます。この構成では、各チャンクのサイズを制限します。デフォルトでは、Logging API で書き込みリクエストあたり 5 MB の推奨チャンクサイズを超えないように、チャンクの上限を慎重に構成しています。API リクエストのログエントリは、すべての追加のメタデータが添付されている元のログサイズの 5 倍から 8 倍になる場合があります。バッファチャンクは、次のいずれかの条件を満たすとフラッシュされます。 1. `flush_interval` が起動している。 2. バッファサイズが `buffer_chunk_limit` に達している。
`flush_interval`	string	`5s`	ログレコードを受信したときに、ダウンストリームコンポーネントに高速で書き込めないレコードは、キューのチャンクに push されます。ここでは、チャンクバッファをフラッシュするまでの時間を構成します。バッファチャンクは、次のいずれかの条件を満たすとフラッシュされます。 1. `flush_interval` が起動している。 2. バッファサイズが `buffer_chunk_limit` に達している。
`disable_retry_limit`	bool	`false`	バッファチャンクのフラッシュが失敗した場合の再試行回数を制限します。詳しくは、`retry_limit`、`retry_wait`、`max_retry_wait` の詳細な仕様を確認してください。
`retry_limit`	int	`3`	バッファチャンクのフラッシュに失敗すると、デフォルトでは `fluentd` が後で再試行されます。ここでは、問題のあるバッファチャンクの削除を開始するまでの再試行回数を構成します。
`retry_wait`	int	`10s`	バッファチャンクのフラッシュに失敗すると、デフォルトでは `fluentd` が後で再試行されます。この構成では、最初の再試行までの待機間隔を秒単位で設定します。`retry_ limit` または `max_retry_wait` に達するまで、再試行のたびに待機間隔が 2 倍になります（20 秒、40 秒、... と増えていきます）。
`max_retry_wait`	int	`300`	バッファチャンクのフラッシュに失敗すると、デフォルトでは `fluentd` が後で再試行されます。待機間隔は再試行のたびに 2 倍になります（20 秒、40 秒、... と増えていきます）。ここでは、最大待機間隔を秒単位で設定します。待機間隔がこの制限に達すると、倍増が停止します。
`num_threads`	int	`8`	出力プラグインで同時に処理可能なログフラッシュの数。
`use_grpc`	bool	`true`	Logging API との通信で REST/JSON の代わりに gRPC を使用するかどうか。gRPC を有効にすると、通常は CPU 使用率が低下します。
`grpc_compression_algorithm`	enum	`none`	gRPC を使用する場合、使用する圧縮スキーマを設定します。`none` または `gzip` のいずれかです。
`partial_success`	bool	`true`	ログの取り込みの部分的な成功をサポートするかどうか。`true` の場合、すべての無効なログエントリが削除され、有効なログエントリが Logging API に正しく取り込まれます。`false` の場合、無効なログエントリが含まれていると、すべてのログエントリが削除されます
`enable_monitoring`	bool	`true`	`true` に設定すると、Logging エージェントは内部テレメトリーをエクスポートします。詳しくは、出力プラグインテレメトリーをご覧ください。
`monitoring_type`	string	`opencensus`	モニタリングのタイプ。サポートされているオプションは `opencensus` と `prometheus` です。詳しくは、出力プラグインテレメトリーをご覧ください。
`autoformat_stackdriver_trace`	bool	`true`	`true` に設定すると、構造化ペイロードの `logging.googleapis.com/trace` フィールドの値が ResourceTrace `traceId` 形式と一致する場合、トレースが再フォーマットされます。自動フォーマットの詳細は、このページの構造化ペイロードの特殊フィールドにあります。

モニタリング構成

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

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 インスタンスでは、デフォルトで有効にはなりません。detect_json オプションが有効な JSON は常に jsonPayload で取り込まれます。

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

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

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

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

JSON ログフィールド	`LogEntry` フィールド	Cloud Logging エージェントの機能	値の例
`severity`	`severity`	Logging エージェントは、Logging API によって認識される LogSeverity 文字列のリストを含む、さまざまな共通の重大度文字列の照合を試みます。	`"severity":"ERROR"`
`message`	`textPayload`（または `jsonPayload` の一部）	ログエクスプローラのログエントリに表示されるメッセージ。	`"message":"There was an error in the application."` 注: Logging エージェントが他の特殊フィールドを移動した後に唯一残ったフィールドであり、かつ `detect_json` が有効でない場合、`message`は `textPayload` として保存されます。これに該当しない場合、`message` は `jsonPayload` に残ります。`detect_json` は、Google Kubernetes Engine などのマネージドロギング環境には適用されません。ログエントリに例外スタックトレースが含まれている場合、例外スタックトレースをこの `message` JSON ログフィールドに設定する必要があります。設定すると、例外スタックトレースが解析され Error Reporting に保存されるようになります。
`log`（以前の Google Kubernetes Engine のみ）	`textPayload`	以前の Google Kubernetes Engine にのみ適用されます。特殊フィールドを移動した後に `log` フィールドだけが残った場合、そのフィールドは `textPayload` として保存されます。
`httpRequest`	`httpRequest`	`LogEntry` `HttpRequest` フィールド形式の構造化レコード。	`"httpRequest":{"requestMethod":"GET"}`
時間関連フィールド	`time`、`timestamp`、など。	詳細については、時間関連フィールドをご覧ください。	`"time":"2020-10-12T07:20:50.52Z"`
`logging.googleapis.com/insertId`	`insertId`	詳細については、`LogEntry` ページの `insertId` をご覧ください。	`"logging.googleapis.com/insertId":"42"`
`logging.googleapis.com/labels`	`labels`	このフィールドの値は構造化レコードにする必要があります。詳細については、`LogEntry` ページの `labels` をご覧ください。	`"logging.googleapis.com/labels":` `{"user_label_1":"value_1","user_label_2":"value_2"}`
`logging.googleapis.com/operation`	`operation`	このフィールドの値は、関連するログエントリをグループ化するためにログエクスプローラによっても使用されます。詳細については、`LogEntry` ページの `operation` をご覧ください。	`"logging.googleapis.com/operation":` `{"id":"get_data","producer":"github.com/MyProject/MyApplication",` `"first":"true"}`
`logging.googleapis.com/sourceLocation`	`sourceLocation`	ログエントリに関連するソースコードの位置情報（存在する場合）。詳細については、`LogEntry` ページの `LogEntrySourceLocation` をご覧ください。	`"logging.googleapis.com/sourceLocation":` `{"file":"get_data.py","line":"142","function":"getData"}`
`logging.googleapis.com/spanId`	`spanId`	ログエントリに関連付けられているトレース内のスパン ID。詳細については、`LogEntry` ページの `spanId` をご覧ください。	`"logging.googleapis.com/spanId":"000000000000004a"`
`logging.googleapis.com/trace`	`trace`	ログエントリに関連するリソースの名前（存在する場合）。詳細については、`LogEntry` ページの `trace` をご覧ください。	`"logging.googleapis.com/trace":"projects/my-projectid/traces/0679686673a"` 注: `stdout` や `stderr` に書き込まない場合、このフィールドの値は、`projects/[PROJECT-ID]/traces/[TRACE-ID]` 形式にする必要があります。これにより、ログエクスプローラとトレースビューアで、ログエントリをグループ化してトレースと一緒に表示できます。`autoformat_stackdriver_trace` が true で、`[V]` が ResourceTrace の `traceId` の形式と一致する場合、LogEntry の `trace` フィールドの値は `projects/[PROJECT-ID]/traces/[V]` になります。
`logging.googleapis.com/trace_sampled`	`traceSampled`	このフィールドの値は `true` または `false` のいずれかにする必要があります。詳細については、`LogEntry` ページの `traceSampled` をご覧ください。	`"logging.googleapis.com/trace_sampled": false`

時間関連フィールド

Logging エージェントは、複数の JSON 形式の時間関連フィールドを受け取って処理できます。次の JSON タイムスタンプ表現の 1 つが構造化レコードに存在する場合、jsonPayload からそのフィールドが移動されて、LogEntry オブジェクトの timestamp フィールドの単一の表現にまとめられます。

jsonPayload には、seconds フィールドと nanos フィールドを含む timestamp フィールドが含まれます。前者は UTC エポックからの経過秒数を示す符号付き秒数、後者は値が負でない小数点以下の秒数を表します。
```
{
  "timestamp": {
    "seconds": CURRENT_SECONDS,
    "nanos": CURRENT_NANOS
  }
}
```
jsonPayload には、timestampSeconds フィールドと timestampNanos フィールドの両方が含まれます。
```
{
   "timestampSeconds": CURRENT_SECONDS,
   "timestampNanos": CURRENT_NANOS
}
```
jsonPayload に含まれる time フィールドには、同じ秒数の情報が RFC 3339 の定義に沿って文字列として書き込まれます。
```
{
    "time": CURRENT_TIME_RFC3339
}
```

Logging エージェントでタイムスタンプ表現が 1 つ検出されると、構造化レコードに許容可能な形式の他の表現が存在する場合でも、タイムスタンプ関連の処理はそれ以上行われません。

エージェント構成のカスタマイズ

デフォルトで 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 に追加のログを送信できます。

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

Linux のコマンドプロンプトで、ログファイルを作成します。
```
touch /tmp/test-unstructured-log.log
```

追加の構成ディレクトリ /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

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

エージェントを再起動して、構成の変更を適用します。
```
sudo service google-fluentd restart
```

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

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

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

  {
   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 エージェントを構成するには、次のようにします。

Linux のコマンドプロンプトで、ログファイルを作成します。
```
touch /tmp/test-structured-log.log
```

追加の構成ディレクトリ /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

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

エージェントを再起動して、構成の変更を適用します。
```
sudo service google-fluentd restart
```

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

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

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

{
 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 プラグインを使用してログを送信するには、以下の説明をお読みください。

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

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

  {
   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 のモニタリング対象リソースの種類のリストをご覧ください。

構成名	型	デフォルト	説明
`label_map`	hash	nil	`label_map`（JSON オブジェクトとして指定）は、順不同の `fluentd` フィールド名のセットです。この値は構造化ペイロードの一部ではなく、ラベルとして送信されます。マップの各エントリは {`field_name`: `label_name`} のペアです。`field_name`（入力プラグインで解析）が検出されると、対応する `label_name` のラベルがログエントリに追加されます。フィールドの値はラベルの値として使用されます。このマップにより、ラベル名を柔軟に指定できます。たとえば、`fluentd` フィールド名では使用できない文字を使用できます。構造化ログエントリのラベルの設定をご覧ください。
`labels`	hash	nil	`labels`（JSON オブジェクトとして指定）は、構成時に提供されるカスタムラベルのセットです。追加の環境情報をすべてのメッセージに挿入したり、自動的に検出されたラベルをカスタマイズしたりできます。マップの各エントリは {`label_name`: `label_value`} のペアです。

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 エージェントの内部バッファ機構を調整できます。

構成名	型	デフォルト	説明
`buffer_type`	string	`buf_memory`	Logging API に高速で書き込めないレコードは、バッファに push されます。バッファはメモリ内または実際のファイルに存在します。推奨値: `buf_file`デフォルトの `buf_memory` は高速ですが、持続性がありません。ログを失う危険性があります。`buffer_type` が `buf_file` の場合、`buffer_path` も指定する必要があります。
`buffer_path`	string	ユーザーによる設定	バッファチャンクが格納されているパス。`buffer_type` が `file` の場合、このパラメータは必須です。競合状態を避けるために、この構成は一意でなければなりません。
`buffer_queue_limit`	int	`64`	チャンクキューの長さ制限を指定します。バッファキューがこのチャンク数に達すると、バッファの動作は `buffer_queue_full_action` によって制御されます。デフォルトでは、例外をスローします。このオプションと `buffer_chunk_limit` により、`fluentd` がバッファリングに使用できる最大ディスク容量が決まります。
`buffer_queue_full_action`	string	`exception`	バッファキューがいっぱいになったときのバッファの動作を制御します。可能な値: 1. `exception`: キューがいっぱいになったときに `BufferQueueLimitError` をスローします。`BufferQueueLimitError` の処理方法は入力プラグインによって異なります。たとえば、`in_forward` 入力プラグインがエラーを返したときに、`in_tail` 入力プラグインは新しい行の読み取りを停止します。 2. `block`: バッファがいっぱいになる状態が解消されるまで入力プラグインスレッドを停止します。このアクションはバッチのユースケースに適しています。`fluentd` では、`BufferQueueLimitError` を回避するためにブロックアクションを指定することはおすすめしません。`BufferQueueLimitError` が頻繁に発生する場合は、トラフィックの送信先で空き容量が不足している可能性があります。 3. `drop_oldest_chunk`: 最も古いチャンクを削除します。

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

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

構成名	型	デフォルト	説明
`project_id`	string	nil	これを指定すると、Logging エージェントが実行されている Google Cloud または AWS プロジェクトを表す `project_id` がオーバーライドされます。
`zone`	文字列	nil	これを指定すると、ゾーンがオーバーライドされます。
`vm_id`	string	nil	これを指定すると、VM ID がオーバーライドされます。
`vm_name`	string	nil	これを指定すると、VM 名がオーバーライドされます。

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

構成名	型	デフォルト	説明
`detect_json`¹	bool	`false`	ログレコードが、解析が必要な JSON コンテンツを含むテキストログエントリかどうかを検出します。このオプションが `true` で、JSON 形式のように構造化されていない（テキスト）ログエントリが検出されると、解析され、構造化（JSON）ペイロードとして送信されます。
`coerce_to_utf8`	bool	`true`	ユーザーログに UTF-8 以外の文字を許可するかどうか。`true` に設定されている場合、UTF-8 以外の文字は `non_utf8_replacement_string` で指定された文字列に置き換えられます。`false` に設定すると、UTF-8 以外の文字があるとプラグインでエラーが発生します。
`require_valid_tags`	bool	`false`	無効なタグを含むログエントリを拒否するかどうか。このオプションを `false` に設定すると場合、文字列以外のタグを文字列に変換し、UTF-8 以外の無効な文字をサニタイズして、タグを有効にします。
`non_utf8_replacement_string`	string	`""`（スペース）	`coerce_to_utf8` が `true` に設定されている場合、UTF-8 以外の文字はここで指定された文字列に置き換えられます。

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

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

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

Linux インスタンス

構成ファイルを次のディレクトリにコピーします。
```
/etc/google-fluentd/config.d/
```
Logging エージェントのインストールスクリプトによって、このディレクトリにデフォルトのキャッチオール構成ファイルが移入されます。詳しくは、Logging エージェントのソースコードを入手するをご覧ください。
省略可。次のコマンドを実行して、構成の変更を検証します。
```
sudo service google-fluentd configtest
```
次のコマンドを実行してエージェントを再起動します。
```
sudo service google-fluentd force-reload
```

Windows インスタンス

構成ファイルをエージェントのインストールディレクトリの config.d サブディレクトリにコピーします。デフォルトのインストールディレクトリを使用している場合、このディレクトリは次のようになります。
```
C:\Program Files (x86)\Stackdriver\LoggingAgent\config.d\
```
コマンドラインシェルで次のコマンドを実行して、エージェントを再起動します。
```
net stop  StackdriverLogging
net start StackdriverLogging
```

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

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

デフォルト構成

デフォルト構成の定義

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

Syslog の構成

in_forward 入力プラグインの構成

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

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

モニタリング構成

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

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

ペイロードの処理

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

時間関連フィールド

エージェント構成のカスタマイズ

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

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

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

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

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

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

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

ラベルを静的に設定する

ログレコードの変更

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

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

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

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

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

Linux インスタンス

Windows インスタンス

`in_forward` 入力プラグインの構成

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

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

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

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

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