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

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

gcpdiag を使用してエージェントのステータスを確認する

gcpdiag を使用すると、個々の VM またはプロジェクト内の VM フリート全体で Ops エージェントのステータスを取得し、エージェントがインストールされ、ログと指標がアクティブに送信されていることを確認できます。gcpdiag では、CSV 形式や JSON 形式など、さまざまな形式でステータス レポートを作成できます。

以下に、フリート全体のエージェント ステータス レポートを CSV 形式で示します。

🔎 gce/ERR/2024_004: Verify Ops Agent is installed on GCE VMs and is sending logs and metrics.

gce/ERR/2024_004,projects/my-project/zones/my-location/instances/instance-1,failed,Ops Agent not installed on the VM,https://gcpdiag.dev/rules/gce/ERR/2024_004
gce/ERR/2024_004,projects/my-project/zones/my-location/instances/instance-2,skipped,VM Manager is needed for the ops agent detection. Please enable it at: https://cloud.google.com/compute/docs/manage-os#automatic and run this check again.,https://gcpdiag.dev/rules/gce/ERR/2024_004
gce/ERR/2024_004,projects/my-project/zones/my-location/instances/instance-3,skipped,VM Manager is needed for the ops agent detection. Please enable it at: https://cloud.google.com/compute/docs/manage-os#automatic and run this check again.,https://gcpdiag.dev/rules/gce/ERR/2024_004
gce/ERR/2024_004,projects/my-project/zones/my-location/instances/instance-4,ok,"Ops Agent installed on the VM, and is successfully sending logs and metrics.",https://gcpdiag.dev/rules/gce/ERR/2024_004
gce/ERR/2024_004,projects/my-project/zones/my-location/instances/instance-5,ok,"Ops Agent installed on the VM, and is successfully sending logs and metrics.",https://gcpdiag.dev/rules/gce/ERR/2024_004

gcpdiag ツールは、Google Cloud サポートが作成したもので、Ops エージェントの問題を含む、Google Cloud プロジェクトの一般的な問題を自己診断するのに役立ちます。gcpdiag は公式の Google Cloud プロダクトではなくオープンソースのツールですが、Google Cloud サポートチームによって積極的に開発とメンテナンスが行われています。GitHub で問題を投稿または報告します。

始める前に

gcpdiag は Cloud Shell と統合されているため、インストールを行わずに実行できます。gcpdiag を実行するには、まず次の前提条件を満たす必要があります。

• 認証: gcpdiag は、Cloud Shell のアプリケーションのデフォルトの認証情報（ADC）を使用して認証を行います。
  gcpdiag で使用する認証情報に、Ops エージェントが稼働している場所の Google Cloud プロジェクトに少なくとも次のロールがあることを確認してください

  • 閲覧者（roles/viewer）
  • Service Usage ユーザー (roles/serviceusage.serviceUsageConsumer)

• API: プロジェクトで gcpdiag を使用するには、次の API を有効にする必要があります。

  • Cloud Resource Manager API: cloudresourcemanager.googleapis.com
  • Identity and Access Management API: iam.googleapis.com
  • Cloud Logging API: logging.googleapis.com
  • Service Usage: serviceusage.googleapis.com

  これらの API を有効にするには、Cloud Shell で次のコマンドを実行します。 別のコマンドラインを使用します。

   gcloud --project=PROJECT_ID services enable \
     cloudresourcemanager.googleapis.com \
     iam.googleapis.com \
     logging.googleapis.com \
     serviceusage.googleapis.com
  

• VM Manager: インスタンスの無料枠で VM Manager を有効にします。Ops エージェントを VM の作成時にインストールするか、またはエージェント ポリシーによって VM インスタンスへの Ops エージェントのインストールが管理されている場合、VM Manager 用の要件はすでに満たされています。

gcpdiag を実行する

Ops エージェントで使用する gcpdiag コマンドの基本的な構文は次のとおりです。

gcpdiag lint --project=PROJECT_ID [--name=INSTANCE_NAME] --show-skipped --include=gce/err/2024_004 [--output=[CSV|JSON]]

