本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 針對 CloudWatch 代理程式進行疑難排解
您可以使用本節中的資訊，對 CloudWatch 代理程式可能遇到的問題進行疑難排解。
當 CloudWatch 代理程式發生問題時，可以使用 `AWSSupport-TroubleshootCloudWatchAgent` Automation 執行手冊。 AWS 疑難排解工具可以：
+ 驗證 IAM 許可和執行個體設定檔
+ 檢查代理狀態並分析日誌
+ 測試端點連線
+ 自動收集相關日誌並上傳至 Amazon S3
如需 AWS 故障診斷工具的詳細資訊，請參閱[支援自動化工作流程 (SAW) Runbook - 故障診斷 CloudWatch 代理程式](https://repost.aws/articles/ARDFhNRgSMRcahrIbGJaIC4g/support-automation-workflow-saw-runbook-troubleshoot-amazon-cloudwatch-agent)。
**Topics**
+ [CloudWatch 代理程式命令列參數](#CloudWatch-Agent-options-help)
+ [使用執行命令安裝 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)
+ [CloudWatch 代理程式無法在 Windows Server 上啟動](#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
```
## 使用執行命令安裝 CloudWatch 代理程式失敗
若要使用 Systems Manager 執行命令安裝 CloudWatch 代理程式，目標伺服器上的 SSM 代理程式必須為 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 從遠端執行此操作。您也可以使用命令列，但只會檢查本機伺服器。
**若要查詢執行命令啟動 CloudWatch 代理程式的狀態**
1. 在 https：//[https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/) 開啟 Systems Manager 主控台。
1. 在導覽窗格中，選擇 **執行命令**。
-或-
如果 AWS Systems Manager 首頁開啟，請向下捲動並選擇**探索執行命令**。
1. 選擇**執行命令**。
1. 在 **Command document (命令文件)** 清單中，選擇 **AmazonCloudWatch-ManageAgent** 旁的按鈕。
1. 在 **Action (動作)** 清單中，選擇 **status (狀態)**。
1. 針對 **Optional Configuration Source (選用組態來源)**，選擇 **default (預設)** 並將 **Optional Configuration Location (選用組態位置)** 維持空白。
1. 在 **Target (目標)** 區域，選擇要檢查的執行個體。
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)。
## CloudWatch 代理程式無法在 Windows Server 上啟動
若使用的是 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 秒的時間進行啟動，因此這會導致代理程式失敗，並出現類似以下的錯誤：
若要修正此問題，請增加服務逾時值。如需詳細資訊，請參閱[服務未啟動，且事件 7000 和 7011 已記錄在 Windows 事件記錄檔中](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 檔案。 | `/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 到 TOML 的轉換是否成功非常有用。 | `/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 代理程式版本的正確方法。如果您使用控制面板中的**程式和功能**，您會看到不正確的版本編號。
您也可以下載有關代理程式最新變更的 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)。
在 CloudWatch 代理程式 1.247350.0 版及更新版本中，您可以選擇將代理程式組態檔案 `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 代理程式。
**若要使用執行命令停止 CloudWatch 代理程式**
1. 在 https：//[https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/) 開啟 Systems Manager 主控台。
1. 在導覽窗格中，選擇 **執行命令**。
-或-
如果 AWS Systems Manager 首頁開啟，請向下捲動並選擇**探索執行命令**。
1. 選擇**執行命令**。
1. 在 **Command document (命令文件)** 清單中選擇 **AmazonCloudWatch-ManageAgent**。
1. 在 **Targets** (目標) 區域中，選擇您安裝 CloudWatch 代理程式的執行個體。
1. 在 **Action (動作)** 清單中，選擇 **stop (停止)**。
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) 中的說明操作。