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

このドキュメントでは、Ops エージェントのデフォルト構成とカスタム構成について詳しく説明します。次のいずれかに該当する場合は、このドキュメントをお読みください。

• 次の目的のため、Ops エージェントの構成を変更する必要がある。

  • 組み込みのロギングまたは指標の取り込みをオフにする。

    • ロギングの取り込みをオフにするには、ロギングの service 構成の例をご覧ください。

    • ホスト指標の取り込みをオフにするには、指標 service の構成例をご覧ください。

  • エージェントによるログの収集元となるログファイルのファイルパスをカスタマイズする。ロギング レシーバーをご覧ください。

  • JSON を解析するか、正規表現を使用して、エージェントがログエントリの処理に使用する構造化ログ形式をカスタマイズする。ロギング プロセッサをご覧ください。

  • 指標のサンプリング レートを変更する。指標レシーバーをご覧ください。

  • 有効にする指標グループまたはグループをカスタマイズする。エージェントはデフォルトで cpu や memory などのすべてのシステム指標を収集します。指標プロセッサをご覧ください。

  • エージェントがログをローテーションする方法をカスタマイズします。ログ ローテーション構成をご覧ください。

  • サポートされているサードパーティのアプリケーションから指標とログを収集します。サポートされているアプリケーションのリストについては、サードパーティ アプリケーションのモニタリングをご覧ください。

  • Prometheus レシーバーを使用してカスタム指標を収集します。

  • OpenTelemetry Protocol（OTLP）レシーバーを使用して、カスタム指標とトレースを収集します。

• Ops エージェントの構成の技術的な詳細に興味がある。

構成モデル

Ops エージェントは、組み込みのデフォルト構成を使用します。この組み込み構成を直接変更することはできません。代わりに、エージェントの再起動時に組み込み構成とマージされるオーバーライドのファイルを作成します。

組み込み構成の構成要素は次のとおりです。

• receivers: この要素はエージェントによって収集される内容を表します。
• processors: この要素は、エージェントが収集した情報を変更する方法を記述します。
• service: この要素は、レシーバーとプロセッサをリンクして、パイプラインというデータフローを作成します。service 要素には、複数のパイプラインを含めることができる pipelines 要素が含まれます。

組み込み構成はこれらの要素で構成され、同じ要素を使用して、その組み込み構成をオーバーライドします。

組み込み構成

Ops エージェントの組み込み構成では、ログと指標のデフォルト コレクションを定義します。Linux と Windows のそれぞれの場合の組み込み構成は、次のとおりです。

logging:
  receivers:
    syslog:
      type: files
      include_paths:
      - /var/log/messages
      - /var/log/syslog
  service:
    pipelines:
      default_pipeline:
        receivers: [syslog]
metrics:
  receivers:
    hostmetrics:
      type: hostmetrics
      collection_interval: 60s
  processors:
    metrics_filter:
      type: exclude_metrics
      metrics_pattern: []
  service:
    pipelines:
      default_pipeline:
        receivers: [hostmetrics]
        processors: [metrics_filter]

logging:
  receivers:
    windows_event_log:
      type: windows_event_log
      channels: [System, Application, Security]
  service:
    pipelines:
      default_pipeline:
        receivers: [windows_event_log]
metrics:
  receivers:
    hostmetrics:
      type: hostmetrics
      collection_interval: 60s
    iis:
      type: iis
      collection_interval: 60s
    mssql:
      type: mssql
      collection_interval: 60s
  processors:
    metrics_filter:
      type: exclude_metrics
      metrics_pattern: []
  service:
    pipelines:
      default_pipeline:
        receivers: [hostmetrics, iis, mssql]
        processors: [metrics_filter]

これらの構成の詳細については、Logging 構成と指標構成をご覧ください。

ユーザー指定の構成

組み込みの構成をオーバーライドするには、ユーザー構成ファイルに新しい構成要素を追加します。Ops エージェントの構成を次のファイルに配置します。

• Linux の場合: /etc/google-cloud-ops-agent/config.yaml
• Windows の場合: C:\Program Files\Google\Cloud Operations\Ops Agent\config\config.yaml

