CloudWatch 代理故障排除 - Amazon CloudWatch
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

CloudWatch 代理故障排除

可以使用以下信息帮助解决 CloudWatch 代理问题。

CloudWatch 代理命令行参数

要查看 CloudWatch 代理支持的参数的完整列表,请在安装了此代理的电脑上的命令行处输入以下命令:

amazon-cloudwatch-agent-ctl -help

使用 Run Command 安装 CloudWatch 代理失败

要使用 Systems Manager Run Command 安装 CloudWatch 代理,目标服务器上的 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 版本的信息,请参阅 Amazon 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 代理以确定它是正在运行还是已停止。可使用 Amazon Systems Manager 远程执行此操作。也可以使用命令行,但仅用于检查本地服务器。

使用 Run Command 查询 CloudWatch 代理的状态
  1. 通过 https://console.aws.amazon.com/systems-manager/ 打开 Systems Manager 控制台。

  2. 在导航窗格中,选择 Run Command

    –或者–

    如果打开了 Amazon Systems Manager 主页,请向下滚动并选择 Explore Run Command(浏览 Run Command)

  3. 选择 Run command(运行命令)

  4. Command document (命令文档) 列表中,选择 AmazonCloudWatch-ManageAgent 旁边的按钮。

  5. 操作列表中,选择状态

  6. 对于 Optional Configuration Source (可选的配置源),选择 default (默认值) 并将 Optional Configuration Location (可选的配置位置) 保留为空。

  7. 目标区域,选择要检查的实例。

  8. 选择运行

如果该代理正在运行,输出将类似于以下内容。

{ "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 代理已运行,但在 Amazon Web Services Management Console 或 Amazon 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 位置

控制代理的启动、停止和重新启动的控制脚本。

/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

代理写入的日志文件。联系 Amazon Web Services Support 时,您可能需要附上此信息。

/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 代理配置文件

/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 代理生成的日志

该代理在运行时生成一个日志。该日志包含故障排除信息。该日志是 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 代理

您可以使用 Amazon Systems Manager 或命令行手动停止 CloudWatch 代理。

使用 Run Command 停止 CloudWatch 代理
  1. 通过 https://console.aws.amazon.com/systems-manager/ 打开 Systems Manager 控制台。

  2. 在导航窗格中,选择 Run Command

    –或者–

    如果打开了 Amazon Systems Manager 主页,请向下滚动并选择 Explore Run Command(浏览 Run Command)

  3. 选择 Run command(运行命令)

  4. 命令文档列表中,选择 AmazonCloudWatch-ManageAgent

  5. Targets(目标)区域中,选择安装了 CloudWatch 代理的实例。

  6. 操作列表中,选择停止

  7. Optional Configuration Source (可选的配置源)Optional Configuration Location (可选的配置位置) 保留空白。

  8. 选择运行

使用命令行在本地停止 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 代理中的说明进行操作。