CloudWatch 代理故障排除
您可以使用本节中的信息排查 CloudWatch 代理可能遇到的问题。
主题
- CloudWatch 代理命令行参数
- 使用 Run Command 安装 CloudWatch 代理失败
- CloudWatch 代理无法启动
- 验证 CloudWatch 代理是否正在运行
- CloudWatch 代理未启动,并且错误中提及了 Amazon EC2 区域
- 无法在 Windows Server 上启动 CloudWatch 代理
- 指标存储在何处?
- CloudWatch 代理需要很长时间才能在容器中运行或记录跃点数限制错误
- 我更新了代理配置,但在 CloudWatch 控制台中看不到新的指标或日志
- CloudWatch 代理文件和位置
- 查找有关 CloudWatch 代理版本的信息
- CloudWatch 代理生成的日志
- 停止和重新启动 CloudWatch 代理
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。
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 代理的状态
通过 https://console.aws.amazon.com/systems-manager/
打开 Systems Manager 控制台。 在导航窗格中,选择 Run Command。
–或者–
如果打开了 AWS Systems Manager 主页,请向下滚动并选择 Explore Run Command(浏览 Run Command)。
-
选择 Run command(运行命令)。
-
在 Command document (命令文档) 列表中,选择 AmazonCloudWatch-ManageAgent 旁边的按钮。
-
在操作列表中,选择状态。
-
对于 Optional Configuration Source (可选的配置源),选择 default (默认值) 并将 Optional Configuration Location (可选的配置位置) 保留为空。
-
在目标区域,选择要检查的实例。
-
选择运行。
如果该代理正在运行,输出将类似于以下内容。
{ "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)。
无法在 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
指标存储在何处?
如果 CloudWatch 代理已运行,但在 AWS Management Console 或 AWS CLI 中找不到收集的指标,请确认使用的是正确的命名空间。默认情况下,该代理收集的指标的命名空间为 CWAgent
。您可以使用代理配置文件的 metrics
部分中的 namespace
字段自定义该命名空间。如果未看到所需的指标,请检查配置文件以确认正在使用该命名空间。
在首次下载 CloudWatch 代理软件包时,代理配置文件为 amazon-cloudwatch-agent.json
。该文件位于运行配置向导的目录中,或者您可能已将其移到其他目录中。如果使用配置向导,该向导的代理配置文件输出命名为 config.json
。有关配置文件(包括 namespace
字段)的更多信息,请参阅 CloudWatch 代理配置文件:Metrics(指标)部分。
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 之前的代理版本中,您可能会在没有看到日志消息的情况下遇到此问题。
要解决此问题,请按照配置实例元数据选项中的说明将跃点数限制增加到 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 位置 |
---|---|---|
控制代理的启动、停止和重新启动的控制脚本。 |
|
|
代理写入的日志文件。联系 AWS Support 时,您可能需要附上此信息。 |
|
|
代理配置验证文件。 |
|
|
在向导创建后立即用于配置代理的 JSON 文件。有关更多信息,请参阅 创建 CloudWatch 代理配置文件。 |
|
|
此 JSON 文件用于配置代理(如果此配置文件已从 Parameter Store 中下载)。 |
|
|
用于指定代理使用的区域和凭证信息的 TOML 文件(覆盖系统默认值)。 |
|
|
包含转换后的 JSON 配置文件内容的 TOML 文件。 |
|
|
包含转换后的 JSON 配置文件内容的 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-
region
.s3.region
.amazonaws.com/info/latest/RELEASE_NOTES -
https://amazoncloudwatch-agent.s3.amazonaws.com/info/latest/CWAGENT_VERSION
或https://amazoncloudwatch-agent-
region
.s3.region
.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 代理配置文件。
在版本 1.247350.0 和更高版本的 CloudWatch 代理中,您可以选择将代理配置文件内 agent
部分中的 aws_sdk_log_level
字段设置为以下一个或多个选项。使用 |
字符分隔多个选项。
LogDebug
LogDebugWithSigning
LogDebugWithHTTPBody
LogDebugRequestRetries
LogDebugWithEventStreamBody
有关这些选项的更多信息,请参阅 LogLevelType。
停止和重新启动 CloudWatch 代理
您可以使用 AWS Systems Manager 或命令行手动停止 CloudWatch 代理。
使用 Run Command 停止 CloudWatch 代理
通过 https://console.aws.amazon.com/systems-manager/
打开 Systems Manager 控制台。 在导航窗格中,选择 Run Command。
–或者–
如果打开了 AWS Systems Manager 主页,请向下滚动并选择 Explore Run Command(浏览 Run Command)。
-
选择 Run command(运行命令)。
-
在命令文档列表中,选择 AmazonCloudWatch-ManageAgent。
-
在 Targets(目标)区域中,选择安装了 CloudWatch 代理的实例。
-
在操作列表中,选择停止。
-
将 Optional Configuration Source (可选的配置源) 和 Optional Configuration Location (可选的配置位置) 保留空白。
-
选择运行。
使用命令行在本地停止 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 代理的通用配置和命名配置文件中的说明进行操作。