ユーザー指定の構成は、エージェントの再起動時に組み込み構成とマージされます。

組み込みのレシーバー、プロセッサ、パイプラインをオーバーライドするには、config.yaml ファイルで同じ識別子で宣言して再定義します。Ops エージェント バージョン 2.31.0 以降では、エージェントのログ ローテーション機能を構成することもできます。詳細については、Ops エージェントでログ ローテーションを構成するをご覧ください。

たとえば、指標の組み込み構成には、60 秒の収集間隔を指定する hostmetrics レシーバーが含まれています。ホスト指標の収集間隔を 30 秒に変更するには、次の例に示すように collection_interval 値を 30 秒に設定する hostmetrics という指標レシーバーを config.yaml ファイルに含めます。

metrics:
  receivers:
    hostmetrics:
      type: hostmetrics
      collection_interval: 30s

組み込み構成を変更する他の例については、ロギング構成と指標の構成をご覧ください。ロギングまたは指標データの収集をオフにすることもできます。これらの変更については、ロギングの service 構成と指標 service 構成の例で説明しています。

このファイルを使用すると、エージェントがセルフログを収集して Cloud Logging に送信しないように設定できます。詳細については、セルフログの収集をご覧ください。

また、このファイルを使用してエージェントのログ ローテーション機能を構成します。詳細については、Ops エージェントでログ ローテーションを構成するをご覧ください。

Cloud Logging と Cloud Monitoring 以外のサービスにログまたは指標をエクスポートするように Ops エージェントを構成することはできません。

ロギング構成

logging 構成では、前述の構成モデルを使用します。

• receivers: この要素は、ログファイルから収集するデータを記述します。このデータは <timestamp, record> モデルにマッピングされます。
• processors: この省略可能な要素は、エージェントが収集した情報を変更する方法を記述します。
• service: この要素は、レシーバーとプロセッサをリンクして、パイプラインというデータフローを作成します。service 要素には、複数のパイプライン定義を含めることができる pipelines 要素が含まれます。

各レシーバーと各プロセッサは、複数のパイプラインで使用できます。

以降のセクションで、これらの各要素について説明します。

Ops エージェントは Cloud Logging にログを送信します。他のサービスにログをエクスポートするように構成することはできません。ただし、ログをエクスポートするように Cloud Logging を構成できます。詳細については、サポートされている宛先にログをルーティングするをご覧ください。

ロギング レシーバー

receivers 要素には、RECEIVER_ID で識別される一連のレシーバーが含まれます。レシーバーは、ログを取得する方法を記述します。たとえば、tail ファイル、TCP ポート、Windows イベントログなどを使用します。

ロギング レシーバーの構造

各レシーバーには、識別子 RECEIVER_ID と type 要素を含める必要があります。有効なタイプは次のとおりです。

• files: ディスク上のファイルをテーリングしてログを収集します。
• fluent_forward（Ops エージェント バージョン 2.12.0 以降）: TCP 上で Fluent Forward プロトコルを介して送信されたログを収集します。
• tcp（Ops エージェント バージョン 2.3.0 以降）: TCP ポートをリッスンして JSON 形式のログを収集します。
• Linux のみ
  • syslog: TCP または UDP を介して Syslog メッセージを収集します。
  • systemd_journald（Ops エージェント バージョン 2.4.0 以降）: systemd-journald サービスから systemd ジャーナルログを収集します。
• Windows のみ:
  • windows_event_log: Windows イベントログ API を使用して Windows イベントログを収集します。
• サードパーティ アプリケーション ログレシーバー

receivers 構造は次のようになります。

receivers:
  RECEIVER_ID:
    type: files
    ...
  RECEIVER_ID_2:
    type: syslog
    ...

type 要素の値によっては、次のような他の構成オプションが存在する場合もあります。

