排查 Monitoring 代理问题

此页可帮助您诊断 Monitoring 代理安装或运行中出现的问题。

注意：如果您在 Linux 虚拟机 (VM) 上看到以下消息，可以放心地忽略它。

Need to set
  STACKDRIVER_API_KEY in /etc/sysconfig/stackdriver Not starting. Configuration
  error.

此消息是由旧版服务发出的，我们正在逐步替换旧版服务。此消息是良性的，最终会消失。

核对清单

如果您在安装或使用 Monitoring 代理时遇到问题，请检查以下几项：

如果 Linux 安装命令导致错误，请确保使用 sudo 作为安装命令的前缀。
验证代理服务是否正在虚拟机实例上运行：
- 对于 Windows 虚拟机，请使用以下 PowerShell 命令：
```
Get-Service -Name StackdriverMonitoring
```
  搜索名为 Stackdriver Monitoring 的服务。如果代理未在运行，您可能需要将其重启。
- 对于 Linux 虚拟机，请使用以下命令：
```
sudo service stackdriver-agent status
```
  如果代理未在运行，您可能需要使用以下命令将其重启：
```
sudo service stackdriver-agent restart
```
  如果重启失败，并且日志输出显示“已通过元数据停用”(Disabled via metadata)，则您可能正在运行来自于 Google Cloud Marketplace 的映像，而默认情况下 Monitoring 代理对于此类映像处于停用状态。此设置由 google-monitoring-enable 实例元数据键（值为 0）控制。要重新启用代理，请移除该键或将值设置为 1（请参阅设置实例元数据）。
  
  如果未通过元数据停用代理，请重新安装代理。如需了解此过程，请参阅重新安装 Monitoring 代理。
查看代理是否向日志中写入了错误消息。
- 在 Windows 上，Monitoring 代理会将消息写入 Windows 事件日志。
- 在 Linux 上，Monitoring 代理是一个 collectd 软件包，其消息会记录到 /var/log/syslog 或 /var/log/messages 中。日志消息以 collectd 或 stackdriver-agent 为前缀：
  - 如果您看到 HTTP 429 错误，则表示您可能已经超出了您的 Monitoring API 配额。您可以通过在 Google Cloud 控制台中选择 API 和服务 > 信息中心来查看可用配额。选择 Monitoring API。
  - 如果您看到代理问题，请检查是否已正确配置您的 HTTP 代理。相关说明，请参阅在 Linux 和 Windows 上安装。
  - 如果您看到 API 访问权限或授权问题，或者“无法确定 collectd 端点”之类的错误消息，请参阅下面的验证项目和凭据部分。
  - 如果您在日志中看到“不受支持的 collectd 插件/类型组合”或“不受支持的 collectd id”错误，则您可能正在发送不受支持的代理指标。这种情况可能发生在以下场景中：
    - 您修改了代理第三方应用配置之一。如需还原更改，您可以按照相关文档页面中的说明，重新安装特定插件的配置。如果要使用代理将指标发送到 Monitoring，请考虑将其转换为用户定义的指标。
    - 其中一个第三方应用插件会向 Monitoring 发送未知的新指标。请参阅支持页面，详细了解如何提交请求，以重新查看这些指标并进行分类。
如果代理似乎运行正常，但您没有收到数据，或者提醒政策没有按您的预期发挥作用，则应检查代理是否正在向正确的项目发送数据。请参阅下面的验证项目和凭据部分。

验证项目和凭据

如果 Monitoring 代理报告访问权限或授权错误；或者如果代理似乎运行正常，但没有数据；或者提醒政策没有按您的预期发挥作用；则检查您的虚拟机实例的凭据是否正确，包括它们是否指定了正确的项目：

如果您使用的是具有标准（非私钥）凭据的 Compute Engine 虚拟机实例，则数据不太可能发送到错误的项目，但您的凭据仍可能不足。如需了解凭据，请参阅向 Monitoring 代理授权。要验证您的凭据，请参阅验证 Compute Engine 凭据。
如果您使用的是 Amazon EC2 虚拟机实例，或者如果您在 Compute Engine 实例上使用私钥凭证，则凭证可能无效或者它们可能来自错误的项目。对于 AWS 账号，代理使用的项目必须是您要向其发送指标的 Google Cloud 项目。如需了解凭据，请参阅向 Monitoring 代理授权。要验证您的凭据，请参阅验证私钥凭据。

