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

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

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

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

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

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

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

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

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

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

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

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

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

構成モデル

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

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

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

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

組み込み構成

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

Linux

デフォルトでは、Ops エージェントはファイルベースの syslog ログとホスト指標を収集します。

収集した指標の詳細については、レシーバーによって取り込まれる指標をご覧ください。

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]

Windows

デフォルトでは、Ops エージェントは System、Application、Security のチャンネル、ホスト指標、IIS 指標、SQL Server の指標から Windows イベントログを収集します。

収集した指標の詳細については、レシーバーによって取り込まれる指標をご覧ください。

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デフォルトは tcp です。

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

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

  • 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 フィールドに最上位フィールドを配置します。

レコード フィールド LogEntry フィールド

オプション 1


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

オプション 2


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

 timestamp
receiver_id（レコード フィールドではない） logName
logging.googleapis.com/httpRequest（HttpRequest） httpRequest
logging.googleapis.com/severity（文字列） severity
logging.googleapis.com/labels（string:string の構造体） labels
logging.googleapis.com/operation（構造体） operation
logging.googleapis.com/sourceLocation（構造体） sourceLocation
logging.googleapis.com/trace（文字列） trace
logging.googleapis.com/spanId（文字列） spanId

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

一般的な Linux ログファイル

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

アプリケーション 一般的なログファイル
apache Apache のログファイルについては、サードパーティ アプリケーションのモニタリング: Apache ウェブサーバーをご覧ください。
cassandra Cassandra のログファイルについては、サードパーティ アプリケーションのモニタリング: Cassandra をご覧ください。
Chef /var/log/chef-server/bookshelf/current
/var/log/chef-server/chef-expander/current
/var/log/chef-server/chef-pedant/http-traffic.log
/var/log/chef-server/chef-server-webui/current
/var/log/chef-server/chef-solr/current
/var/log/chef-server/erchef/current
/var/log/chef-server/erchef/erchef.log.1
/var/log/chef-server/nginx/access.log
/var/log/chef-server/nginx/error.log
/var/log/chef-server/nginx/rewrite-port-80.log
/var/log/chef-server/postgresql/current
gitlab /home/git/gitlab/log/application.log
/home/git/gitlab/log/githost.log
/home/git/gitlab/log/production.log
/home/git/gitlab/log/satellites.log
/home/git/gitlab/log/sidekiq.log
/home/git/gitlab/log/unicorn.stderr.log
/home/git/gitlab/log/unicorn.stdout.log
/home/git/gitlab-shell/gitlab-shell.log
Jenkins /var/log/jenkins/jenkins.log
jetty /var/log/jetty/out.log
/var/log/jetty/*.request.log
/var/log/jetty/*.stderrout.log
joomla /var/www/joomla/logs/*.log
magento /var/www/magento/var/log/exception.log
/var/www/magento/var/log/system.log
/var/www/magento/var/report/*
mediawiki /var/log/mediawiki/*.log
memcached Memcached のログファイルについては、サードパーティ アプリケーションのモニタリング: Memcached をご覧ください。
mongodb MongoDB のログファイルについては、サードパーティ アプリケーションのモニタリング: MongoDB をご覧ください。
mysql MySQL のログファイルについては、サードパーティ アプリケーションのモニタリング: MySQL をご覧ください。
nginx nginx ログファイルについては、サードパーティ アプリケーションのモニタリング: nginx をご覧ください。
postgres PostgreSQL ログファイルについては、サードパーティ アプリケーションのモニタリング: PostgreSQL をご覧ください。
Puppet /var/log/puppet/http.log
/var/log/puppet/masterhttp.log
puppet-enterprise /var/log/pe-activemq/activemq.log
/var/log/pe-activemq/wrapper.log
/var/log/pe-console-auth/auth.log
/var/log/pe-console-auth/cas_client.log
/var/log/pe-console-auth/cas.log
/var/log/pe-httpd/access.log
/var/log/pe-httpd/error.log
/var/log/pe-httpd/other_vhosts_access.log
/var/log/pe-httpd/puppetdashboard.access.log
/var/log/pe-httpd/puppetdashboard.error.log
/var/log/pe-httpd/puppetmasteraccess.log
/var/log/pe-mcollective/mcollective_audit.log
/var/log/pe-mcollective/mcollective.log
/var/log/pe-puppet-dashboard/certificate_manager.log
/var/log/pe-puppet-dashboard/event-inspector.log
/var/log/pe-puppet-dashboard/failed_reports.log
/var/log/pe-puppet-dashboard/live-management.log
/var/log/pe-puppet-dashboard/mcollective_client.log
/var/log/pe-puppet-dashboard/production.log
/var/log/pe-puppetdb/pe-puppetdb.log
/var/log/pe-puppet/masterhttp.log
/var/log/pe-puppet/rails.log
rabbitmq RabbitMQ ログファイルについては、サードパーティ アプリケーションのモニタリング: RabbitMQ をご覧ください。
redis Redis のログファイルについては、サードパーティ アプリケーションのモニタリング: Redis をご覧ください。
redmine /var/log/redmine/*.log
salt /var/log/salt/key
/var/log/salt/master
/var/log/salt/minion
/var/log/salt/syndic.loc
solr Apache Solr ログファイルについては、サードパーティ アプリケーションのモニタリング: Apache Solr をご覧ください。
sugarcrm /var/www/*/sugarcrm.log
syslog /var/log/syslog
/var/log/messages
tomcat Apache Tomcat のログファイルについては、サードパーティ アプリケーションのモニタリング: Apache Tomcat をご覧ください。
zookeeper Apache ZooKeeper のログファイルについては、サードパーティ アプリケーションのモニタリング: Apache ZooKeeper をご覧ください。

