エージェントの構成

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

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

1 <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 文字列 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 使用率が低下します。
grpc_compression_algorithm enum none gRPC を使用する場合、使用する圧縮スキーマを設定します。none または gzip のいずれかです。
partial_success bool true ログの取り込みの部分的な成功をサポートするかどうか。true の場合、すべての無効なログエントリが削除され、有効なログエントリが Logging API に正しく取り込まれます。false の場合、無効なログエントリが含まれていると、すべてのログエントリが削除されます
enable_monitoring bool true true に設定すると、Logging エージェントは内部テレメトリーをエクスポートします。詳しくは、出力プラグイン テレメトリーをご覧ください。
monitoring_type 文字列 opencensus モニタリングのタイプ。サポートされているオプションは opencensusprometheus です。詳しくは、出力プラグイン テレメトリーをご覧ください。
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 インスタンスでは、デフォルトで有効にはなりません。すべての JSON を detect_json で解析するオプションは、常に jsonPayload で取り込まれます。

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

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

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

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

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

JSON ログフィールド LogEntry フィールド Cloud Logging エージェントの機能 値の例
severity severity Logging エージェントは、Logging API によって認識される LogSeverity 文字列のリストを含む、さまざまな共通の重大度文字列の照合を試みます。 "severity":"ERROR"
message textPayload(または jsonPayload の一部) Logs Explorer のログエントリに表示されるメッセージ。 "message":"There was an error in the application."

: Logging エージェントが他の特殊フィールドを削除した後に唯一残ったフィールドであり、かつ detect_json が有効でない場合、messagetextPayload として保存されます。これに該当しない場合、messagejsonPayload に残ります。ログエントリに例外スタック トレースが含まれている場合、例外スタック トレースをこの message JASON ログフィールドに設定する必要があります。設定すると、例外スタック トレースが解析され、Error Reporting に保存されるようになります。
log(以前の Google Kubernetes Engine のみ) textPayload 以前の Google Kubernetes Engine にのみ適用されます。特殊用途フィールドを削除した後にログフィールドが 1 つだけが残った場合、そのログは textPayload として保存されます。
httpRequest httpRequest LogEntry HttpRequest フィールド形式の構造化レコード。 "httpRequest":{"requestMethod":"GET"}
時間関連フィールド timetimestamp など 詳細については、時間関連フィールドをご覧ください。 "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"

: stdoutstderr に書き込まない場合、このフィールドの値は、projects/[PROJECT-ID]/traces/[TRACE-ID] 形式となる必要があります。そうすると、ログ エクスプローラとトレース ビューアが、ログエントリをグループ化してトレースと一緒に表示できます。autoformat_stackdriver_trace が true で、[V]ResourceTracetraceId の形式と一致する場合、LogEntry の trace フィールドの値は、projects/[PROJECT-ID]/traces/[V] になります。
logging.googleapis.com/trace_sampled traceSampled このフィールドの値は true または false のいずれかにする必要があります。詳細については、LogEntry ページの traceSampled をご覧ください。 logging.googleapis.com/trace_sampled": 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.dtest-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.dtest-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-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 の構成ファイル構文のドキュメントをご覧ください。