如果您仍然无法解决问题，请参阅重新安装 Monitoring 代理。

验证 Compute Engine 凭据

使用 Google Cloud 控制台的 Compute Engine 虚拟机实例页面来验证您的 Compute Engine 虚拟机实例具有足够的 Monitoring 代理凭据。凭据通常会添加到所有新的 Compute Engine 虚拟机实例的默认服务账号中，但创建实例时可能会覆盖这些默认值。

在 Google Cloud 控制台中，转到虚拟机实例页面：

前往虚拟机实例

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

如有必要，将当前 Google Cloud 项目更改为与您的 Compute Engine 虚拟机实例关联的一个项目。例如，如果系统提示您启用结算功能，则表示当前项目中没有任何 Compute Engine 虚拟机实例。
在虚拟机实例页面中，点击您的虚拟机实例的名称。随即会显示虚拟机实例的详情页面。
在虚拟机实例详情页面中，查看 Cloud API 访问权限范围标题下的内容：
- 如果看到“允许所有 Cloud API 的全面访问权限”，则表明您拥有足够的凭据。
- 如果您在 Stackdriver Monitoring API（Cloud Monitoring API 的旧名称）旁边看到您拥有只写或完整权限，则表明您拥有足够的凭据。
- 否则，实例的默认服务账号不具有代理所需的凭据。要在实例上使用代理，您必须添加私钥服务账号凭据。如需了解相关说明，请参阅添加凭据。

如果您拥有正确的默认凭据，请直接跳到在 Linux 和 Windows 上安装。

验证私钥凭据

要验证虚拟机实例上是否安装了有效的私钥凭据，请首先验证凭据文件是否存在于其预期位置，然后验证凭据文件中的信息是否有效。可以使用 Google Cloud 控制台的 IAM 和管理 > 服务账号部分撤消以前有效的凭据。如果不存在有效凭据，请参阅添加凭据，以替换现有凭据或添加新凭据。

凭据是否存在？

要查看您的实例上是否存在私钥服务账号凭据，请在您的实例上运行以下 Linux 命令：

sudo cat $GOOGLE_APPLICATION_CREDENTIALS
sudo cat /etc/google/auth/application_default_credentials.json

如果任一命令显示如下所示的文件，那么您的实例可能具有有效的私钥凭据。如果两个命令都显示文件，则会使用由 GOOGLE_APPLICATION_CREDENTIALS 表示的文件。

{
  "type": "service_account",
  "project_id": "{your-project-id}",
  "private_key_id": "{your-private-key-id}",
  "private_key": "{your-private-key}",
  "client_email": "{your-project-number}-{your-key}@developer.gserviceaccount.com",
  "client_id": "{your-client-id}",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://accounts.google.com/o/oauth2/token",
  "auth_provider_x509_cert_url": "{x509-cert-url}",
  "client_x509_cert_url": "{client-x509-cert-url}"
}

如果不存在凭据文件，请参阅添加凭据。

凭据是否有效？

在凭据文件中，project_id 字段是您的 Google Cloud 项目，client_email 标识项目中的服务账号，private_key_id 标识服务账号中的私钥。将此信息与 Google Cloud 控制台的 IAM 和管理 > 服务账号部分中显示的内容比对。

如果存在以下任一情况，则凭据文件无效：

您检查的是 Compute Engine 虚拟机实例，但凭据文件中的 Google Cloud 项目不是包含您的实例的项目。
您检查的是 Amazon EC2 实例，但凭据文件中的 Google Cloud 项目不是您从 AWS 账号发送指标的 Google Cloud 项目。
列出的服务账号不存在，可能已被删除。
列出的服务账号没有启用正确的角色。它至少应具有用于指标收集的 roles/monitoring.metricWriter (Monitoring Metric Writer)，以及用于写入日志的 roles/logging.logWriter (Logs Writer)。
私钥不存在，可能已被撤消。

如果服务账号没有问题，但私钥已被撤消，那么您可以创建一个新的私钥，并将其复制到您的实例。否则，您必须按照以下添加凭据部分中所述创建新的服务账号。

生成新的凭据

如果凭据无效，请执行以下步骤：

对于包含需要使用私钥授权的实例的每个关联项目 - 每个包含在创建时未包含访问范围 https://www.googleapis.com/auth/monitoring.write 的 Compute Engine 实例的项目 - 创建一个服务账号并生成一个私钥（如果它们尚不存在）。请按以下步骤操作：
1. 在 Google Cloud 控制台中，转到设置页面：
  前往设置
  
  如果您使用搜索栏查找此页面，请选择子标题为监控的结果。
