查找 Ops Agent 问题排查信息

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

代理健康检查

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`	连接	向软件包代码库 `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 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 控制台的导航面板中，选择 Logging，然后选择 Logs Explorer：
前往 Logs Explorer
输入以下查询并点击运行查询：
```
log_id("ops-agent-health")
```

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

在 Google Cloud 控制台的导航面板中，选择 Error Reporting，然后选择您的 Google Cloud 项目：
前往 Error Reporting
如需查看 Ops Agent 中的错误，请过滤“Ops Agent”的错误。

验证是否成功收集日志

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

使用日志浏览器搜索特定虚拟机的日志，查找 ping 消息。
使用 Metrics Explorer 检查特定虚拟机的 log_entry_count 指标的值。
创建提醒政策，以便在特定虚拟机未更新 log_entry_count 指标时收到通知。

如果其中任何选项表明日志消息未被提取，您可以执行以下操作：

检查指示启动错误或运行时错误的错误代码。
确定 Ops Agent 是否已启动并运行。
运行代理诊断脚本。

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

在 Google Cloud 控制台的导航面板中，选择 Compute Engine，然后选择虚拟机实例：
前往虚拟机实例
点击虚拟机实例的名称。
在详细信息标签页上，找到基本信息部分。实例 ID 以数字字符串的形式显示。在接下来的部分中，将此字符串用于 INSTANCE_ID 值。

使用 Logs Explorer 搜索消息

如需使用 Logs Explorer 在虚拟机的日志中搜索 ping 消息，请执行以下操作：

在 Google Cloud 控制台的导航面板中，选择 Logging，然后选择 Logs Explorer：
前往 Logs Explorer
如需查找来自特定虚拟机实例上的 Ops Agent 的 ping 消息，请输入以下查询并将 INSTANCE_ID 替换为 Compute Engine 虚拟机的标识符，然后点击运行查询：
```
resource.type="gce_instance"
resource.labels.instance_id="INSTANCE_ID"
log_id("ops-agent-health")
jsonPayload.code="LogPingOpsAgent"
    
```

查看“`log_entry_count`”指标

如需使用 Metrics Explorer 检查虚拟机的 log_entry_count 指标的值，请执行以下操作：

在 Google Cloud 控制台的导航面板中，选择 Monitoring，然后选择 Metrics Explorer：
进入 Metrics Explorer
在选择指标字段中，执行以下操作：
1. 输入 log entries。
2. 对于资源类型，选择虚拟机实例。
3. 对于指标类别，选择 Logs-based metrics。
4. 对于指标，选择日志条目。
5. 选择应用。
在过滤条件字段中，添加以下过滤条件：
- 针对特定虚拟机的实例 ID 进行过滤：
  1. 选择资源标签 instance_id。
  2. 选择比较运算符 =（等于）。
  3. 输入虚拟机的 INSTANCE_ID。
- 过滤 ops-agent-health 日志：
  1. 选择资源标签 log。
  2. 选择比较运算符 =（等于）。
  3. 选择值 ops-agent-heath。

为 `log_entry_count` 指标创建提醒政策

如需创建提醒政策来监控来自特定虚拟机的日志 ping 的 log_entry_count 指标的值，请执行以下操作：

在 Google Cloud 控制台的导航面板中，选择 Monitoring，然后选择提醒：
进入提醒
如果您尚未创建通知渠道并希望收到通知，请点击修改通知渠道并添加通知渠道。添加渠道后，返回到提醒页面。
在提醒页面中，点击创建政策。
在选择指标字段中，执行以下操作：
1. 输入 log entries。
2. 对于资源类型，选择虚拟机实例。
3. 对于指标类别，选择 Logs-based metrics。
4. 对于指标，选择日志条目。
5. 选择应用。
在过滤条件字段中，添加以下过滤条件：
- 针对特定虚拟机的实例 ID 进行过滤：
  1. 选择资源标签 instance_id。
  2. 选择比较运算符 =（等于）。
  3. 输入虚拟机的 INSTANCE_ID。
- 过滤 ops-agent-health 日志：
  1. 选择资源标签 log。
  2. 选择比较运算符 =（等于）。
  3. 选择值 ops-agent-heath。
在转换数据部分中，选择以下选项：
- 对于滚动窗口字段，选择 10 分钟。如需检测较长时间段内缺失的日志条目，请输入一个较大的值。
- 对于滚动窗口函数字段，选择增量。
点击下一步。

配置提醒触发器页面中的设置决定了何时触发提醒。使用下表中的设置完成此页面。

配置提醒触发器页面字段	值
`Condition type`	`Threshold`
`Alert trigger`	`Any time series violates`
`Threshold position`	`Below threshold`
`Threshold value`	`1`
`Advanced Options: Retest window`	`No retest`

点击下一步。
可选：如需将通知添加到您的提醒政策中，请点击通知渠道。在对话框中，从菜单中选择一个或多个通知渠道，然后点击确定。
可选：更新突发事件自动关闭持续时间。此字段用于确定在缺少指标数据的情况下 Monitoring 何时关闭突发事件。
可选：点击文档，然后添加您希望包含在通知消息中的任何信息。
点击提醒名称，然后输入提醒政策的名称。
点击创建政策。

如需了解详情，请参阅提醒政策。

虚拟机的代理诊断工具

代理诊断工具会从虚拟机收集以下所有代理的关键本地调试信息：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

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

代理状态

您可以检查虚拟机上 Ops Agent 进程的状态，以确定代理是否正在运行。

Linux

如需检查 Ops Agent 的状态，请使用以下命令：

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

验证“Metrics Agent”和“Logging Agent”组件是否列为“有效（正在运行）”，如以下示例输出所示（为简洁起见，已移除某些行）：

● 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 Agent 的状态，请使用以下命令：

Get-Service google-cloud-ops-agent*

验证“指标代理”和“Logging 代理”组件是否列为“正在运行”，如以下示例输出所示：

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，您可能需要在虚拟机本地检查代理的日志以排查问题。您还可以使用日志轮替管理代理本身的日志。

Linux

如需检查写入 Journald 的自身日志，请运行以下命令：

journalctl -u google-cloud-ops-agent*

如需检查日志记录模块写入磁盘的自身日志，请运行以下命令：

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