• files レシーバー:

  • include_paths: 必須。各ファイルのテーリングで読み込むファイルシステムのパスのリスト。パスにはワイルドカード（*）を使用できます。例えば、/var/log/*.log（Linux）や C:\logs\*.log（Windows）などです。

    一般的な Linux アプリケーション ログファイルの一覧については、一般的な Linux ログファイルをご覧ください。

  • exclude_paths: 省略可。include_paths の照合で除外するファイルシステム パスのパターンのリスト。

  • record_log_file_path: 省略可。true に設定すると、ログレコードの取得元のファイルのパスが agent.googleapis.com/log_file_path ラベルの値として出力ログエントリに表示されます。ワイルドカードを使用する場合、レコードを取得したファイルのパスのみが記録されます。

  • wildcard_refresh_interval: 省略可。include_paths のワイルドカード ファイル パスが更新される間隔。時間を指定します（例: 30s、2m）。このプロパティは、ログファイルのローテーションがデフォルトの間隔よりも速く、ロギングのスループットが高い場合に有用です。指定しない場合のデフォルトの間隔は 60 秒です。

• fluent_forward レシーバ:

  • listen_host: 省略可。リッスンする IP アドレス。デフォルト値は 127.0.0.1 です。

  • listen_port: 省略可。リッスンするポート。デフォルト値は 24224 です。

• syslog レシーバー（Linux のみ）:

  • transport_protocol: サポートされる値: tcp、udp。

  • listen_host: リッスンする IP アドレス。

  • listen_port: リッスンするポート。

• tcp レシーバー:

  • format: 必須。ログ形式。サポートされている値: json

  • listen_host: 省略可。リッスンする IP アドレス。デフォルト値は 127.0.0.1 です。

  • listen_port: 省略可。リッスンするポート。デフォルト値は 5170 です。

• windows_event_log レシーバー（Windows のみ）:

  • channels: 必須。ログの読み取りを行う Windows イベント ログチャネルのリスト。

  • receiver_version: 省略可。使用する Windows Event Log API を制御します。サポートされる値は 1 と 2 です。デフォルト値は 1 です。

  • render_as_xml: 省略可。true に設定すると、jsonPayload.Message と jsonPayload.StringInserts を除くすべてのイベントログ フィールドが、jsonPayload.raw_xml という文字列フィールドに XML ドキュメントとして表示されます。デフォルト値は false です。receiver_version が 1 の場合は、これを true に設定することはできません。

ロギング レシーバーの例

files レシーバーの例:

receivers:
  RECEIVER_ID:
    type: files

    include_paths: [/var/log/*.log]
    exclude_paths: [/var/log/not-this-one.log]
    record_log_file_path: true

fluent_forward レシーバーの例:

receivers:
  RECEIVER_ID:
    type: fluent_forward

    listen_host: 127.0.0.1
    listen_port: 24224

syslog レシーバーの例（Linux のみ）:

receivers:
  RECEIVER_ID:
    type: syslog

    transport_protocol: tcp
    listen_host: 0.0.0.0
    listen_port: 5140

tcp レシーバーの例:

receivers:
  RECEIVER_ID:
    type: tcp

    format: json
    listen_host: 127.0.0.1
    listen_port: 5170

windows_event_log レシーバーの例（Windows のみ）:

receivers:
  RECEIVER_ID:
    type: windows_event_log

    channels: [System,Application,Security]

バージョン 2 を使用するように組み込みレシーバーをオーバーライドする windows_event_log レシーバーの例。

receivers:
  windows_event_log:
    type: windows_event_log

    channels: [System,Application,Security]
    receiver_version: 2

systemd_journald レシーバーの例:

receivers:
  RECEIVER_ID:
    type: systemd_journald

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

構造化データを取り込むことができるプロセッサとレシーバー（fluent_forward および tcp レシーバー、parse_json プロセッサ）の場合、入力で、エージェントが Logging API に書き込む LogEntry オブジェクト内の特定のフィールドにマッピングする特殊フィールドを設定できます。

フィールド名が次の表に記載されていない限り、Ops エージェントは、外部構造化ログデータを受け取ると、LogEntry の jsonPayload フィールドに最上位フィールドを配置します。

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

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

残りの構造化レコードのフィールドは、jsonPayload 構造の一部として残ります。

一般的な Linux ログファイル

次の表は、よく使用される Linux アプリケーションの一般的なログファイルを示したものです。