デフォルトの取り込みラベル

LogEntry のログには、デフォルトで次のラベルを含めることができます。

フィールド 値のサンプル 説明
labels."compute.googleapis.com/resource_name" test_vm このログの取得元の仮想マシンの名前。すべてのログが対象。
labels."logging.googleapis.com/instrumentation_source" agent.googleapis.com/apache_access ログの作成元であるレシーバ type の値。接頭辞は agent.googleapis.com/ です。サードパーティ統合の受信者のみが記録します。

ロギング プロセッサ

オプションの processors 要素には、PROCESSOR_ID で識別される一連の処理ディレクティブが含まれます。プロセッサは、レシーバーによって収集された情報を操作する方法を記述します。

各プロセッサには一意の識別子があり、type 要素が含まれている必要があります。有効なタイプは次のとおりです。

  • parse_json: JSON 形式の構造化ログを解析します。
  • parse_multiline: 複数行のログを解析します。（Linux のみ）
  • parse_regex: 正規表現パターンを使用してテキスト形式のログを解析して、JSON 形式の構造化ログに変換します。
  • exclude_logs: 指定したルールに一致するログを除外します（2.9.0 以降）。
  • modify_fields: ログエントリのフィールドを設定 / 変換します（2.14.0 以降）。

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

processors:
  PROCESSOR_ID:
    type: parse_json
    ...
  PROCESSOR_ID_2:
    type: parse_regex
    ...

type 要素の値に応じて、次のような構成オプションを使用できます。

parse_json プロセッサ

設定の構造

processors:
  PROCESSOR_ID:
    type: parse_json

    time_key:    <field name within jsonPayload>
    time_format: <strptime format string>

parse_json プロセッサは、入力 JSON を解析して、その結果を LogEntry の jsonPayload フィールドに挿入します。LogEntry の他の部分は、特定の特別なトップレベル フィールドを設定することで解析できます。

  • time_key: 省略可。ログエントリにタイムスタンプを含むフィールドがある場合、このオプションでそのフィールドの名前を指定します。抽出された値は、生成される LogEntry の timestamp フィールドの設定に使用され、ペイロードから削除されます。

    time_key オプションを指定する場合は、以下も指定する必要があります。

    • time_format: time_key を使用する場合は必須。このオプションで time_key フィールドの形式を指定すると、認識と分析が適切に行われます。フォーマットの詳細については、strptime(3) ガイドをご覧ください。
