查找 Ops Agent 问题排查信息

本文档介绍诊断信息来源,可用于识别 Ops Agent 安装或运行中出现的问题。

使用 gcpdiag 验证代理状态

您可以使用 gcpdiag 报告项目中各个虚拟机或整个虚拟机舰队的 Ops Agent 状态,确认代理已安装并在主动发送日志和指标。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 支持团队打造,可帮助您自行诊断 Google Cloud 项目中的常见问题,包括 Ops Agent 相关问题。gcpdiag 是一款开源工具,虽然它不属于 Google Cloud 官方产品,但它是由 Google Cloud 支持团队开发和维护的。在 GitHub 上贡献或报告问题。

准备工作

gcpdiag 已与 Cloud Shell 集成,因此您无需执行任何安装即可运行它。如需运行 gcpdiag,您必须先满足以下前提条件:

  • 授权:gcpdiag 使用 Cloud Shell 中的应用默认凭据 (ADC) 进行身份验证。
    确保 gcpdiag 使用的凭据在运行 Ops Agent 的 Google Cloud 项目中至少具有以下角色:

    • Viewer (roles/viewer)
    • Service Usage Consumer (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 \
    
  • 虚拟机管理器:在您的实例上启用虚拟机管理器(免费层级)。如果您是在创建虚拟机期间安装的 Ops Agent,或者您的虚拟机实例上的 Ops Agent 安装是通过代理政策来管理的,则您已满足虚拟机管理器相关要求。

运行 gcpdiag

与 Ops Agent 搭配使用的 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 虚拟机的名称。可以使用 --name 选项查询特定虚拟机;省略该选项则可查询整个舰队。
  • 可以使用 --output 选项将报告保存为 CSV 或 JSON 格式文件;如果您不需要输出文件,则可省略此选项。

--include 选项的值指定一个或多个 gcpdiag 规则;gce/ERR/2024-004 是 Ops Agent 适用的规则。如需详细了解 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 规则指示符,该规则用来调用 gcpdiag 命令。对于 Ops Agent,此信息如下所示:
    🔎 gce/ERR/2024_004: Verify Ops Agent is installed on GCE VMs and is sending logs and metrics
  • 特定虚拟机的结果标识符,格式为 PROJECT_ID/INSTANCE_ID。在舰队级报告的输出中,每个虚拟机都有一个条目。而对于单一虚拟机的报告,输出仅包含针对该虚拟机的单个条目。
  • 检查返回的结果状态。状态具有以下某个值:
  • 状态值的说明。

以下部分将详细介绍状态值及其含义。

状态:OK

OK 状态表示 Ops Agent 在虚拟机上运行,并且在从虚拟机发送日志和指标。对于该状态,报告包含以下状态说明:
Ops Agent installed on the VM, and is successfully sending logs and metrics.

状态:FAIL

FAIL 状态表示 Ops Agent 未安装,或者 Ops Agent 未从虚拟机同时发送日志和指标。状态说明会指明检测到的具体问题:

  • 如果 Ops Agent 未安装,您会看到以下状态说明:
    Ops Agent not installed on the VM
  • 如果 Ops Agent 未从虚拟机同时发送日志和指标,您会看到如下所示的状态说明:
    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 Agent 未安装,请安装 Ops Agent。如果安装失败,则可能是以下某一问题所导致:

如果 Ops Agent 未从虚拟机发送日志或指标,请使用代理健康检查来查找启动时错误,以确定并纠正问题。

状态:SKIP

SKIP 状态表示 gcpdiag 无法确定虚拟机上是否安装了 Ops Agent。对于该状态,报告包含以下状态说明:
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 需要在您的虚拟机上运行虚拟机管理器。如要解决此问题,请在实例上安装虚拟机管理器(免费层级)。安装后,等待 15 分钟,然后尝试重新运行 gcpdiag 命令。

代理健康检查

2.25.1 版引入了 Ops Agent 的启动时健康检查。Ops Agent 会在启动时执行一系列检查,以发现阻止代理正常运行的情况。如果代理检测到其中一种情况,则会记录描述问题的消息。 Ops Agent 会检查以下内容:

  • 连接问题
  • 代理用于报告其相关指标的端口的可用性
  • 权限问题
  • 代理用于写入日志或指标的 API 的可用性
  • 健康检查例程本身的问题。
如需了解如何查找启动时错误,请参阅查找启动时错误

2.37.0 版引入了 Ops Agent 的运行时健康检查。这些错误会报告给 Cloud Logging 和 Error Reporting。如需了解如何查找运行时错误,请参阅查找运行时错误

2.46.0 版中引入了信息性代码 LogPingOpsAgent。此代码不表示错误。如需了解详情,请参阅验证是否成功收集了日志

下表按字母顺序列出了每个健康检查代码,并说明了每个代码的含义。以字符串 Err 结尾的代码表示错误;其他则为信息性代码。

健康检查代码 类别 含义 建议
DLApiConnErr 连接 向下载子网域 dl.google.com 发送的请求失败。 检查您的互联网连接和防火墙规则。如需了解详情,请参阅网络连接问题
FbMetricsPortErr 端口可用性 Ops Agent 自身指标所需的端口 20202 不可用。 验证端口 20202 是否已打开。如需了解详情,请参阅所需端口不可用
HcFailureErr 通用方法 Ops Agent 健康检查例程遇到内部错误。 通过 Google Cloud 控制台提交支持请求。如需了解详情,请参阅获取支持
LogApiConnErr 连接 对 Logging API 的请求失败。 检查您的互联网连接和防火墙规则。如需了解详情,请参阅网络连接问题
LogApiDisabledErr API Logging API 已在当前的 Google Cloud 项目中停用。 启用 Logging API
LogApiPermissionErr 权限 服务账号缺少 Logs Writer 角色 (roles/logging.logWriter)。 向服务账号授予 Logs Writer 角色。如需了解详情,请参阅 代理缺少 API 权限
LogApiScopeErr 权限 虚拟机缺少 https://www.googleapis.com/auth/logging.write 访问权限范围。 将 https://www.googleapis.com/​auth/​logging.write 范围添加到虚拟机。 如需了解详情,请参阅 验证访问权限范围
LogApiUnauthenticatedErr API 当前虚拟机无法向 Logging API 进行身份验证。 验证您的凭据文件、虚拟机访问权限范围和权限是否已正确设置。如需了解详情,请参阅向 Ops Agent 授权
LogPingOpsAgent   系统每 10 分钟向 ops-agent-health 日志写入一条信息性载荷消息。您可以使用生成的日志条目来验证代理是否在发送日志。此消息不是错误。 此消息预计每 10 分钟显示一次。如果此消息在 20 分钟或更长时间内没有显示,则代理可能遇到了问题。如需了解问题排查信息,请参阅排查 Ops Agent 问题
LogParseErr 运行时 Ops Agent 无法解析一个或多个日志。 检查您创建的所有日志记录处理器的配置。如需了解详情,请参阅日志解析错误
LogPipeLineErr 运行时 Ops Agent 的日志记录流水线失败。 验证代理有权访问缓冲区文件;检查磁盘是否已满,并验证 Ops Agent 配置正确无误。如需了解详情,请参阅流水线错误
MetaApiConnErr 连接 请求 GCE 元数据服务器(用于查询虚拟机访问权限范围、OAuth 令牌和资源标签)失败。 检查您的互联网连接和防火墙规则。如需了解详情,请参阅网络连接问题
MonApiConnErr 连接 向 Monitoring API 发出的请求失败。 检查您的互联网连接和防火墙规则。如需了解详情,请参阅网络连接问题
MonApiDisabledErr API Monitoring API 已在当前的 Google Cloud 项目中停用。 启用 Monitoring API
MonApiPermissionErr 权限 服务账号缺少 Monitoring Metric Writer 角色 (roles/monitoring.metricWriter)。 向服务账号授予 Monitoring Metric Writer 角色。如需了解详情,请参阅 代理缺少 API 权限
MonApiScopeErr 权限 虚拟机缺少 https://www.googleapis.com/​auth/​monitoring.write 访问权限范围。 向虚拟机添加 https://www.googleapis.com/​auth/​monitoring.write 范围。 如需了解详情,请参阅 验证访问权限范围
MonApiUnauthenticatedErr API 当前虚拟机无法向 Monitoring API 进行身份验证。 验证您的凭据文件、虚拟机访问权限范围和权限是否已正确设置。如需了解详情,请参阅向 Ops Agent 授权
OtelMetricsPortErr 端口可用性 Ops Agent 自身指标所需的端口 20201 不可用。 验证端口 20201 是否已打开。如需了解详情,请参阅所需的端口不可用
PacApiConnErr 连接 此健康检查代码不稳定。此代码已在 Ops Agent 2.46.1 版中被停用。 更新到 Ops Agent 2.46.1 版或更高版本。

查找启动时错误

从 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
  • WindowsC:\ProgramData\Google\Cloud Operations\Ops Agent\log\health-checks.log

您还可以通过查询 Ops Agent 服务的状态来查看任何健康检查消息,如下所示:

  • 在 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 Agent 的运行时错误,请执行以下操作:

  1. 在 Google Cloud 控制台中,转到 Logs Explorer 页面。

    前往 Logs Explorer

    如果您使用搜索栏查找此页面,请选择子标题为 Logging 的结果。

  2. 输入以下查询并点击运行查询
    log_id("ops-agent-health")

如需在 Error Reporting 中查看来自 Ops Agent 的运行时错误,请执行以下操作:

  1. 在 Google Cloud 控制台中,转到 Error Reporting 页面:

    前往 Error Reporting

    您也可以使用搜索栏查找此页面。

  2. 如需查看 Ops Agent 中的错误,请按 Ops Agent 过滤错误。

验证是否成功收集了日志

Ops Agent 2.46.0 版引入了信息性 LogPingOpsAgent 健康检查。此检查每 10 分钟会向 ops-agent-health 写入一条信息性消息。有了这些消息,您便可以通过执行以下任一操作来验证 Ops Agent 是否在写入日志:

如果上述任一操作表明未在注入日志消息,则您可以执行以下操作:

如需检查特定虚拟机上的 Ops Agent 状态,您需要该虚拟机的实例 ID。如需查找实例 ID,请执行以下操作:

  • 在 Google Cloud 控制台中,转到虚拟机实例页面:

    前往虚拟机实例

    如果您使用搜索栏查找此页面,请选择子标题为 Compute Engine 的结果。

  • 点击虚拟机实例的名称。
  • 详细信息标签页上,找到基本信息部分。实例 ID 以数值字符串显示。在后续部分中,此字符串将用作 INSTANCE_ID 值。

虚拟机的代理诊断工具

代理诊断工具会从虚拟机收集以下所有代理的关键本地调试信息:Ops Agent、旧版 Logging 代理和旧版 Monitoring 代理。调试信息包括项目信息、虚拟机信息、代理配置、代理日志、代理服务状态、通常需要手动收集的信息。该工具还会检查本地虚拟机环境,确保它满足代理正常运行的要求,例如网络连接和所需权限。

在虚拟机上提交代理的客户案例时,请运行代理诊断工具并将收集的信息附加到案例。提供此信息可以减少排查支持案例问题所需的时间。在将信息附加到支持案例之前,请隐去密码等任何敏感信息。

代理诊断工具必须从虚拟机内部运行,因此,通常需要先通过 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 Agent 操作系统政策安装 Ops Agent 失败,您可以使用本部分中所述的诊断脚本进行调试。例如,您可能会遇到以下某个情况:

  • 使用安装用于监控和日志记录的 Ops Agent 复选框在创建虚拟机期间安装 Ops Agent 时,Ops Agent 安装失败。
  • Cloud Monitoring 虚拟机实例信息中心或 Compute Engine 虚拟机详情页面上的可观测性标签页上的代理状态保持等待中状态超过 10 分钟。长时间的等待中状态可能表示有以下问题之一:

    • 应用政策时出现问题。
    • Ops Agent 的实际安装存在问题。
    • 虚拟机与 Cloud Monitoring 之间有连接问题。

    对于其中一些问题,常规的代理诊断脚本健康检查可能也有用。

如需运行政策诊断脚本,请运行以下命令:

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

此脚本显示受影响的虚拟机和相关自动安装政策的信息。

在虚拟机上提交代理的客户案例时,请运行代理诊断工具并将收集的信息附加到案例。提供此信息可以减少排查支持案例问题所需的时间。在将信息附加到支持案例之前,请隐去密码等任何敏感信息。

代理自身日志

如果代理无法将日志注入 Cloud Logging,您可能需要在虚拟机上本地检查代理的日志,以进行问题排查。您还可以使用日志轮换来管理代理的自身日志。

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 Agent 服务日志,请运行以下命令:

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 控制台中,转到 指标管理页面:

    进入指标管理

    如果您使用搜索栏查找此页面,请选择子标题为监控的结果。

  2. 在工具栏中,选择时间窗口。默认情况下,指标管理页面会显示有关前一天收集的指标的信息。

如需详细了解指标管理页面,请参阅查看和管理指标使用情况