# 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)
+ [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
```
## 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. 탐색 창에서 **명령 실행**을 선택합니다.
-또는-
AWS Systems Manager 홈페이지가 열리면 아래로 스크롤하여 [**Run Command 탐색(Explore Run Command)**]을 선택합니다.
1. **명령 실행**을 선택합니다.
1. **명령 문서** 목록에서 **AmazonCloudWatch-ManageAgent** 옆의 버튼을 선택합니다.
1. **작업** 목록에서 **상태**를 선택합니다.
1. **Optional Configuration Source(구성 소스(선택 사항))**에 대해 **기본값**을 선택하고 **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 엔드포인트에 액세스해야 하도록 에이전트를 구성했을 수 있습니다.
예를 들어 에이전트 구성 파일에서 Amazon EC2 메타데이터에 따라 달라지는 `append_dimensions` 파라미터의 값을 지정하고 프록시를 사용하는 경우 서버가 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초만 허용하므로 다음과 유사한 오류가 발생하며 에이전트가 시작되지 않습니다.
이 문제를 해결하려면 서비스 제한 시간 값을 늘려야 합니다. 자세한 내용은 [서비스가 시작되지 않으며 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 Management Console 또는 AWS CLI에서 에이전트가 수집한 지표를 찾을 수 없는 경우 올바른 네임스페이스를 사용하고 있는지 확인합니다. 기본적으로 에이전트에 의해 수집되는 지표의 네임스페이스는 `CWAgent`입니다. 에이전트 구성 파일의 `metrics` 섹션에 있는 `namespace` 필드를 사용하여 이 네임스페이스를 사용자 지정할 수 있습니다. 원하는 지표가 표시되지 않는 경우 구성 파일을 점검하여 사용 중인 네임스페이스를 확인하세요.
CloudWatch 에이전트 패키지를 처음 다운로드할 때 에이전트 구성 파일은 `amazon-cloudwatch-agent.json`입니다. 이 파일은 구성 마법사를 실행한 디렉터리에 있습니다. 그렇지 않으면 이 파일을 다른 디렉터리로 옮긴 것일 수 있습니다. 구성 마법사를 사용하는 경우, 마법사의 에이전트 구성 파일 출력이 `config.json`으로 명명됩니다. `namespace` 필드를 포함한 구성 파일에 대한 자세한 내용은 [CloudWatch 에이전트 구성 파일: 지표 섹션](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 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 에이전트 구성 파일 생성](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에서 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 에이전트 버전을 올바르게 찾을 수 있습니다. 이와 달리 제어판의 [**프로그램 및 기능(Programs 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. 탐색 창에서 **명령 실행**을 선택합니다.
-또는-
AWS Systems Manager 홈페이지가 열리면 아래로 스크롤하여 [**Run Command 탐색(Explore Run Command)**]을 선택합니다.
1. **명령 실행**을 선택합니다.
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) 섹션의 지침을 따르세요.