構成の例
processors:
  PROCESSOR_ID:
    type: parse_json

    time_key:    time
    time_format: "%Y-%m-%dT%H:%M:%S.%L%Z"

parse_multiline プロセッサ

設定の構造

processors:
  PROCESSOR_ID:
    type: parse_multiline

    match_any:
    - type: <type of the exceptions>
      language: <language name>

  • match_any: 必須。1 つ以上のルールのリスト。

    • type: 必須。サポートされる値は 1 つのみです。

      • language_exceptions: プロセッサが language オプションの値に基づいて例外を 1 つの LogEntry に連結します。

    • language: 必須。サポートされる値は 1 つのみです。

      • java: 一般的な Java 例外を 1 つの LogEntry に連結します。
      • python: 一般的な Python 例外を 1 つの LogEntry に連結します。
      • go: 一般的な Go 例外を 1 つの LogEntry に連結します。
構成の例
logging:
  receivers:
    custom_file1:
      type: files
      include_paths:
      - /tmp/test-multiline28
  processors:
    parse_java_multiline:
      type: parse_multiline
      match_any:
      - type: language_exceptions
        language: java
    extract_structure:
      type: parse_regex
      field: message
      regex: "^(?<time>[\d-]*T[\d:.Z]*) (?<severity>[^ ]*) (?<file>[^ :]*):(?<line>[\d]*) - (?<message>(.|\\n)*)$"
      time_key: time
      time_format: "%Y-%m-%dT%H:%M:%S.%L"
    move_severity:
      type: modify_fields
      fields:
        severity:
          move_from: jsonPayload.severity
  service:
    pipelines:
      pipeline1:
        receivers: [custom_file1]
        processors: [parse_java_multiline, extract_structure, move_severity]

前述の構成を使用していて、次の内容のログファイルがある場合:

2022-10-17T22:00:00.187512963Z ERROR HelloWorld:16 - javax.servlet.ServletException: Something bad happened
    at com.example.myproject.OpenSessionInViewFilter.doFilter(OpenSessionInViewFilter.java:60)
    at org.mortbay.jetty.servlet.ServletHandler$CachedChain.doFilter(ServletHandler.java:1157)
    at com.example.myproject.ExceptionHandlerFilter.doFilter(ExceptionHandlerFilter.java:28)
    at org.mortbay.jetty.servlet.ServletHandler$CachedChain.doFilter(ServletHandler.java:1157)
    at com.example.myproject.OutputBufferFilter.doFilter(OutputBufferFilter.java:33)
Caused by: com.example.myproject.MyProjectServletException
    at com.example.myproject.MyServlet.doPost(MyServlet.java:169)
    at javax.servlet.http.HttpServlet.service(HttpServlet.java:727)
    at javax.servlet.http.HttpServlet.service(HttpServlet.java:820)
    at org.mortbay.jetty.servlet.ServletHolder.handle(ServletHolder.java:511)
    at org.mortbay.jetty.servlet.ServletHandler$CachedChain.doFilter(ServletHandler.java:1166)
    at com.example.myproject.OpenSessionInViewFilter.doFilter(OpenSessionInViewFilter.java:30)
    ... 27 common frames omitted

エージェントはログを次の形式で Cloud Logging に取り込みます。

