エージェントの構成

このページでは、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 リポジトリをご覧ください。

構成名 デフォルト 説明
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 文字列 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.confforward.conf 以外のファイルは、1 つのアプリケーションを表します(たとえば、apache.conf は Apache アプリケーションを表します)。

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

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

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 文字列 512KB ログレコードを受信したときに、ダウンストリーム コンポーネントに高速で書き込めないレコードは、キューのチャンクに push されます。この構成では、各チャンクのサイズを制限します。デフォルトでは、Logging API で書き込みリクエストあたり 5 MB の推奨チャンクサイズを超えないように、チャンク制限を慎重に構成しています。API リクエストのログエントリは、すべての追加のメタデータが添付されている元のログサイズの 5 倍から 8 倍になる場合があります。バッファ チャンクは、次のいずれかの条件を満たすとフラッシュされます。
1. flush_interval が起動している。
2. バッファサイズが buffer_chunk_limit に達している。
flush_interval 文字列 5s ログレコードを受信したときに、ダウンストリーム コンポーネントに高速で書き込めないレコードは、キューのチャンクに push されます。ここでは、チャンク バッファをフラッシュするまでの時間を構成します。バッファ チャンクは、次のいずれかの条件を満たすとフラッシュされます。
1. flush_interval が起動している。
2. バッファサイズが buffer_chunk_limit に達している。
disable_retry_limit bool false バッファ チャンクのフラッシュが失敗した場合の再試行回数を制限します。詳しくは、retry_limitretry_waitmax_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 使用率が低下します。
partial_success bool true ログの取り込みの部分的な成功をサポートするかどうか。true の場合、すべての無効なログエントリが削除され、有効なログエントリが Logging API に正しく取り込まれます。false の場合、無効なログエントリが含まれていると、すべてのログエントリが削除されます
enable_monitoring bool true true に設定すると、Cloud Logging エージェントは 2 つの指標を公開します。1 つは、Cloud Logging に送信するようリクエストされているログエントリの数を記録するリクエスト数の指標で、もう 1 つは Cloud Logging によって正常に取り込まれたログエントリの実際の数を記録する取り込みエントリ数です。falseの場合、これらの指標は公開されません。
monitoring_type 文字列 prometheus モニタリングのタイプ。現在使用できるオプションは prometheus だけですが、今後はオプションが追加される可能性があります。enable_monitoringtrue で、monitoring_typeprometheus の場合、Logging エージェントは localhost:24231/metrics にローカル指標の一部を Prometheus 形式で公開します。詳細をご覧ください。
autoformat_stackdriver_trace bool true true に設定すると、構造化ペイロードの logging.googleapis.com/trace フィールドの値が ResourceTrace traceId 形式と一致する場合、トレースは再フォーマットされます。自動フォーマットの詳細は、このページの構造化ペイロードの特殊フィールドにあります。

ペイロードの処理

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 エージェントが構造化ログレコードを受信すると、次のフィールドを特殊なフィールドとして扱います。これにより、Stackdriver Logging API に書き込まれる LogEntry オブジェクトに特殊フィールドを設定できます。

次の表のすべてのフィールドは、存在する場合、ペイロードから削除されます。