• PROJECT_ID は、Google Cloud プロジェクトの ID です。
• INSTANCE_NAME は Compute Engine VM の名前です。特定の VM をクエリするには --name オプションを使用します。フリート全体をクエリするには、このオプションを省略します。
• --output オプションを使用して、レポートを CSV 形式または JSON 形式のファイルに保存します。出力ファイルを作成しない場合は、このオプションを省略します。

--include オプションの値には、1 つ以上の gcpdiag ルールを指定します。gce/ERR/2024-004 は Ops エージェントのルールです。gcpdiag コマンドの構文の詳細については、gcpdiag - Google Cloud Platform の診断をご覧ください。

たとえば、プロジェクト「my-project」のフリート全体のレポートを生成するには、次のコマンドを実行します。

gcpdiag lint --project=my-project --show-skipped --include=gce/ERR/2024_004

出力は次のようになります。

🔎 gce/ERR/2024_004: Verify Ops Agent is installed on GCE VMs and is sending logs and metrics.
  - my-project/instance-1                                                 [FAIL] Ops Agent not installed on the VM
  - my-project/instance-2                                                 [FAIL] Ops Agent not installed on the VM
  - my-project/instance-3                                                 [SKIP] Unable to confirm Ops Agent installation
  VM Manager is needed for the ops agent detection. Please enable it at: https://cloud.google.com/compute/docs/manage-os#automatic and run this check again.
  - my-project/instance-4                                            [FAIL] Ops Agent is installed, but it's failing to send both logs and metrics to Google Cloud.
  Is Ops Agent sending logs? (Yes)  Is Ops Agent sending metrics? (No)
  - my-project/instance-5                                                 [FAIL] Ops Agent is installed, but it's failing to send both logs and metrics to Google Cloud.
  Is Ops Agent sending logs? (No)   Is Ops Agent sending metrics? (No)
  - my-project/instance-6                                                 [ OK ] Ops Agent installed on the VM, and is successfully sending logs and metrics.
  - my-project/instance-7                                                 [ OK ] Ops Agent installed on the VM, and is successfully sending logs and metrics.

プロジェクト「my-project」のインスタンス「my-instance」のレポートを生成するには、次のコマンドを実行します。

gcpdiag lint  --project=my-project --name=my-instance --show-skipped --include=gce/err/2024_004

出力は次のようになります。

🔎 gce/ERR/2024_004: Verify Ops Agent is installed on GCE VMs and is sending logs and metrics.
  - my-project/my-instance   [ OK ] Ops Agent installed on the VM, and is successfully sending logs and metrics.

gcpdiag コマンドが失敗し、次のような出力が返される場合は、ツールを実行するためのすべての前提条件を満たしていることを確認します。

WARNING:googleapiclient.http:Encountered 403 Forbidden with reason "PERMISSION_DENIED"
[ERROR]:can't access project my-project: Cloud Resource Manager API has not been used in project my-project before or it is disabled. Enable it by visiting https://console.developers.google.com/apis/api/cloudresourcemanager.googleapis.com/overview?project=my-project then retry. If you enabled this API recently, wait a few minutes for the action to propagate to our systems and retry..
[DEBUG]: An Http Error occurred whiles accessing projects.get

HttpError 403 when requesting https://cloudresourcemanager.googleapis.com/v3/projects/my-project?alt=json returned Cloud Resource Manager API has not been used in project my-project before or it is disabled. Enable it by visiting https://console.developers.google.com/apis/api/cloudresourcemanager.googleapis.com/overview?project=my-project then retry. If you enabled this API recently, wait a few minutes for the action to propagate to our systems and retry. Details: ...
[ERROR]:exiting program...
error getting project details

gcpdiag の出力を解釈する

このセクションでは、gcpdiag によって生成されたレポートの理解と使用に役立つ情報を提供します。

gcpdiag コマンドは、次の情報が含まれるレポートを生成します。

• コマンドが呼び出された gcpdiag ルールのインジケーター。Ops エージェントの場合、この情報は次のようになります。
  🔎 gce/ERR/2024_004: Verify Ops Agent is installed on GCE VMs and is sending logs and metrics
• 特定の VM の結果の識別子（PROJECT_ID/INSTANCE_ID の形式）。フリート全体のレポートの場合、出力には VM ごとにエントリが含まれます。単一の VM レポートの場合、出力には単一のエントリが含まれます。
• チェックのステータス。ステータスは次のいずれかの値になります。
  • OK
  • FAIL
  • SKIP