{
  "insertId": "...",
  "jsonPayload": {
    "line": "16",
    "message": "javax.servlet.ServletException: Something bad happened\n    at com.example.myproject.OpenSessionInViewFilter.doFilter(OpenSessionInViewFilter.java:60)\n    at org.mortbay.jetty.servlet.ServletHandler$CachedChain.doFilter(ServletHandler.java:1157)\n    at com.example.myproject.ExceptionHandlerFilter.doFilter(ExceptionHandlerFilter.java:28)\n    at org.mortbay.jetty.servlet.ServletHandler$CachedChain.doFilter(ServletHandler.java:1157)\n    at com.example.myproject.OutputBufferFilter.doFilter(OutputBufferFilter.java:33)\nCaused by: com.example.myproject.MyProjectServletException\n    at com.example.myproject.MyServlet.doPost(MyServlet.java:169)\n    at javax.servlet.http.HttpServlet.service(HttpServlet.java:727)\n    at javax.servlet.http.HttpServlet.service(HttpServlet.java:820)\n    at org.mortbay.jetty.servlet.ServletHolder.handle(ServletHolder.java:511)\n    at org.mortbay.jetty.servlet.ServletHandler$CachedChain.doFilter(ServletHandler.java:1166)\n    at com.example.myproject.OpenSessionInViewFilter.doFilter(OpenSessionInViewFilter.java:30)\n    ... 27 common frames omitted\n",
    "file": "HelloWorld"
  },
  "resource": {
    "type": "gce_instance",
    "labels": {
      "instance_id": "...",
      "project_id": "...",
      "zone": "..."
    }
  },
  "timestamp": "2022-10-17T22:00:00.187512963Z",
  "severity": "ERROR",
  "labels": {
    "compute.googleapis.com/resource_name": "..."
  },
  "logName": "projects/.../logs/custom_file",
  "receiveTimestamp": "2022-10-18T03:12:38.430364391Z"
}

parse_regex プロセッサ

設定の構造

processors:
  PROCESSOR_ID:
    type: parse_regex

    regex: <regular expression>

    time_key:    <field name within jsonPayload>
    time_format: <format string>

  • time_key: 省略可。ログエントリにタイムスタンプを含むフィールドがある場合、このオプションでそのフィールドの名前を指定します。抽出された値は、生成される LogEntry の timestamp フィールドの設定に使用され、ペイロードから削除されます。

    time_key オプションを指定する場合は、以下も指定する必要があります。

    • time_format: time_key を使用する場合は必須。このオプションで time_key フィールドの形式を指定すると、認識と分析が適切に行われます。フォーマットの詳細については、strptime(3) ガイドをご覧ください。

  • regex: 必須。フィールドの解析に使用される正規表現。式には、一致したサブ式のキー名を含める必要があります（例: "^(?<time>[^ ]*) (?<severity>[^ ]*) (?<msg>.*)$"）。

    名前付きキャプチャ グループと一致したテキストは、LogEntry の jsonPayload フィールドに配置されます。ログに構造を追加するには、modify_fields プロセッサを使用します。

    一般的な Linux アプリケーション ログファイルから情報を抽出するための一連の正規表現については、一般的な Linux ログファイルをご覧ください。

構成の例
processors:
  PROCESSOR_ID:
    type: parse_regex

    regex:       "^(?<time>[^ ]*) (?<severity>[^ ]*) (?<msg>.*)$"
    time_key:    time
    time_format: "%Y-%m-%dT%H:%M:%S.%L%Z"

exclude_logs プロセッサ

設定の構造

type: exclude_logs
match_any:
  - <filter>
  - <filter>

このプロセッサのトップレベル構成には、フィルタルールのリストを含む単一のフィールド match_any があります。

  • match_any: 必須。1 つ以上のルールのリスト。ログエントリがいずれかのルールと一致した場合、Ops エージェントはそのエントリを取り込みません。

    Ops エージェントによって取り込まれるログは、LogEntry の構造に従います。フィールド名では、大文字と小文字が区別されます。ルールを指定できるのは、次のフィールドとそのサブフィールドのみです。

    • httpRequest
    • jsonPayload
    • labels
    • operation
    • severity
    • sourceLocation
    • trace
    • spanId

    次のルールの例

    severity =~ "(DEBUG|INFO)"

    正規表現を使用して、DEBUG および INFO レベルのログをすべて除外します。

    ルールは Cloud Logging クエリ言語の構文に従いますが、Logging クエリ言語でサポートされる機能の一部のみをサポートします。

    • 比較演算子: =、!=、:、=~、!~。文字列比較のみがサポートされています。
    • ナビゲーション演算子: .。例: jsonPayload.message。
    • ブール演算子: AND、OR、NOT。
    • ( ) を使用して式をグループ化します。

構成の例

