排查代理安装问题

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

学习要点

如果您在安装或使用 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)，则您可能正在运行来自于 Cloud Marketplace 的映像，而默认情况下 Monitoring 代理对于此类映像处于停用状态。此设置由 google-monitoring-enable 实例元数据键（值为 0）控制。要重新启用代理，请移除该键或将值设置为 1（请参阅设置实例元数据）。
  
  如果未通过元数据停用代理，请重新安装代理。请参阅下文中的重新安装代理部分。
查看代理是否向日志中写入了错误消息。
- 在 Windows 上，Monitoring 代理会将消息写入 Windows 事件日志。
- 在 Linux 上，Monitoring 代理是一个 collectd 程序包，会将日志消息记录到 /var/log/syslog 或 /var/log/messages 中。这些日志消息以 collectd 或 stackdriver-agent 为前缀：
  - 如果您看到 HTTP 429 错误，则表示您可能已经超出了您的 Monitoring API 配额。您可以通过在 GCP Console 中选择 API 和服务 > 信息中心来查看可用配额。选择 Monitoring API。
  - 如果您看到代理问题，请检查是否已正确配置您的 HTTP 代理。相关说明，请参阅在 Linux 上安装或在 Windows 上安装。
  - 如果您看到 API 访问权限或授权问题，或者“无法确定 collectd 端点”(Unable to determine collectd endpoint) 之类的错误消息，请参阅下面的验证项目和凭据部分。
  - 如果您在日志中看到“不受支持的 collectd 插件/类型组合”(Unsupported collectd plugin/type combination) 或“不受支持的 collectd id”(Unsupported collectd id) 错误，则您可能正在发送不受支持的代理指标。如果修改了某个代理第三方应用配置，就可能会发生这种情况。要还原更改，您可以按照相关文档页面中的说明，重新安装特定插件的配置。如果您要使用代理将该指标发送至 Monitoring，可考虑将其转换为自定义指标。
如果代理似乎运行正常，但您没有收到数据，或者提醒政策没有按您的预期发挥作用，则应检查代理是否正在向正确的项目发送数据。请参阅下面的验证项目和凭据部分。

验证项目和凭据

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

要查看数据是否到达了 Monitoring，请尝试读取一些时间序列数据。如需查看相关说明，请参阅验证代理到项目的连接。如果您确实看到了数据，则问题不是出在代理中。
如果您使用的是具有标准（非私钥）凭据的 Google Compute Engine 虚拟机实例，则数据不太可能发送到错误的项目，但您的凭据仍可能不足。如需了解凭据，请参阅为代理授权。要验证您的凭据，请参阅验证 Compute Engine 凭据。
如果您使用的是 Amazon EC2 虚拟机实例，或者如果您在 Google Compute Engine 实例上使用的是私钥凭据，则凭据可能无效，或者它们可能来自错误的项目。对于 AWS 帐号，代理使用的项目必须是 AWS 连接器项目（通常名为 "AWS Link..."）。如需了解凭据，请参阅为代理授权。要验证您的凭据，请参阅验证私钥凭据。

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

验证代理数据

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

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

确定安装了代理的虚拟机实例的实例 ID：
- Compute Engine：转到实例的 Compute Engine 的详情页面。在页面底部，点击等效 REST (Equivalent REST)。该 ID 是一个 19 位数字。
- Amazon EC2：每个实例的 ID 显示在实例列表中。该 ID 采用 i-1a2b3c4d 的格式。
转到 timeseries.list 方法的文档页面：

打开 timeseries.list 页面
在试试看! (Try it!) 部分中，点击使用 OAuth 2.0 授权请求 (Authorize requests using OAuth 2.0) 开关。不必进行任何改动，接受表单并点击授权。
填写 APIs Explorer 表单：
1. 将名称设置为包含您的虚拟机实例的项目，并以 projects/ 作为前缀，例如 projects/[YOUR_PROJECT_ID]。对于 Amazon EC2 实例，您必须为您的 Amazon 帐号使用 AWS 连接器项目，该帐号的名称通常以 "AWS Link" 开头。
2. 将过滤条件设置为以下行，以便从您的虚拟机实例中选择代理指标。复制该代理指标，并将其粘贴到 APIs 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. 将所有其他字段留空。
点击 Execute。

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