• ステータス値の説明。

以降のセクションでは、ステータス値とその意味について詳しく説明します。

ステータス: OK

ステータスが OK の場合、Ops エージェントが VM で実行されており、VM からログと指標の両方を送信しています。レポートには、次のステータスの説明が含まれます。
Ops Agent installed on the VM, and is successfully sending logs and metrics.

ステータス: FAIL

ステータスが FAIL の場合、Ops エージェントがインストールされていないか、VM からログと指標の両方が送信されていません。ステータスの説明には、検出された問題が示されます。

• Ops エージェントがインストールされていない場合は、次のステータスの説明が表示されます。
  Ops Agent not installed on the VM
• Ops エージェントが VM からログと指標の両方を送信していない場合、次のステータスの説明が表示されます。
  Agent is installed, but it's failing to send both logs and metrics to Google Cloud.
Is Ops Agent sending logs? (Yes) Is Ops Agent sending metrics? (No)

Ops エージェントがインストールされていない場合は、Ops エージェントをインストールします。インストールに失敗した場合は、次のいずれかの問題が発生している可能性があります。

• VM に関連付けられているサービス アカウントがない。この問題を解決するには、VM にサービス アカウントを割り当ててから、もう一度 Ops エージェントのインストールを試みます。
• VM にいずれかの以前のエージェント（Monitoring エージェントまたは Logging エージェント）が すでにインストールされています。この問題を解決するには、以前のエージェントをアンインストールしてから、もう一度 Ops エージェントのインストールを試みます。

Ops エージェントが VM からログや指標を送信していない場合は、起動時エラーのエージェント ヘルスチェックで問題を特定して修正します。

ステータス: SKIP

ステータスが SKIP の場合、gcpdiag は VM に Ops エージェントがインストールされているかどうかを判断できていません。レポートには、次のステータスの説明が含まれます。
Unable to confirm Ops Agent installation
  VM Manager is needed for the ops agent detection.
  Please enable it at: https://cloud.google.com/compute/docs/manage-os#automatic and run this check again.

gcpdiag でエージェントのステータスをテストするには、VM で VM Manager が実行されている必要があります。この問題を解決するには、インスタンスに VM Manager の無料枠をインストールします。インストール後、15 分待ってから、gcpdiag コマンドを再度実行してみてください。

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

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

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

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

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

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

起動時のエラーを探す

バージョン 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 エージェントからのランタイム エラーを確認する方法は次のとおりです。

1. Google Cloud コンソールで、[ログ エクスプローラ] ページに移動します。

   [ログ エクスプローラ] に移動

   検索バーを使用してこのページを検索する場合は、小見出しが「Logging」の結果を選択します。

2. 次のクエリを入力し、[クエリを実行] をクリックします。
   

   log_id("ops-agent-health")

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

1. Google Cloud コンソールで、[Error Reporting] ページに移動します。

   Error Reporting に移動

   このページは、検索バーを使用して見つけることもできます。

2. 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 コンソールで、[VM インスタンス] ページに移動します。

  [VM インスタンス] に移動

  検索バーを使用してこのページを検索する場合は、小見出しが [Compute Engine] の結果を選択します。

• VM インスタンスの名前をクリックします。
• [詳細] タブで、[基本情報] セクションを見つけます。 インスタンス ID は数値文字列として表示されます。この文字列は、後続のセクションの INSTANCE_ID 値に使用します。

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

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

エージェントが 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 の [指標の管理] ページでは、オブザーバビリティに影響を与えることなく、課金対象の指標に費やす金額を制御するために役立つ情報が提供されます。[指標の管理] ページには、次の情報が表示されます。

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

また、指標の管理を使用して不要な指標を除外し、取り込みのコストを削減することもできます。

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

1. Google Cloud コンソールで、 query_stats[指標の管理] ページに移動します。

   [指標の管理] に移動

   検索バーを使用してこのページを検索する場合は、小見出しが [Monitoring] である結果を選択します。

2. ツールバーで時間枠を選択します。デフォルトでは、[指標の管理] ページには、過去 1 日間に収集された指標に関する情報が表示されます。

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