processors:
  PROCESSOR_ID:
    type: exclude_logs
    match_any:
    - '(jsonPayload.message =~ "log spam 1" OR jsonPayload.message =~ "log spam 2") AND severity = "ERROR"'
    - 'jsonPayload.application = "foo" AND severity = "INFO"'

modify_fields プロセッサ

modify_fields プロセッサを使用すると、ログエントリの構造と内容をカスタマイズできます。

設定の構造

type: modify_fields
fields:
  <destination field>:
    # Source
    move_from: <source field>
    copy_from: <source field>
    static_value: <string>
    
    # Mutation
    default_value: <string>
    map_values:
      <old value>: <new value>
    type: {integer|float}
    omit_if: <filter>

このプロセッサのトップレベル構成には、単一のフィールド fields があります。このフィールドには、出力フィールド名と対応する変換のマップが含まれます。出力フィールドごとに、オプションのソースと 0 個以上のミューテーション オペレーションが適用されます。

すべてのフィールド名で Cloud Logging クエリ言語のドット区切り構文が使用されます。フィルタでは、Cloud Logging クエリ言語が使用されます。

すべての変換は並行して適用されます。つまり、ソースとフィルタは元の入力ログエントリで動作するため、同じプロセッサによって変更される他のフィールドの新しい値を参照できません。

ソース オプション: 指定したソースを 1 つ指定できます。

  • ソースが指定されていません

    ソース値が指定されていない場合、宛先フィールドの既存の値が変更されます。

  • move_from: <source field>

    <source field> の値が宛先フィールドの送信元として使用されます。さらに、<source field> がログエントリから削除されます。ソース フィールドが move_from と copy_from の両方で参照されている場合でも、ソース フィールドは削除されます。

  • copy_from: <source field>

    <source field> の値が宛先フィールドの送信元として使用されます。<source field> は、move_from オペレーションで参照されるか変更されない限り、ログエントリから削除されません。

  • static_value: <string>

    静的文字列 <string> が宛先フィールドのソースとして使用されます。

ミューテーション オプション: 1 つのフィールドに 0 個以上のミューテーション オペレータを適用できます。複数の演算子を指定すると、常に次の順序で適用されます。

  1. default_value: <string>

    ソース フィールドが存在しない場合、出力値は <string> に設定されます。ソース フィールドが存在する場合（空の文字列が含まれている場合も含む）、元の値は変更されません。

  2. map_values: <map>

    入力値が <map> のいずれかのキーと一致する場合、出力値はマップの対応する値に置き換えられます。

  3. map_values_exclusive: {true|false}

    <source field> 値が map_values ペアに指定されたキーと一致しない場合、map_values_exclusive が true であれば destination フィールドは強制的に設定解除されます。map_values_exclusive が false の場合は、そのまま残ります。

  4. type: {integer|float}

    入力値は整数または浮動小数点数に変換されます。文字列を数値に変換できない場合、出力値は設定されません。文字列に浮動小数点数が含まれていても、型が integer として指定されている場合、数値は整数に切り捨てられます。

    Cloud Logging API は JSON を使用するため、完全な 64 ビット整数はサポートされません。64 ビット以上の整数が必要な場合は、ログエントリに文字列として保存する必要があります。

  5. omit_if: <filter>

    フィルタが入力ログレコードと一致する場合、出力フィールドは設定されません。これは、次のようなプレースホルダ値を削除する場合に使用できます。

    httpRequest.referer:
  move_from: jsonPayload.referer
  omit_if: httpRequest.referer = "-"

構成例

parse_json プロセッサは、次を含む JSON ファイルを変換します。

{
  "http_status": "400",
  "path": "/index.html",
  "referer": "-"
}

次のような LogEntry 構造にします。

{
  "jsonPayload": {
    "http_status": "400",
    "path": "/index.html",
    "referer": "-"
  }
}

その後、modify_fields でこの LogEntry に変換できます。

{
  "httpRequest": {
    "status": 400,
    "requestUrl": "/index.html",
  }
}

次の Ops エージェント構成を使用します。

