# CloudWatch 代理故障排除
您可以使用本节中的信息排查 CloudWatch 代理可能遇到的问题。
当 CloudWatch 代理出现问题时，可使用 `AWSSupport-TroubleshootCloudWatchAgent` 自动化运行手册进行故障处理。AWS 故障排查工具可以：
+ 验证 IAM 权限与实例配置文件
+ 检查代理状态并分析日志
+ 测试端点连通性
+ 自动采集相关日志并上传到 Amazon S3
有关 AWS 故障排查工具的详细信息，请参阅 [Support Automation Workflow (SAW) Runbook - Troubleshoot CloudWatch agent](https://repost.aws/articles/ARDFhNRgSMRcahrIbGJaIC4g/support-automation-workflow-saw-runbook-troubleshoot-amazon-cloudwatch-agent)。
**Topics**
+ [CloudWatch 代理命令行参数](#CloudWatch-Agent-options-help)
+ [使用 Run Command 安装 CloudWatch 代理失败](#CloudWatch-Agent-installation-fails)
+ [CloudWatch 代理无法启动](#CloudWatch-Agent-troubleshooting-cannot-start)
+ [验证 CloudWatch 代理是否正在运行](#CloudWatch-Agent-troubleshooting-verify-running)
+ [CloudWatch 代理未启动，并且错误中提及了 Amazon EC2 区域](#CloudWatch-Agent-troubleshooting-EC2-region)
+ [无法在 Windows Server 上启动 CloudWatch 代理](#CloudWatch-Agent-troubleshooting-Windows-start)
+ [指标存储在何处？](#CloudWatch-Agent-troubleshooting-no-metrics)
+ [CloudWatch 代理需要很长时间才能在容器中运行或记录跃点数限制错误](#CloudWatch-Agent-container-slow)
+ [我更新了代理配置，但在 CloudWatch 控制台中看不到新的指标或日志](#CloudWatch-Agent-troubleshooting-update-no-new-metrics)
+ [CloudWatch 代理文件和位置](#CloudWatch-Agent-files-and-locations)
+ [查找有关 CloudWatch 代理版本的信息](#CloudWatch-Agent-troubleshooting-agent-version)
+ [CloudWatch 代理生成的日志](#CloudWatch-Agent-troubleshooting-loginfo)
+ [停止和重新启动 CloudWatch 代理](#CloudWatch-Agent-troubleshooting-stopping-restarting)
## CloudWatch 代理命令行参数
要查看 CloudWatch 代理支持的参数的完整列表，请在安装了此代理的电脑上的命令行处输入以下命令：
```
amazon-cloudwatch-agent-ctl -help
```
## 使用 Run Command 安装 CloudWatch 代理失败
要使用 Systems Manager Run Command 安装 CloudWatch 代理，目标服务器上的 SSM Agent 必须为 SSM Agent 代理 2.2.93.0 或更高版本。如果 SSM Agent 不是正确的版本，您可能会看到以下错误消息：
```
no latest version found for package AmazonCloudWatchAgent on platform linux
```
```
failed to download installation package reliably
```
有关更新 SSM Agent 版本的信息，请参阅 *AWS Systems Manager 用户指南*中的[安装和配置 SSM Agent](https://docs.aws.amazon.com/systems-manager/latest/userguide/ssm-agent.html)。
## CloudWatch 代理无法启动
如果 CloudWatch 代理无法启动，则您的配置可能存在问题。配置信息会记录到 `configuration-validation.log` 文件中。在 Linux 服务器上，该文件位于 `/opt/aws/amazon-cloudwatch-agent/logs/configuration-validation.log` 中，在运行 Windows Server 的服务器上，该文件位于 `$Env:ProgramData\Amazon\AmazonCloudWatchAgent\Logs\configuration-validation.log` 中。
## 验证 CloudWatch 代理是否正在运行
您可以查询 CloudWatch 代理以确定它是正在运行还是已停止。可使用 AWS Systems Manager 远程执行此操作。也可以使用命令行，但仅用于检查本地服务器。
**使用 Run Command 查询 CloudWatch 代理的状态**
1. 通过 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/) 打开 Systems Manager 控制台。
1. 在导航窗格中，选择 **Run Command**。
–或者–
如果打开了 AWS Systems Manager 主页，请向下滚动并选择 **Explore Run Command（浏览 Run Command）**。
1. 选择 **Run command（运行命令）**。
1. 在 **Command document (命令文档)** 列表中，选择 **AmazonCloudWatch-ManageAgent** 旁边的按钮。
1. 在**操作**列表中，选择**状态**。
1. 对于 **Optional Configuration Source (可选的配置源)**，选择 **default (默认值)** 并将 **Optional Configuration Location (可选的配置位置)** 保留为空。
1. 在**目标**区域，选择要检查的实例。
1. 选择**运行**。
如果该代理正在运行，输出将类似于以下内容。
```
{
"status": "running",
"starttime": "2017-12-12T18:41:18",
"version": "1.73.4"
}
```
如果该代理已停止，`"status"` 字段将显示 `"stopped"`。
**使用命令行在本地查询 CloudWatch 代理的状态**
+ 在 Linux 服务器上，输入以下命令：
```
sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -m ec2 -a status
```
在运行 Windows Server 的服务器上，以管理员身份在 PowerShell 中输入以下命令：
```
& $Env:ProgramFiles\Amazon\AmazonCloudWatchAgent\amazon-cloudwatch-agent-ctl.ps1 -m ec2 -a status
```
## CloudWatch 代理未启动，并且错误中提及了 Amazon EC2 区域
如果代理将不会启动，并且错误消息中提及了 Amazon EC2 区域端点，则您可能已将代理配置为需要访问 Amazon EC2 端点但未授予该访问权限。
例如，如果您在代理配置文件中为 `append_dimensions` 参数指定一个值（取决于 Amazon EC2 元数据），并且使用代理，则必须确保服务器能够访问 Amazon EC2 的端点。有关这些端点的更多信息，请参阅 *Amazon Web Services 一般参考* 中的 [Amazon Elastic Compute Cloud（Amazon EC2）](https://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region)。
## 无法在 Windows Server 上启动 CloudWatch 代理
在 Windows Server 上，您可能会看到以下错误：
```
Start-Service : Service 'Amazon CloudWatch Agent (AmazonCloudWatchAgent)' cannot be started due to the following
error: Cannot start service AmazonCloudWatchAgent on computer '.'.
At C:\Program Files\Amazon\AmazonCloudWatchAgent\amazon-cloudwatch-agent-ctl.ps1:113 char:12
+ $svc | Start-Service
+ ~~~~~~~~~~~~~
+ CategoryInfo : OpenError: (System.ServiceProcess.ServiceController:ServiceController) [Start-Service],
ServiceCommandException
+ FullyQualifiedErrorId : CouldNotStartService,Microsoft.PowerShell.Commands.StartServiceCommand
```
要修复此问题，首先确保该服务器服务正在运行。如果代理在服务器服务未运行时尝试启动，则可能看到此错误。
如果服务器服务已在运行中，可能出现以下问题。在某些 Windows Server 安装中，CloudWatch 代理需要超过 30 秒才能启动。由于默认情况下，Windows Server 的服务启动超时只有 30 秒，因此这会导致代理失败，并出现类似于以下内容的错误：
要解决此问题，请增加服务超时值。有关详细信息，请参阅[服务无法启动，并在 Windows 事件日志中记录事件 7000 和 7011](https://support.microsoft.com/en-us/help/922918/a-service-does-not-start-and-events-7000-and-7011-are-logged-in-window)。
## 指标存储在何处？
如果 CloudWatch 代理已运行，但在 AWS 管理控制台 或 AWS CLI 中找不到收集的指标，请确认使用的是正确的命名空间。默认情况下，该代理收集的指标的命名空间为 `CWAgent`。您可以使用代理配置文件的 `metrics` 部分中的 `namespace` 字段自定义该命名空间。如果未看到所需的指标，请检查配置文件以确认正在使用该命名空间。
在首次下载 CloudWatch 代理软件包时，代理配置文件为 `amazon-cloudwatch-agent.json`。该文件位于运行配置向导的目录中，或者您可能已将其移到其他目录中。如果使用配置向导，该向导的代理配置文件输出命名为 `config.json`。有关配置文件（包括 `namespace` 字段）的更多信息，请参阅[CloudWatch 代理配置文件：Metrics（指标）部分](CloudWatch-Agent-Configuration-File-Details.md#CloudWatch-Agent-Configuration-File-Metricssection)。
## CloudWatch 代理需要很长时间才能在容器中运行或记录跃点数限制错误
当您将 CloudWatch 代理作为容器服务运行，并希望将 Amazon EC2 指标维度添加到代理收集的所有指标时，您可能会在该代理的 v1.247354.0 版中看到以下错误：
```
2022-06-07T03:36:11Z E! [processors.ec2tagger] ec2tagger: Unable to retrieve Instance Metadata Tags. This plugin must only be used on an EC2 instance.
2022-06-07T03:36:11Z E! [processors.ec2tagger] ec2tagger: Please increase hop limit to 2 by following this document https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-options.html#configuring-IMDS-existing-instances.
2022-06-07T03:36:11Z E! [telegraf] Error running agent: could not initialize processor ec2tagger: EC2MetadataRequestError: failed to get EC2 instance identity document
caused by: EC2MetadataError: failed to make EC2Metadata request
status code: 401, request id:
caused by:
```
如果代理尝试从容器内的 IMDSv2 获取元数据，而没有适当的跃点数限制，则可能会看到此错误。在 v1.247354.0 之前的代理版本中，您可能会在没有看到日志消息的情况下遇到此问题。
要解决此问题，请按照[配置实例元数据选项](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-options.html#configuring-IMDS-existing-instances.)中的说明将跃点数限制增加到 2。
## 我更新了代理配置，但在 CloudWatch 控制台中看不到新的指标或日志
如果您更新 CloudWatch 代理配置文件，则下次启动代理时需要使用 **fetch-config** 选项。例如，如果您将更新的文件存储在本地计算机上，请输入以下命令：
```
sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -a fetch-config -s -m ec2 -c file:configuration-file-path
```
## CloudWatch 代理文件和位置
下表列出了 CloudWatch 代理安装和使用的文件及其在运行 Linux 或 Windows Server 的服务器上的位置。
| 文件 | Linux 位置 | Windows Server 位置 |
| --- | --- | --- |
| 控制代理的启动、停止和重新启动的控制脚本。 | `/opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl` 或 `/usr/bin/amazon-cloudwatch-agent-ctl` | `$Env:ProgramFiles\Amazon\AmazonCloudWatchAgent\amazon-cloudwatch-agent-ctl.ps1` |
| 代理写入的日志文件。联系 AWS 支持 时，您可能需要附上此信息。 | `/opt/aws/amazon-cloudwatch-agent/logs/amazon-cloudwatch-agent.log` 或 `/var/log/amazon/amazon-cloudwatch-agent/amazon-cloudwatch-agent.log` | `$Env:ProgramData\Amazon\AmazonCloudWatchAgent\Logs\amazon-cloudwatch-agent.log` |
| 代理配置验证文件。 | `/opt/aws/amazon-cloudwatch-agent/logs/configuration-validation.log` 或 `/var/log/amazon/amazon-cloudwatch-agent/configuration-validation.log` | `$Env:ProgramData\Amazon\AmazonCloudWatchAgent\Logs\configuration-validation.log` |
| 在向导创建后立即用于配置代理的 JSON 文件。有关更多信息，请参阅 [创建 CloudWatch 代理配置文件](create-cloudwatch-agent-configuration-file.md)。 | `/opt/aws/amazon-cloudwatch-agent/bin/config.json` | `$Env:ProgramFiles\Amazon\AmazonCloudWatchAgent\config.json` |
| 此 JSON 文件用于配置代理（如果此配置文件已从 Parameter Store 中下载）。 | `/opt/aws/amazon-cloudwatch-agent/etc/amazon-cloudwatch-agent.json` 或 `/etc/amazon/amazon-cloudwatch-agent/amazon-cloudwatch-agent.json` | `$Env:ProgramData\Amazon\AmazonCloudWatchAgent\amazon-cloudwatch-agent.json` |
| 用于指定代理使用的区域和凭证信息的 TOML 文件（覆盖系统默认值）。 | `/opt/aws/amazon-cloudwatch-agent/etc/common-config.toml` 或 `/etc/amazon/amazon-cloudwatch-agent/common-config.toml` | `$Env:ProgramData\Amazon\AmazonCloudWatchAgent\common-config.toml` |
| 包含转换后的 JSON 配置文件内容的 TOML 文件。`amazon-cloudwatch-agent-ctl` 脚本会生成此文件。用户不应直接修改此文件。它对于验证 JSON 到 TOML 的转换是否成功很有用。 | `/opt/aws/amazon-cloudwatch-agent/etc/amazon-cloudwatch-agent.toml` 或 `/etc/amazon/amazon-cloudwatch-agent/amazon-cloudwatch-agent.toml` | `$Env:ProgramData\Amazon\AmazonCloudWatchAgent\amazon-cloudwatch-agent.toml` |
| 包含转换后的 JSON 配置文件内容的 YAML 文件。`amazon-cloudwatch-agent-ctl` 脚本会生成此文件。您不应直接修改此文件。此文件对于验证 JSON 到 YAML 的转换是否成功非常有用。 | `/opt/aws/amazon-cloudwatch-agent/etc/amazon-cloudwatch-agent.yaml or /etc/amazon/amazon-cloudwatch-agent/amazon-cloudwatch-agent.yaml` | `$Env:ProgramData\Amazon\AmazonCloudWatchAgent\amazon-cloudwatch-agent.yaml` |
## 查找有关 CloudWatch 代理版本的信息
要在 Linux 服务器上查找 CloudWatch 代理的版本号，请输入以下命令：
```
sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -a status
```
要在 Windows Server 上查找 CloudWatch 代理的版本号，请输入以下命令：
```
& $Env:ProgramFiles\Amazon\AmazonCloudWatchAgent\amazon-cloudwatch-agent-ctl.ps1 -m ec2 -a status
```
**注意**
使用此命令是查找 CloudWatch 代理版本的正确方法。如果您使用控制面板中的 **Program and Features（程序和功能）**，您看到的版本号将不是正确的版本号。
您也可以下载有关代理的最新更改的 README 文件，以及指示当前可供下载的版本号的文件。这些文件位于以下位置：
+ `https://amazoncloudwatch-agent.s3.amazonaws.com/info/latest/RELEASE_NOTES` 或 `https://amazoncloudwatch-agent-us-east-1.s3.us-east-1.amazonaws.com/info/latest/RELEASE_NOTES`
+ `https://amazoncloudwatch-agent.s3.amazonaws.com/info/latest/CWAGENT_VERSION` 或 `https://amazoncloudwatch-agent-us-east-1.s3.us-east-1.amazonaws.com/info/latest/CWAGENT_VERSION`
## CloudWatch 代理生成的日志
该代理在运行时生成一个日志。该日志包含故障排除信息。该日志是 `amazon-cloudwatch-agent.log` 文件。在 Linux 服务器上，该文件位于 `/opt/aws/amazon-cloudwatch-agent/logs/amazon-cloudwatch-agent.log` 中，在运行 Windows Server 的服务器上，该文件位于 `$Env:ProgramData\Amazon\AmazonCloudWatchAgent\Logs\amazon-cloudwatch-agent.log` 中。
您可以将代理配置为在 `amazon-cloudwatch-agent.log` 文件中记录其他详细信息。在代理配置文件的 `agent` 部分中，将 `debug` 字段设置为 `true`，然后重新配置并重新启动 CloudWatch 代理。要禁用该额外信息的日志记录，请将 `debug` 字段设置为 `false`。然后重新配置并重启该代理。有关更多信息，请参阅 [手动创建或编辑 CloudWatch 代理配置文件](CloudWatch-Agent-Configuration-File-Details.md)。
在版本 1.247350.0 和更高版本的 CloudWatch 代理中，您可以选择将代理配置文件内 `agent` 部分中的 `aws_sdk_log_level` 字段设置为以下一个或多个选项。使用 `|` 字符分隔多个选项。
+ `LogDebug`
+ `LogDebugWithSigning`
+ `LogDebugWithHTTPBody`
+ `LogDebugRequestRetries`
+ `LogDebugWithEventStreamBody`
有关这些选项的更多信息，请参阅 [LogLevelType](https://docs.aws.amazon.com/sdk-for-go/api/aws/#LogLevelType)。
## 停止和重新启动 CloudWatch 代理
您可以使用 AWS Systems Manager 或命令行手动停止 CloudWatch 代理。
**使用 Run Command 停止 CloudWatch 代理**
1. 通过 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/) 打开 Systems Manager 控制台。
1. 在导航窗格中，选择 **Run Command**。
–或者–
如果打开了 AWS Systems Manager 主页，请向下滚动并选择 **Explore Run Command（浏览 Run Command）**。
1. 选择 **Run command（运行命令）**。
1. 在**命令文档**列表中，选择 **AmazonCloudWatch-ManageAgent**。
1. 在 **Targets（目标）**区域中，选择安装了 CloudWatch 代理的实例。
1. 在**操作**列表中，选择**停止**。
1. 将 **Optional Configuration Source (可选的配置源)** 和 **Optional Configuration Location (可选的配置位置)** 保留空白。
1. 选择**运行**。
**使用命令行在本地停止 CloudWatch 代理**
+ 在 Linux 服务器上，输入以下命令：
```
sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -m ec2 -a stop
```
在运行 Windows Server 的服务器上，以管理员身份在 PowerShell 中输入以下命令：
```
& $Env:ProgramFiles\Amazon\AmazonCloudWatchAgent\amazon-cloudwatch-agent-ctl.ps1 -m ec2 -a stop
```
要重新启动该代理，请按照[（可选）修改 CloudWatch 代理的通用配置和命名配置文件](installing-cloudwatch-agent-ssm.md#CloudWatch-Agent-profile-instance-fleet)中的说明进行操作。