Ops エージェントのトラブルシューティング情報を確認する

このドキュメントでは、Ops エージェントのインストールまたは実行時の問題の特定に使用できる診断情報のソースについて説明します。

エージェントのヘルスチェック

バージョン 2.25.1 では、Ops エージェント起動時のヘルスチェックが導入されました。Ops エージェントが起動すると、エージェントの正常な実行を妨げる条件がチェックされます。エージェントがいずれかの条件を検出すると、問題を説明するメッセージがログに記録されます。Ops エージェントは次のことを確認します。

接続エラー
エージェントが自身に関する指標の報告に使用するポートの可用性
権限に関する問題
エージェントがログまたは指標を書き込むために使用する API の可用性
ヘルスチェックルーチン自体の問題

起動時のエラーの特定については、起動時のエラーを探すをご覧ください。

バージョン 2.37.0 では、Ops エージェント用のランタイムヘルスチェックが導入されました。これらのエラーは、Cloud Logging と Error Reporting に報告されます。ランタイムエラーの特定については、ランタイムエラーを探すをご覧ください。

バージョン 2.46.0 で情報提供用の LogPingOpsAgent コードが導入されました。このコードはエラーを表すものではありません。詳細については、ログ収集の成功を確認するをご覧ください。

次の表に、ヘルスチェックコード（アルファベット順）とそのコードの意味を示します。文字列 Err で終わるコードはエラーを示します。その他のコードは情報コードです。

ヘルスチェックコード	カテゴリ	意味	アドバイス
`DLApiConnErr`	接続	ダウンロードサブドメイン `dl.google.com` へのリクエストに失敗しました。	インターネット接続とファイアウォールルールを確認します。詳細については、ネットワーク接続の問題をご覧ください。
`FbMetricsPortErr`	ポートの可用性	Ops エージェントの自己指標に必要なポート 20202 を使用できません。	ポート 20202 が開いていることを確認します。詳細については、必要なポートを使用できないをご覧ください。
`HcFailureErr`	汎用	Ops エージェントのヘルスチェックルーチンで内部エラーが発生しました。	Google Cloud コンソールからサポートケースを送信します。詳細については、サポートの利用をご覧ください。
`LogApiConnErr`	接続	Logging API へのリクエストに失敗しました。	インターネット接続とファイアウォールルールを確認します。詳細については、ネットワーク接続の問題をご覧ください。
`LogApiDisabledErr`	API	Logging API が現在の Google Cloud プロジェクトで無効になっています。	Logging API を有効にします。
`LogApiPermissionErr`	権限	サービスアカウントにログ書き込みロール（`roles/logging.logWriter`）がありません。	サービスアカウントにログ書き込みロールを付与します。詳しくは、エージェントに API 権限がないをご覧ください。
`LogApiScopeErr`	権限	VM に https://www.googleapis.com/auth/logging.write アクセススコープがありません。	VM に https://www.googleapis.com/auth/logging.write スコープを追加します。詳細については、アクセススコープを確認するをご覧ください。
`LogApiUnauthenticatedErr`	API	現在の VM は Logging API で認証できませんでした。	認証情報ファイル、VM アクセススコープ、権限が正しく設定されていることを確認してください。詳細については、Ops エージェントを認可するをご覧ください。
`LogPingOpsAgent`		情報提供のペイロードメッセージが 10 分ごとに `ops-agent-health` ログに書き込まれます。生成されたログエントリを使用して、エージェントがログを送信していることを確認できます。このメッセージはエラーではありません。	このメッセージは 10 分ごとに表示されると予想されます。メッセージが 20 分以上表示されない場合、エージェントに問題が発生している可能性があります。トラブルシューティング情報については、Ops エージェントのトラブルシューティングをご覧ください。
`LogParseErr`	ランタイム	Ops エージェントが 1 つ以上のログを解析できませんでした。	作成したロギングプロセッサの構成を確認します。詳しくは、ログ解析エラーをご覧ください。
`LogPipeLineErr`	ランタイム	Ops エージェントのロギングパイプラインが失敗しました。	エージェントがバッファファイルにアクセスできることを確認します。ディスクの空き容量を確認し、Ops エージェントの構成が正しいことを確認します。詳細については、パイプラインエラーをご覧ください。
`MetaApiConnErr`	接続	VM アクセススコープ、OAuth トークン、リソースラベルをクエリするための GCE メタデータサーバーへのリクエストが失敗しました。	インターネット接続とファイアウォールルールを確認します。詳細については、ネットワーク接続の問題をご覧ください。
`MonApiConnErr`	接続	Monitoring API へのリクエストが失敗しました。	インターネット接続とファイアウォールルールを確認します。詳細については、ネットワーク接続の問題をご覧ください。
`MonApiDisabledErr`	API	Monitoring API が現在の Google Cloud プロジェクトで無効になっています。	Monitoring API を有効にします。
`MonApiPermissionErr`	権限	サービスアカウントに、モニタリング指標の書き込みロール（`roles/monitoring.metricWriter`）がありません。	サービスアカウントにモニタリング指標の書き込みのロールを付与します。詳しくは、エージェントに API 権限がないをご覧ください。
`MonApiScopeErr`	権限	VM に https://www.googleapis.com/auth/monitoring.write アクセススコープがありません。	VM に https://www.googleapis.com/auth/monitoring.write スコープを追加します。詳細については、アクセススコープを確認するをご覧ください。
`MonApiUnauthenticatedErr`	API	現在の VM は、Monitoring API で認証できませんでした。	認証情報ファイル、VM アクセススコープ、権限が正しく設定されていることを確認してください。詳細については、Ops エージェントを認可するをご覧ください。
`OtelMetricsPortErr`	ポートの可用性	Ops エージェントの自己指標に必要なポート 20201 を使用できません。	ポート 20201 が開いていることを確認します。詳細については、必要なポートを使用できないをご覧ください。
`PacApiConnErr`	接続	パッケージリポジトリ `packages.cloud.google.com` へのリクエストに失敗しました。	インターネット接続とファイアウォールルールを確認します。詳細については、ネットワーク接続の問題をご覧ください。