2. 选择指标范围标签页。
3. 确定包含相关 Compute Engine 资源的项目，然后进入 Google Cloud 控制台。
4. 转到 Google Cloud 控制台的 IAM 服务账号页面，选择您的 Google Cloud 项目，创建一个新的服务账号，然后为该服务账号生成一个新的私钥。
  如需执行这些步骤，请执行以下操作之一：
  - 转到 IAM 服务账号页面，选择您的 Google Cloud 项目，然后按照创建服务账号中的步骤操作：
    
    转到 IAM 服务账号
  - 点击以下按钮，然后选择您的 Google Cloud 项目：
    
    创建服务账号并下载密钥
    
    上一个按钮可自动执行为特定于代理的服务账号创建密钥并下载到本地系统的流程。如有必要，该流程还会创建所需的服务账号，并确保该服务账号具有正确的权限。特定于代理的服务账号的名称形如 stackdriver-1234@PROJECT_ID.iam.gserviceaccount.com。系统会通过类似于以下内容的对话框通知您这些操作已完成：
  注意：服务账号最多可以有 10 个密钥。如需了解详情，请参阅限制。
替换与相关服务账号相对应的实例的私钥。
- 在 Linux 上，替换位于 /etc/google/auth/application_default_credentials.json 的私钥。
- 在 Windows 上，替换位于 C:\ProgramData\Google\Auth\application_default_credentials.json 的私钥。如需了解详情，请参阅将私钥复制到您的实例。
重启代理
- 在 Linux 上，运行 sudo service stackdriver-agent restart
- 在 Windows 上，进入服务管理控制台，然后重启 Cloud Monitoring 服务。

如果您有多个需要新私钥的项目，请为各个项目重复此过程。

要验证私钥是否正确，请参阅凭据是否存在？。具体而言：

读取实例上的私钥 JSON 文件，例如（在 Linux 上）：sudo cat /etc/google/auth/application_default_credentials.json
确保 project_id 字段的值与您刚为其生成凭据的受监控项目的值相匹配。

验证代理数据

要验证代理是否正确地发送指标，请使用 Monitoring API 的 timeSeries.list 方法，查找近期来自虚拟机实例的时间序列数据。您可以使用方法文档页面上的 API Explorer 来调用该方法。如果没有看到任何数据，则可能是代理正在向错误的项目发送数据。要检查这一点，请参阅验证项目和凭据。

以下是使用 timeSeries.list 方法的详细说明：

确定安装了代理的虚拟机实例的实例 ID：
- Compute Engine 实例：转到实例的 Compute Engine 详细信息页面。点击页面底部的 Equivalent REST。 ID 是一个 19 位数字。
- Amazon EC2 实例：每个实例的 ID 显示在实例列表中。该 ID 类似于 i-1a2b3c4d。
转到 timeSeries.list 方法的文档页面。
填写 APIs Explorer 表单：
1. 将名称设置为包含您的虚拟机实例的项目，并以 projects/ 作为前缀。例如 projects/[YOUR_PROJECT_ID]。
2. 将过滤条件设置为以下行，以便从您的虚拟机实例中选择代理指标。复制该代理指标，并将其粘贴到 API Explorer 中，然后更改虚拟机实例 ID：
```
metric.type = "agent.googleapis.com/memory/bytes_used" AND resource.label.instance_id = "[YOUR-VM-INSTANCE-ID]"
```
3. 设置搜索时间间隔。建议将间隔设置为大约五分钟：
  - 将 interval.endTime 设置为当前的 GMT 时间，该时间可以在 time.is/GMT 中找到。时间格式必须如下例所示。请勿将时间用引号括起来：
```
2016-10-31T14:10:00Z
```
  - 使用相同的格式，将 interval.startTime 设置为在结束时间之前大约五分钟。
4. 将所有其他字段留空。
点击执行。

您应该会看到如下所示的输出：