logging:
  receivers:
    in:
      type: files
      include_paths:
      - /var/log/http.json
  processors:
    parse_json:
      type: parse_json
    set_http_request:
      type: modify_fields
      fields:
        httpRequest.status:
          move_from: jsonPayload.http_status
          type: integer
        httpRequest.requestUrl:
          move_from: jsonPayload.path
        httpRequest.referer:
          move_from: jsonPayload.referer
          omit_if: jsonPayload.referer = "-"
  pipelines:
    pipeline:
      receivers: [in]
      processors: [parse_json, set_http_request]

この構成では、/var/log/http.json から JSON 形式のログを読み取り、ログのフィールドから httpRequest 構造の一部を入力します。

ロギング サービス

このロギング サービスは、Ops エージェント自身のログの詳細度をカスタマイズし、ロギングのレシーバーとプロセッサをパイプラインにリンクします。service セクションには、次の要素があります。

  • log_level
  • pipelines

ログの詳細レベル

log_level フィールド（Ops エージェント バージョン 2.6.0 以降で利用可能）は、Ops エージェント ロギングのサブモジュール自体のログの詳細度をカスタマイズします。デフォルトは info です。使用できるオプション: error、warn、info、debug、trace.

次の構成では、ロギングのサブモジュールのログの詳細度が debug になるようにカスタマイズします。

logging:
  service:
    log_level: debug

ロギング パイプライン

pipelines フィールドには、複数のパイプライン ID と定義を含めることができます。各 pipeline の値は、次の要素で構成されます。

  • receivers: 新しいパイプラインに必要です。ロギング レシーバーで説明されているレシーバー ID のリストです。リスト内のレシーバー ID の順序に意味はありません。パイプラインは、リストされたすべてのレシーバーからデータを収集します。

  • processors: 省略可。ロギング プロセッサで説明されているプロセッサ ID のリストです。リスト内のプロセッサ ID の順序は重要です。各レコードは、リストに記載された順序でプロセッサによって実行されます。

ロギングの service 構成の例

service 構成の構造は次のとおりです。

service:
  log_level: CUSTOM_LOG_LEVEL
  pipelines:
    PIPELINE_ID:
      receivers:  [...]
      processors: [...]
    PIPELINE_ID_2:
      receivers:  [...]
      processors: [...]

エージェントが /var/log/message エントリまたは /var/log/syslog エントリのいずれかの収集と送信を行わないようにするには、プロセッサを指定せずに receivers リストを使用してデフォルトのパイプラインを再定義します。この構成では、エージェントのロギング サブコンポーネントが停止しません。これは、エージェントがモニタリング サブコンポーネントのログを収集する必要があるためです。空のロギング構成全体は、次のようになります。

logging:
  service:
    pipelines:
      default_pipeline:
        receivers: []

次の service 構成は、ID が custom_pipeline であるパイプラインを定義します。

logging:
  service:
    pipelines:
      custom_pipeline:
        receivers:
        - RECEIVER_ID
        processors:
        - PROCESSOR_ID

指標の構成

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

  • receivers: レシーバー定義のリスト。receiver は指標のソースを記述します。（cpu や memory などのシステム指標など）。 このリストのレシーバーは、複数のパイプラインで共有できます。
  • processors: プロセッサ定義のリスト。processor は、レシーバーによって収集された指標を変更する方法を表します。
  • service: pipeline 定義のリストである pipelines セクションが含まれます。pipeline は、receivers のリストと processors のリストを接続して、データフローを形成します。

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

Ops エージェントは Cloud Monitoring に指標を送信します。他のサービスに指標をエクスポートするように構成することはできません。

指標レシーバー

receivers 要素にはレシーバー定義のセットが含まれます。レシーバーは、cpu や memory など、指標を取得する場所を記述します。レシーバーは複数のパイプラインで共有できます。

指標レシーバーの構造

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

  • hostmetrics
  • iis（Windows のみ）
  • mssql（Windows のみ）

レシーバーは、オペレーションの collection_interval オプションも指定できます。この値は期間の形式です（例: 30s、2m）。デフォルト値は 60s です。

これらのレシーバー タイプはそれぞれ、一連の指標を収集します。含まれる特定の指標の詳細については、レシーバーによって取り込まれる指標をご覧ください。