{
 "timeSeries": [
  {
   "metric": {
    "labels": {
     "state": "buffered"
    },
    "type": "agent.googleapis.com/memory/bytes_used"
   },
   "resource": {
    "type": "[GCP-OR-AWS-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、过滤条件和两个时间戳的拼写和格式。“未授权”(Not authorized) 错误可能意味着您的项目 ID 拼写错误。“未找到”(Not found) 错误可能表示“名称”字段中遗漏了必需的 projects/ 前缀。请修复问题并再次尝试调用 API。
如果 API 调用成功，但您看到的只是一个空的响应 ({ })，则检查您的过滤条件和时间间隔是否正确。时间戳格式错误可能会导致不返回数据。如果一切看起来都正确，但您没有收到数据，则说明代理未发送指标数据，或者至少未发送到您预期的项目。这可能表示凭据有问题；请参阅验证私钥凭据。

验证 Compute Engine 凭据

使用 GCP Console 的 Compute Engine > VM 实例页面，验证您的 Compute Engine 虚拟机实例是否拥有适用于 Monitoring 代理的足够凭据。凭据通常会添加到所有新的 Compute Engine 虚拟机实例的默认服务帐号中，但创建实例时可能会改写这些默认值。

打开“Compute Engine 实例”页面

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

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

验证私钥凭据

要验证虚拟机实例上是否安装了有效的私钥凭据，请首先验证凭据文件是否存在于其预期位置，然后验证凭据文件中的信息是否有效。可以使用 GCP Console 的 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 是您的 GCP 项目，client_email 标识项目中的服务帐号，private_key_id 则标识服务帐号中的私钥。将此信息与 GCP Console 的 IAM 和管理 > 服务帐号部分中显示的内容比对。

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

您检查的是 Compute Engine 实例，但凭据文件中的 GCP 项目不是包含您的实例的项目。
您检查的是 Amazon EC2 实例，但凭据文件中的 GCP 项目不是您的 AWS 帐号的连接器项目（名为 AWS Link...）。
列出的服务帐号不存在，可能已被删除。
列出的服务帐号没有启用正确的角色。它至少应具有 Monitoring 代理的 roles/monitoring.metricWriter（监控指标写入者）和 Logging 代理的 roles/logging.logWriter（日志写入者）。
私钥不存在，可能已被撤消。

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

生成新的凭据

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

对于每个包含需要用私钥授权的实例的已关联项目（所有 AWS 连接器项目和在没有监控范围的情况下创建的 Compute Engine 实例），创建一个服务帐号并生成一个私钥（如果它们尚不存在）。请按以下步骤操作：
1. 在此处打开连接到工作区的项目的列表。
  - 对于 AWS，使用链接直接导航到相关项目的 Cloud Console。
  - 对于 GCP，确定包含相关 Compute Engine 资源的项目并导航到 Cloud Console。
2. 从 Cloud Console 中导航到 IAM 服务帐号页面。
3. 创建一个新的服务帐号，并为其生成一个新的私钥。
  
  最简单的方法是下载一个具备正确配置的私钥。可通过在当前页面的基础上修改网址（即，将 &createStackdriverServiceAccount 附加到网址的末尾）来获取此密钥。如需了解详情，请参阅创建服务帐号。
  
  注意：上面的网址参数会自动下载一个密钥；服务帐号最多可以有 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 上，进入服务管理控制台，然后重启 Stackdriver Monitoring 服务。

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

要验证私钥是否正确，请参阅凭据是否存在？。具体来讲，执行以下操作：

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

重新安装代理

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

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