JSON ログフィールド LogEntry フィールド Logging エージェント機能
severity severity Logging エージェントは、共通の重大度文字列の比較を行います。この中には、Logging API によって認識される LogSeverity 文字列のリストが含まれます。
message textPayload(または jsonPayload の一部) ロギング エージェントが他の特殊フィールドを削除した後に唯一残ったフィールドであり、かつdetect_jsonは有効ではない場合、messagetextPayloadとして保存されます。それ以外の場合は、messagejsonPayloadのままです。ログエントリに例外スタック トレースが含まれている場合、例外スタック トレースをこの message JASON ログフィールドに設定する必要があります。設定すると、例外スタック トレースが解析され Error Reporting に保存されるようになります。
log(以前の Google Kubernetes Engine のみ) textPayload 以前の Google Kubernetes Engine にのみ適用されます。特殊フィールドを削除した後にlogフィールドだけが残った場合、logtextPayload として保存されます。
httpRequest httpRequest LogEntry HttpRequest フィールド形式の構造化レコードです。
時間関連フィールド timestamp 詳しくは、このページの時間関連のフィールドをご覧ください。
logging.googleapis.com/insertId insertId
logging.googleapis.com/labels labels このフィールドの値は構造化レコードであることが必要です。
logging.googleapis.com/operation operation このフィールドの値は、関連するログエントリをグループ化するためにログビューアでも使用されます。
logging.googleapis.com/sourceLocation sourceLocation LogEntry LogEntrySourceLocation フィールド形式の構造化レコードです。
logging.googleapis.com/spanId spanId
logging.googleapis.com/trace trace このフィールドの値は projects/[PROJECT-ID]/traces/[TRACE-ID] としてフォーマットする必要があります。これは、ログビューアとトレース ビューアが、ログエントリをグループ化し、トレースに一致するように表示できるようにするためです。autoformat_stackdriver_tracetrue で、[V]ResourceTracetraceId の形式と一致する場合、LogEntrytrace フィールドの値は projects/[PROJECT-ID]/traces/[V] になります。
logging.googleapis.com/trace_sampled traceSampled このフィールドの値は true または false としてフォーマットする必要があります。

残りの構造化レコードのフィールドは、jsonPayload の一部になります。detect_json が存在せず、message フィールドだけが残っている場合、そのフィールドの値は textPayload としてログエントリに保存されます。

時間関連フィールド

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

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

  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
        # Format 'none' indicates the log is unstructured (text).
        format none
        # 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
        # Format 'JSON' indicates the log is structured (JSON).
        format json
        # 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-loglogName でフィルタします。

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

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

構成名 デフォルト 説明
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 設定を使用して特定のリテラル値にラベルを添付します。このアプローチは、非構造化ログの送信中でも使用できます。

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

ログレコードの変更

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

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

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

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

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

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

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

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

構成名 デフォルト 説明
buffer_type 文字列 buf_memory Logging API に高速で書き込めないレコードは、バッファに push されます。バッファはメモリ内または実際のファイルに存在します。推奨値: buf_fileデフォルトの buf_memory は高速ですが、持続性がありません。ログを失う危険性があります。buffer_typebuf_file の場合、buffer_path も指定する必要があります。
buffer_path string ユーザーによる設定 バッファ チャンクが格納されているパス。buffer_typefile の場合、このパラメータは必須です。競合状態を避けるために、この構成は一意でなければなりません。
buffer_queue_limit int 64 チャンクキューの長さ制限を指定します。バッファキューがこのチャンク数に達すると、バッファの動作は buffer_queue_full_action によって制御されます。デフォルトでは、例外がスローされます。このオプションとbuffer_chunk_limitの組み合わせにより、fluentdがバッファに使用する最大ディスク容量が決まります。
buffer_queue_full_action 文字列 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 エージェントが実行されている GCP または AWS プロジェクトを表す project_id がオーバーライドされます。
zone string nil これを指定すると、ゾーンがオーバーライドされます。
vm_id string nil これを指定すると、VM ID がオーバーライドされます。
vm_name string nil これを指定すると、VM 名がオーバーライドされます。

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

構成名 デフォルト 説明
detect_json1 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 文字列 ""(スペース) coerce_to_utf8true に設定されている場合、UTF-8 以外の文字はここで指定された文字列に置き換えられます。

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

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

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

Linux インスタンス

  1. 構成ファイルを次のディレクトリにコピーします。

    /etc/google-fluentd/config.d/
    
  2. 次のコマンドを実行してエージェントを再起動します。

    sudo service google-fluentd force-reload
    

Logging エージェントのインストール スクリプトによって、このディレクトリにデフォルトのキャッチオール構成ファイルが移入されます。詳しくは、ロギング エージェントのソースコードを入手するをご覧ください。

Windows インスタンス

  1. 構成ファイルをエージェントのインストール ディレクトリの config.d サブディレクトリにコピーします。デフォルトのインストール ディレクトリを使用している場合、このディレクトリは次のようになります。

    C:\Program Files (x86)\Stackdriver\LoggingAgent\config.d\
    
  2. コマンドライン シェルで次のコマンドを実行して、エージェントを再起動します。

    net stop  StackdriverLogging
    net start StackdriverLogging
    

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