起動時のエラーを探す

バージョン 2.35.0 以降では、ヘルスチェック情報は、Cloud Logging API によって ops-agent-health ログに書き込まれます（バージョン 2.33.0、2.34.0 では ops-agent-health-checks が使用されます）。また、同じ情報が以下の health-checks.log ファイルにも書き込まれます。

Linux: /var/log/google-cloud-ops-agent/health-checks.log
Windows: C:\ProgramData\Google\Cloud Operations\Ops Agent\log\health-checks.log

次のように Ops エージェントサービスのステータスを照会して、ヘルスチェックメッセージを確認することもできます。

Linux の場合は、次のコマンドを実行します。
```
   sudo systemctl status google-cloud-ops-agent"*"
   
```
「[Ports Check] - Result: PASS」のようなメッセージを探します。その他の結果には「ERROR」と「FAIL」が含まれています。
Windows: Windows のイベントビューアを使用します。google-cloud-ops-agent サービスに関連付けられている「情報」、「エラー」、または「失敗」のメッセージを探します。

問題を解決したら、エージェントを再起動する必要があります。ヘルスチェックはエージェントの起動時に実行されるので、チェックを再実行するにはエージェントを再起動する必要があります。

ランタイムエラーを探す

ランタイムヘルスチェックは、Cloud Logging と Error Reporting の両方に報告されます。エージェントの起動に失敗しても、失敗する前にエラーを報告できた場合は、起動時のエラーも報告されます。

Logging で Ops エージェントからのランタイムエラーを確認する方法は次のとおりです。

Google Cloud コンソールのナビゲーションパネルで、[ロギング] を選択してから、[ログエクスプローラ] を選択します。
[ログエクスプローラ] に移動
次のクエリを入力し、[クエリを実行] をクリックします。
```
log_id("ops-agent-health")
```

Error Reporting で Ops エージェントからのランタイムエラーを表示する方法は次のとおりです。