{
 "timeSeries": [
  {
   "metric": {
    "labels": {
     "state": "buffered"
    },
    "type": "agent.googleapis.com/memory/bytes_used"
   },
   "resource": {
    "type": "[INSTANCE-TYPE]",
    "labels": {
     "instance_id": "[YOUR-VM-INSTANCE-ID]",
     "zone": "[YOUR-INSTANCE-ZONE]",
     "project_id": "[YOUR-PROJECT-ID]"
    }
   },
   "metricKind": "GAUGE",
   "valueType": "DOUBLE",
   "points": [
    {
     "interval": {
      "startTime": "[START_TIME]",
      "endTime": "[END_TIME]"
     },
     "value": {
      "doubleValue": 27451392
     }
    },
    ...

如果 API 调用从您的虚拟机实例返回任何时间序列数据（如上所示），则表示您的代理运行正常；您已完成操作。

如果您没有看到任何时序数据，请检查以下各项：

如果您的 API 调用导致错误消息，这并不表示代理存在问题。请检查 APIs Explorer 字段是否填写正确：
- “参数无效”错误可能表示项目 ID、过滤条件或两个时间戳的拼写和格式有问题。
  
  对时间戳参数的要求取决于您指定的指标类型。指标类型记录 GAUGE、DELTA 或 CUMULATIVE 数据。如需了解详情，请参阅 MetricKind。
  
  对于 DELTA 和 CUMULATIVE 指标，必须提供间隔的开始时间和结束时间，并且结束时间必须晚于开始时间。这些类型的指标类型会记录随时间推移而变化的指标，因此开始时间和结束时间必须定义一个非零间隔。
- “未授权”错误可能意味着您拼错了项目 ID。
- “找不到”错误可能表示您在“名称”字段中省略了必需的 projects/ 前缀。
请修复问题并再次尝试调用 API。
如果 API 调用成功，但您看到的只是一个空的响应 { }，则检查您的过滤条件和时间间隔是否正确。时间戳格式错误可能会导致不返回数据。如果一切看起来都正确，但您没有收到数据，则说明代理未发送指标数据，或者至少未发送到您预期的项目。这可能表示凭据有问题；请参阅验证私钥凭据。

重新安装 Monitoring 代理

安装最新版本的代理可以解决许多问题：

如果您确定问题与凭据无关，则可以直接跳到在 Linux 和 Windows 上安装。
如需了解代理的完整安装过程和任何所需的凭据，请参阅安装 Monitoring 代理。

确定已安装代理的 Linux 虚拟机

运行以下任一查询以查看哪些 Linux 虚拟机正在运行代理：
- APIs Explorer
- 指标浏览器
请注意，对于每个查询，您必须输入项目名称并调整时间范围。

自动重启代理

您可以设置脚本以检查代理是否正在运行，然后在代理崩溃时重启代理。

例如，在 Linux 上，您可以创建以下 crontab 条目，每 5 分钟检查一次代理状态：

  */5 * * * * /bin/pidof stackdriver-collectd >/dev/null 2>&1 || /usr/sbin/service stackdriver-agent restart >/dev/null 2>&1

已知问题

以下各部分介绍了 Monitoring 代理的已知问题。

处理数据访问问题 (Windows)

您可能会在 Windows 事件日志中看到代理错误信息，如下所示：

Read access denied for processes: Registry (84), smss.exe (264), csrss.exe (376), wininit.exe (448), csrss.exe (456), services.exe (580), NisSrv.exe (3008), MsMpEng.exe (3624), csrss.exe (7044)

此消息表明代理无权访问您系统上的这些数据。要停止查看此消息，您可以向 SYSTEM 用户提供足够的权限，以读取错误消息中列出的进程和服务的进程数据。如果您不需要这些数据，则可以忽略这些信息性消息。

元数据缓存问题 (Linux)

您可能会在 Linux 系统日志文件（Debian/Ubuntu 上的 /var/log/syslog 或 Red Hat/CentOS/SLES 上的 /var/log/messages）看到类似以下内容的错误消息：

collectd[25571]: uc_update: Value too old: name = myhost/processes-all/ps_vm;
value time = 1511345468.180; last cache update = 1511345468.180;
write_gcm: wg_update_stats failed.
write_gcm: uc_update returned an error.

这些消息属于无害警告，并不表示数据会丢失。当时间戳不匹配时，这些消息由当前进程插件实现生成。

无限值数据点删除问题 (Linux)

您可能会在 Linux 系统日志文件（Debian/Ubuntu 上的 /var/log/syslog 或 Red Hat/CentOS/SLES 上的 /var/log/messages）看到类似以下内容的错误消息：

write_gcm: can not take infinite value

此消息表示已删除格式有误的数据点。这通常没有损害，可以忽略。

元数据键节流问题 (Linux)

您可能会在 Linux 系统日志文件（Debian/Ubuntu 上的 /var/log/syslog 或 Red Hat/CentOS/SLES 上的 /var/log/messages）看到类似以下内容的错误消息：

collectd[7440]:match_throttle_metadata_keys: uc_meta_data_add returned an error
collectd[7440]:match_throttle_metadata_keys: mtg_update_stats failed

此消息表明内存节流的状态更新失败。此错误通常无害，但可能表示代理内存不足，尤其是这种情况频繁发生时。

Cloud Monitoring API 配额用尽问题 (Linux)

您可能会在 Linux 系统日志文件（Debian/Ubuntu 上的 /var/log/syslog 或 Red Hat/CentOS/SLES 上的 /var/log/messages）看到类似以下内容的错误消息：

collectd[25198]: write_gcm: Unsuccessful HTTP request 429

此消息表示已达到 Cloud Monitoring API 配额上限。如需了解如何管理您的配额限制，请按照配额指南进行操作。

由于 `COLLECTD_INTERVAL` 较短导致内存用量高 (Linux)

如果 COLLECTD_INTERVAL 配置为小于默认的 60 seconds（例如 10 seconds），您可能会看到代理的内存用量较高。这是一个已知代理限制，因为它从单个线程串行发送请求。为了缓解此问题，请考虑仅对一部分必需指标缩短 COLLECTD_INTERVAL，并将其余指标保留为默认时间间隔。

令牌缓冲区溢出问题 (Linux)

您可能会在 Linux 系统日志文件（Debian/Ubuntu 上的/var/log / syslog 或 Red Hat /CentOS/SLES 上的/var / log / messages）中看到类似以下内容的错误消息：

write_gcm: Error or buffer overflow when building auth_header
write_gcm: wg_oauth2_get_auth_header failed.
write_gcm: wg_transmit_unique_segment failed.
write_gcm: wg_transmit_unique_segments failed. Flushing.

这些消息表示监控代理需要升级到 6.1.2 或更高版本。

仓库更改了其“Origin”值 (Linux)

升级代理、安装代理或在 Debian/Ubuntu Linux 上运行 apt-get update 时，您可能会看到如下所示的错误消息：

E: Repository 'https://packages.cloud.google.com/apt google-cloud-monitoring-buster-all InRelease' changed its 'Origin' value from 'google-cloud-monitoring-buster' to 'namespaces/cloud-ops-agents-artifacts/repositories/google-cloud-monitoring-buster-all'
E: Repository 'https://packages.cloud.google.com/apt google-cloud-monitoring-buster-all InRelease' changed its 'Label' value from 'google-cloud-monitoring-buster' to 'namespaces/cloud-ops-agents-artifacts/repositories/google-cloud-monitoring-buster-all'

此消息表明软件包仓库缓存可能与其来源存在差异。如需解决此问题，请运行以下命令：

apt-get --allow-releaseinfo-change update

然后，再次运行升级或安装。

移除了由 Google Cloud 控制台报告为已安装的代理

卸载代理后，Google Cloud 控制台最多可能需要一小时才能报告此更改。

Monitoring 代理未显示在 Windows“卸载程序”列表中

如需在 Windows 控制面板的卸载程序列表中未列出 Monitoring 代理时将其卸载，请从安装它的目录运行 uninstall.exe。

排查 Monitoring 代理问题

核对清单

验证项目和凭据

验证 Compute Engine 凭据

验证私钥凭据

凭据是否存在？

凭据是否有效？

生成新的凭据

验证代理数据

重新安装 Monitoring 代理

确定已安装代理的 Linux 虚拟机

自动重启代理

已知问题

处理数据访问问题 (Windows)

元数据缓存问题 (Linux)

无限值数据点删除问题 (Linux)

元数据键节流问题 (Linux)

Cloud Monitoring API 配额用尽问题 (Linux)

由于 COLLECTD_INTERVAL 较短导致内存用量高 (Linux)

令牌缓冲区溢出问题 (Linux)

仓库更改了其“Origin”值 (Linux)

移除了由 Google Cloud 控制台报告为已安装的代理

Monitoring 代理未显示在 Windows“卸载程序”列表中

由于 `COLLECTD_INTERVAL` 较短导致内存用量高 (Linux)