本文档介绍诊断信息来源,可用于识别 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
)
- Viewer (
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 \
- Cloud Resource Manager API:
虚拟机管理器:在您的实例上启用虚拟机管理器(免费层级)。如果您是在创建虚拟机期间安装的 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。
- 虚拟机安装了某个旧版代理(Monitoring 代理或 Logging 代理)。如要解决此问题,卸载旧版代理,然后尝试重新安装 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
- Windows:
C:\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 的运行时错误,请执行以下操作:
-
在 Google Cloud 控制台中,转到 Logs Explorer 页面。
如果您使用搜索栏查找此页面,请选择子标题为 Logging 的结果。
- 输入以下查询并点击运行查询:
log_id("ops-agent-health")
如需在 Error Reporting 中查看来自 Ops Agent 的运行时错误,请执行以下操作:
-
在 Google Cloud 控制台中,转到 Error Reporting 页面:
您也可以使用搜索栏查找此页面。
- 如需查看 Ops Agent 中的错误,请按
Ops Agent
过滤错误。
验证是否成功收集了日志
Ops Agent 2.46.0 版引入了信息性 LogPingOpsAgent
健康检查。此检查每 10 分钟会向 ops-agent-health
写入一条信息性消息。有了这些消息,您便可以通过执行以下任一操作来验证 Ops Agent 是否在写入日志:
- 使用 Logs Explorer 在特定虚拟机的日志中搜索 ping 消息。
- 使用 Metrics Explorer 检查特定虚拟机的
log_entry_count
指标值。 - 创建一个提醒政策,在特定虚拟机未更新
log_entry_count
指标时通知您。
如果上述任一操作表明未在注入日志消息,则您可以执行以下操作:
如需检查特定虚拟机上的 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 指标管理页面提供的信息可帮助您控制在收费指标上支出的金额,而不会影响可观测性。指标管理页面报告以下信息:
- 针对指标网域中基于字节和基于样本的结算以及各个指标的注入量。
- 有关标签和指标基数的数据。
- 指标在提醒政策和自定义信息中心内的使用。
- 指标写入错误率。
如需查看指标管理页面,请执行以下操作:
-
在 Google Cloud 控制台中,转到
指标管理页面:如果您使用搜索栏查找此页面,请选择子标题为监控的结果。
- 在工具栏中,选择时间窗口。默认情况下,指标管理页面会显示有关前一天收集的指标的信息。
如需详细了解指标管理页面,请参阅查看和管理指标使用情况。