Google Cloud コンソールのナビゲーションパネルで [エラーレポート] を選択し、Google Cloud プロジェクトを選択します。
Error Reporting に移動
Ops エージェントからのエラーを表示するには、Ops Agent のエラーをフィルタします。

ログ収集の成功を確認する

Ops エージェントのバージョン 2.46.0 では、情報提供目的の LogPingOpsAgent ヘルスチェックが導入されました。このチェックでは、10 分ごとに情報メッセージが ops-agent-health に書き込まれます。次のいずれかの方法で、これらのメッセージのプレゼンスを使用して、Ops エージェントがログを作成していることを確認できます。

ログエクスプローラを使用して、特定の VM のログで ping メッセージを検索します。
Metrics Explorer を使用して、特定の VM の指標 log_entry_count の値を確認します。
特定の VM が log_entry_count 指標を更新していない場合に通知するアラートポリシーを作成します。

これらのオプションのいずれかが、ログメッセージが取り込まれないことを示している場合は、次の操作を行います。

起動エラーまたはランタイムエラーを示すエラーコードを確認します。
Ops エージェントが稼働中かどうかを確認します。
エージェント診断スクリプトを実行します。

特定の VM で Ops エージェントのステータスを確認するには、VM のインスタンス ID が必要です。インスタンス ID を確認するには、次の操作を行います。

Google Cloud コンソールのナビゲーションパネルで、[Compute Engine] を選択してから、[VM インスタンス] を選択します。
[VM インスタンス] に移動
VM インスタンスの名前をクリックします。
[詳細] タブで、[基本情報] セクションを見つけます。インスタンス ID は数値文字列として表示されます。この文字列は、後続のセクションの INSTANCE_ID 値に使用します。

ログエクスプローラを使用してメッセージを検索する

ログエクスプローラを使用して VM のログで ping メッセージを検索するには、次の操作を行います。

Google Cloud コンソールのナビゲーションパネルで、[ロギング] を選択してから、[ログエクスプローラ] を選択します。
[ログエクスプローラ] に移動
特定の VM インスタンス上の Ops エージェントからの ping メッセージを検索するには、次のクエリを入力して、INSTANCE_ID を Compute Engine VM の識別子に置き換えてから、[クエリを実行] をクリックします。 :
```
resource.type="gce_instance"
resource.labels.instance_id="INSTANCE_ID"
log_id("ops-agent-health")
jsonPayload.code="LogPingOpsAgent"
    
```

`log_entry_count` 指標を表示する

Metrics Explorer を使用して VM の指標 log_entry_count の値を確認するには、次の操作を行います。

Google Cloud コンソールのナビゲーションパネルで [Monitoring] を選択し、次に [ Metrics Explorer] を選択します。
Metrics Explorer に移動
[指標を選択] フィールドで、次の操作を行います。
1. 「log entries」と入力します。
2. [リソースタイプ] に [VM インスタンス] を選択します。
3. [指標カテゴリ] で、[ログベースの指標] を選択します。
4. [指標] で [ログエントリ] を選択します。
5. [適用] を選択します。
[フィルタ ] フィールドに次のフィルタを追加します。
- 特定の VM のインスタンス ID でフィルタします。
  1. リソースラベル instance_id を選択します。
  2. コンパレータ [= (equals)] を選択します。
  3. VM の INSTANCE_ID を入力します。
- ops-agent-health ログをフィルタします。
  1. リソースラベル [log] を選択します。
  2. コンパレータ [= (equals)] を選択します。
  3. 値 [ops-agent-heath] を選択します。

`log_entry_count` 指標のアラートポリシーを作成する

特定の VM からのログ ping の log_entry_count 指標の値をモニタリングするアラートポリシーを作成するには、次の操作を行います。