レシーバーはタイプごとに 1 つのみ作成できます。たとえば、hostmetrics タイプのレシーバーを 2 つ定義することはできません。

指標レシーバーでの収集間隔の変更

重要なワークロードの中には、迅速なアラートを必要とするものがあります。指標の収集間隔を短くすることで、より感度の高いアラートを構成できます。アラートの評価方法については、指標ベースのアラート ポリシーの動作をご覧ください。

たとえば、次のレシーバーは、ホスト指標（レシーバー ID は hostmetrics）の収集間隔をデフォルトの 60 秒から 10 秒に変更します。

metrics:
  receivers:
    hostmetrics:
      type: hostmetrics
      collection_interval: 10s

同じ手法を使用して、Windows の iis と mssql の指標レシーバーで収集間隔をオーバーライドすることもできます。

レシーバーによって取り込まれた指標

Ops エージェントによって取り込まれた指標には、agent.googleapis.com/GROUP のパターンで始まる識別子が含まれています。GROUP コンポーネントは、関連する一連の指標を識別します。これらには cpu、network などの値があります。

hostmetrics レシーバー

hostmetrics レシーバーは、次の指標グループを取得します。詳しくは、Ops エージェント指標ページの各グループのリンク先のセクションをご覧ください。

グループ 指標
cpu 1 分間隔の CPU 負荷
5 分間隔の CPU 負荷
15 分間隔の CPU 負荷
CPU の使用量（CPU 番号と状態のラベル付き）
CPU の使用率（CPU 番号と状態のラベル付き）
disk ディスク読み取りバイト数（デバイスラベル付き）
ディスク書き込みバイト数（デバイスラベル付き）
ディスク I/O 時間（デバイスラベル付き）
ディスク総所要 I/O 時間（デバイスラベル付き）
ディスクの保留中の処理（デバイスラベル付き）
ディスクマージ処理（デバイスと方向のラベル付き）
ディスク処理（デバイスと方向のラベル付き）
ディスク処理時間（デバイスと方向のラベル付き）
デバイス使用量（ディスクと状態のラベル付き）
ディスク使用率（デバイスと状態のラベル付き）
gpu
Linux のみ。その他の重要な情報については、gpu 指標についてをご覧ください。		 現在の使用 GPU メモリバイト数（状態別）
プロセスによって割り当てられた GPU メモリの最大量（バイト単位）
GPU で稼働している 1 つ以上のカーネルのプロセス存続期間内の時間の割合
最後のサンプル以降、GPU がアクティブだった時間の割合
interface
Linux のみ		 ネットワーク エラーの合計数
ネットワーク上で送信されたパケットの合計数
ネットワーク上で送信されたバイトの合計数
memory メモリ使用量、状態（buffered、cached、free、slab、used）のラベル付き
メモリ使用率、状態（buffered、cached、free、slab、used）のラベル付き
network TCP 接続数（ポートと TCP の状態のラベル付き）
swap スワップ I/O 処理（方向のラベル付き）
スワップ使用バイト数（デバイスと状態のラベル付き）
スワップ使用率（デバイスと状態のラベル付き）
pagefile
Windows のみ		 状態で使用されるページファイルの現在の割合
processes プロセス数（状態ラベル付き）
プロセス フォーク数
プロセスごとのディスク読み取り I/O（プロセス名 + その他のラベル付き）
プロセスごとディスク書き込み I/O（プロセス名 + その他のラベル付き）
プロセスごとの RSS 使用量（プロセス名 + その他のラベル付き）
プロセスごとの VM 使用量（プロセス名 + その他のラベル付き）
iis レシーバー（Windows のみ）

iis レシーバー（Windows のみ）が、iis グループの指標を取り込みます。 詳しくは、エージェントの指標ページをご覧ください。

グループ 指標
iis
Windows のみ		 現在の IIS へのオープン接続
IIS によって転送されたネットワーク バイト
IIS に開かれた接続
IIS に対して行われたリクエスト
mssql レシーバー（Windows のみ）

mssql レシーバー（Windows のみ）が、mssql グループの指標を取り込みます。詳細については、Ops エージェントの指標ページをご覧ください。