Google Cloud コンソールのナビゲーションパネルで、[Monitoring] を選択してから、[アラート] を選択します。
アラートに移動
通知チャンネルを作成せずに通知を受け取る場合は、[Edit Notification Channels] をクリックして、通知チャンネルを追加します。チャンネルを追加したら、[アラート] ページに戻ります。
[アラート] ページで、[CREATE POLICY] をクリックします。
[指標を選択] フィールドで、次の操作を行います。
1. 「log entries」と入力します。
2. [リソースタイプ] に [VM インスタンス] を選択します。
3. [指標カテゴリ] で、[ログベースの指標] を選択します。
4. [指標] で [ログエントリ] を選択します。
5. [適用] を選択します。
[フィルタ ] フィールドに次のフィルタを追加します。
- 特定の VM のインスタンス ID でフィルタします。
  1. リソースラベル instance_id を選択します。
  2. コンパレータ [= (equals)] を選択します。
  3. VM の INSTANCE_ID を入力します。
- ops-agent-health ログをフィルタします。
  1. リソースラベル [log] を選択します。
  2. コンパレータ [= (equals)] を選択します。
  3. 値 [ops-agent-heath] を選択します。
[データの変換] セクションで、以下を選択します。
- [ローリングウィンドウ] フィールドで、[10 分] を選択します。長い期間にわたって欠落しているログエントリを検出するには、より大きな値を入力します。
- [ローリングウィンドウ関数] フィールドで [デルタ] を選択します。
[次へ] をクリックします。

[Configure alert trigger] ページの設定によって、アラートがトリガーされるタイミングが決まります。次のテーブルの設定を使用して、このページに入力します。

[Configure alert trigger] ページフィールド	値
`Condition type`	`Threshold`
`Alert trigger`	`Any time series violates`
`Threshold position`	`Below threshold`
`Threshold value`	`1`
`Advanced Options: Retest window`	`No retest`

[次へ] をクリックします。
（省略可）アラートポリシーに通知を追加するには、[通知チャネル] をクリックします。ダイアログで、メニューから 1 つ以上の通知チャンネルを選択し、[OK] をクリックします。
（省略可）インシデントの自動クローズ期間を更新します。このフィールドは、指標データがない場合に Monitoring がインシデントを閉じるタイミングを決定します。
（省略可）[Documentation] をクリックして、通知メッセージに追加する情報を入力します。
[アラート名] をクリックして、アラートポリシーの名前を入力します。
[ポリシーを作成] をクリックします。

詳細については、アラートポリシーをご覧ください。

VM 用エージェント診断ツール

エージェント診断ツールは、Ops エージェント、以前の Logging エージェント、以前の Monitoring エージェントのために VM から重要なローカルデバッグ情報を収集します。デバッグ情報には、プロジェクト情報、VM 情報、エージェント構成、エージェントログ、エージェントサービスステータス、収集に通常必要となる手作業の情報などが含まれます。このツールはローカル VM 環境を確認し、ネットワーク接続性や必要な権限など、エージェントが正常に機能するための特定の要件を満たしていることを保証します。

VM 上のエージェントのカスタマーケースを登録する場合は、エージェント診断ツールを実行し、収集した情報をケースに添付します。この情報を提供することで、サポートケースのトラブルシューティングにかかる時間を短縮できます。サポートケースに情報を添付する前に、パスワードなどの機密情報を削除してください。

エージェント診断ツールは VM 内から実行する必要があるため、まず VM に SSH 経由で接続する必要があります。次のコマンドは、エージェント診断ツールを取得して実行します。

Linux

curl -sSO https://dl.google.com/cloudagents/diagnose-agents.sh
sudo bash diagnose-agents.sh

Windows

(New-Object Net.WebClient).DownloadFile("https://dl.google.com/cloudagents/diagnose-agents.ps1", "${env:UserProfile}\diagnose-agents.ps1")
Invoke-Expression "${env:UserProfile}\diagnose-agents.ps1"

スクリプト実行の出力に従って、収集した情報を含むファイルを探します。スクリプトの実行時に出力ディレクトリをカスタマイズしない限り、このファイルは /var/tmp/google-agents ディレクトリ（Linux の場合）または $env:LOCALAPPDATA/Temp ディレクトリ（Windows の場合）にあります。

詳しくは、diagnose-agents.sh スクリプト（Linux の場合）または diagnose-agents.ps1 スクリプト（Windows の場合）をご覧ください。

自動インストールポリシーのエージェント診断ツール

Ops エージェントの OS ポリシーを使用した Ops エージェントのインストールが失敗した場合は、このセクションで説明する診断スクリプトを使用してデバッグできます。たとえば、次のいずれかのようになることがあります。

[モニタリングとロギング用の Ops エージェントをインストールする] チェックボックスを使用して VM の作成時に Ops エージェントをインストールした際に、Ops エージェントのインストールが失敗します。
Cloud Monitoring の [VM インスタンス] ダッシュボード、または Compute Engine VM の詳細ページの [オブザーバビリティ] タブに表示されるエージェントのステータスが 10 分以上 [保留中] 状態のままになります。ステータスが長い間 [保留中] になっている場合は、次のいずれかを示している可能性があります。
- ポリシーの適用に問題があります。
- Ops エージェントの実際のインストールに問題があります。
- VM と Cloud Monitoring 間の接続に問題があります。
これらの問題の中には、一般的なエージェント診断スクリプトとヘルスチェックが役に立つものがあります。

ポリシー診断スクリプトを実行するには、次のコマンドを実行します。

curl -sSO https://dl.google.com/cloudagents/diagnose-ui-policies.sh
bash diagnose-ui-policies.sh VM_NAME VM_ZONE

このスクリプトは、影響を受ける VM と関連する自動インストールポリシーに関する情報を表示します。

エージェントのステータス

VM 上の Ops エージェントプロセスのステータスを確認して、エージェントが実行中かどうかを判断できます。

Linux

Ops エージェントのステータスを確認するには、次のコマンドを使用します。

sudo systemctl status google-cloud-ops-agent"*"

次のサンプル出力に示すように、「Metrics Agent」と「Logging Agent」のコンポーネントが「active（実行中）」として表示されていることを確認します（簡潔にするために一部の行は削除されています）。

● google-cloud-ops-agent.service - Google Cloud Ops Agent
     Loaded: loaded (/lib/systemd/system/google-cloud-ops-agent.service; enabled; vendor preset: enabled)
     Active: active (exited) since Wed 2023-05-03 21:22:28 UTC; 4 weeks 0 days ago
    Process: 3353828 ExecStartPre=/opt/google-cloud-ops-agent/libexec/google_cloud_ops_agent_engine -in /etc/go>
    Process: 3353837 ExecStart=/bin/true (code=exited, status=0/SUCCESS)
   Main PID: 3353837 (code=exited, status=0/SUCCESS)
        CPU: 195ms

[...]

● google-cloud-ops-agent-opentelemetry-collector.service - Google Cloud Ops Agent - Metrics Agent
     Loaded: loaded (/lib/systemd/system/google-cloud-ops-agent-opentelemetry-collector.service; static)
     Active: active (running) since Wed 2023-05-03 21:22:29 UTC; 4 weeks 0 days ago
    Process: 3353840 ExecStartPre=/opt/google-cloud-ops-agent/libexec/google_cloud_ops_agent_engine -service=ot>
   Main PID: 3353855 (otelopscol)
      Tasks: 9 (limit: 2355)
     Memory: 65.3M
        CPU: 40min 31.555s
     CGroup: /system.slice/google-cloud-ops-agent-opentelemetry-collector.service
             └─3353855 /opt/google-cloud-ops-agent/subagents/opentelemetry-collector/otelopscol --config=/run/g>

[...]

● google-cloud-ops-agent-fluent-bit.service - Google Cloud Ops Agent - Logging Agent
     Loaded: loaded (/lib/systemd/system/google-cloud-ops-agent-fluent-bit.service; static)
     Active: active (running) since Wed 2023-05-03 21:22:29 UTC; 4 weeks 0 days ago
    Process: 3353838 ExecStartPre=/opt/google-cloud-ops-agent/libexec/google_cloud_ops_agent_engine -service=fl>
   Main PID: 3353856 (google_cloud_op)
      Tasks: 31 (limit: 2355)
     Memory: 58.3M
        CPU: 29min 6.771s
     CGroup: /system.slice/google-cloud-ops-agent-fluent-bit.service
             ├─3353856 /opt/google-cloud-ops-agent/libexec/google_cloud_ops_agent_wrapper -config_path /etc/goo>
             └─3353872 /opt/google-cloud-ops-agent/subagents/fluent-bit/bin/fluent-bit --config /run/google-clo>