グループ 指標
mssql
Windows のみ		 現在の SQL Server へのオープン接続
SQL Server の 1 秒あたりのトランザクション合計数
SQL Server の 1 秒あたりの書き込みトランザクション

指標プロセッサ

processor 要素には、一連のプロセッサ定義が含まれます。プロセッサは、除外するレシーバー タイプの指標を記述します。サポートされているタイプは exclude_metrics のみで、metrics_pattern オプションを指定できます。この値は、レシーバーによって収集されたグループから除外する Ops エージェントの指標タイプに一致する glob のリストです。例:

指標プロセッサの例

次の例は、組み込み構成で指定される exclude_metrics プロセッサを示します。このプロセッサは空の metrics_pattern 値を指定するため、指標は除外されません。

processors:
  metrics_filter:
    type: exclude_metrics
    metrics_pattern: []

Ops エージェントによるすべてのプロセス指標の収集を無効にするには、次の行を config.yaml ファイルに追加します。

metrics:
  processors:
    metrics_filter:
      type: exclude_metrics
      metrics_pattern:
      - agent.googleapis.com/processes/*

この場合、metrics サービスのデフォルト パイプラインに適用される metrics_filter プロセッサ内のコレクションから、プロセス指標が除外されます。

指標サービス

指標サービスは、Ops エージェントの指標モジュール自体のログの詳細度をカスタマイズし、指標レシーバーとプロセッサをパイプラインにリンクします。service セクションには、log_level と pipelines という 2 つの要素があります。

指標の詳細レベル

log_level（Ops エージェント バージョン 2.6.0 以降で利用可能）は、Ops エージェントの指標のサブモジュール自体のログの詳細度をカスタマイズします。デフォルトは info です。使用できるオプションは error、warn、info、debug です。

指標パイプライン

service セクションには、複数のパイプライン ID と定義を含む単一の要素 pipelines があります。各 pipeline 定義は、次の要素で構成されます。

  • receivers: 新しいパイプラインに必要です。指標レシーバーで説明されているレシーバー ID のリストです。リスト内のレシーバー ID の順序に意味はありません。パイプラインは、リストされたすべてのレシーバーからデータを収集します。

  • processors: 省略可。指標プロセッサで説明されているプロセッサ ID のリストです。リスト内のプロセッサ ID の順序は重要です。各指標ポイントは、リストに記載された順序でプロセッサによって実行されます。

指標 service の構成例

service 構成の構造は次のとおりです。

service:
  log_level: CUSTOM_LOG_LEVEL
  pipelines:
    PIPELINE_ID:
      receivers:  [...]
      processors: [...]
    PIPELINE_ID_2:
      receivers:  [...]
      processors: [...]

ホスト指標の組み込みの取り込みを無効にするには、空の receivers リストを使用してデフォルトのパイプラインを再定義します。プロセッサは設定しません。指標の構成全体は、次のようになります。

metrics:
  service:
    pipelines:
      default_pipeline:
        receivers: []

次の例では、Windows 用の組み込みの service 構成を示します。

metrics:
  service:
    pipelines:
      default_pipeline:
        receivers:
        - hostmetrics
        - iis
        - mssql
        processors:
        - metrics_filter

次の service 構成では、指標のサブモジュールのログの詳細度が debug になるようにカスタマイズします。

metrics:
  service:
    log_level: debug

セルフログのコレクション

デフォルトでは、Ops エージェントの Fluent Bit セルフログが Cloud Logging に送信されます。これらのログには多くの情報が含まれる可能性があり、量が増えると Cloud Logging の使用コストが増加する可能性があります。

Ops エージェント バージョン 2.44.0 以降では、default_self_log_file_collection オプションを使用して、これらのセルフログのコレクションを無効にできます。

セルフログのコレクションを無効にするには、ユーザー指定の構成ファイルに global セクションを追加し、default_self_log_file_collection オプションの値を false に設定します。

logging:  ...
metrics:  ...
global:
  default_self_log_file_collection: false

ログ ローテーションの構成

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