[...]

● google-cloud-ops-agent-diagnostics.service - Google Cloud Ops Agent - Diagnostics
     Loaded: loaded (/lib/systemd/system/google-cloud-ops-agent-diagnostics.service; disabled; vendor preset: e>
     Active: active (running) since Wed 2023-05-03 21:22:26 UTC; 4 weeks 0 days ago
   Main PID: 3353819 (google_cloud_op)
      Tasks: 8 (limit: 2355)
     Memory: 36.0M
        CPU: 3min 19.488s
     CGroup: /system.slice/google-cloud-ops-agent-diagnostics.service
             └─3353819 /opt/google-cloud-ops-agent/libexec/google_cloud_ops_agent_diagnostics -config /etc/goog>

[...]

Windows

Ops エージェントのステータスを確認するには、次のコマンドを使用します。

Get-Service google-cloud-ops-agent*

次のサンプル出力に示すように、「Metrics Agent」と「Logging Agent」のコンポーネントが「Running」としてリストされていることを確認します。

Status   Name               DisplayName
------   ----               -----------
Running  google-cloud-op... Google Cloud Ops Agent
Running  google-cloud-op... Google Cloud Ops Agent - Logging Agent
Running  google-cloud-op... Google Cloud Ops Agent - Metrics Agent
Running  google-cloud-op... Google Cloud Ops Agent - Diagnostics

エージェントのセルフログ

エージェントが Cloud Logging へのログの取り込みに失敗した場合は、トラブルシューティングのために VM 上のエージェントのログをローカルで検査しなければならないことがあります。ログローテーションを使用して、エージェントのセルフログを管理することもできます。

Linux

Journald に書き込まれたセルフログを調べるには、次のコマンドを実行します。

journalctl -u google-cloud-ops-agent*

ロギングモジュールによってディスクに書き込まれたセルフログを調べるには、次のコマンドを実行します。

vim -M /var/log/google-cloud-ops-agent/subagents/logging-module.log

Windows

Windows Event Logs に書き込まれたセルフログを調べるには、次のコマンドを実行します。

Get-WinEvent -FilterHashtable @{ Logname='Application'; ProviderName='google-cloud-ops-agent*' } | Format-Table -AutoSize -Wrap

ロギングモジュールによってディスクに書き込まれたセルフログを調べるには、次のコマンドを実行します。

notepad "C:\ProgramData\Google\Cloud Operations\Ops Agent\log\logging-module.log"

Windows Service Control Manager から Ops エージェントサービスのログを調べるには、次のコマンドを実行します。

Get-WinEvent -FilterHashtable @{ Logname='System'; ProviderName='Service Control Manager' } | Where-Object -Property Message -Match 'Google Cloud Ops Agent' | Format-Table -AutoSize -Wrap

Cloud Monitoring で指標の使用状況と診断情報を表示する

Cloud Monitoring の [指標の管理] ページでは、オブザーバビリティに影響を与えることなく、課金対象の指標に費やす金額を制御するのに役立つ情報が提供されます。[指標の管理] ページには、次の情報が表示されます。

指標ドメイン全体と個々の指標での、バイトベースとサンプルベースの両方の課金に対する取り込み量。
指標のラベルとカーディナリティに関するデータ。
アラートポリシーとカスタムダッシュボードでの指標の使用。
指標書き込みエラーの割合。

[指標の管理] ページを表示するには、次の操作を行います。

Google Cloud コンソールのナビゲーションパネルで、[Monitoring] を選択してから、 [指標の管理] を選択します。
[指標の管理] に移動
ツールバーで時間枠を選択します。デフォルトでは、[指標の管理] ページには、過去 1 日間に収集された指標に関する情報が表示されます。

[指標の管理] ページの詳細については、指標の使用状況の表示と管理をご覧ください。