Amazon CloudWatch 데이터 소스 트러블슈팅

Amazon CloudWatch 데이터 소스 트러블슈팅

Amazon CloudWatch 데이터 소스를 구성하거나 사용할 때 겪을 수 있는 흔한 문제에 대한 해결책을 정리한 문서예요. 인증 오류, 연결 오류, 메트릭/로그 쿼리 오류, 템플릿 변수, 교차 계정 관측성, 할당량·비용 문제를 다룹니다.

출처: Troubleshoot Amazon CloudWatch data source issues

본문

구성 지침은 CloudWatch 구성 문서를 참고하세요.

참고: 데이터 소스 상태 점검은 메트릭과 로그 권한을 모두 검증해요. IAM 정책이 둘 중 하나(메트릭 전용 또는 로그 전용)에만 접근을 부여하면 상태 점검은 빨간색으로 표시돼요. 그러나 권한이 있는 서비스는 여전히 사용할 수 있어요 — 구성된 권한에 따라 메트릭 또는 로그를 쿼리할 수 있어요.

인증 오류 (Authentication errors)

이 오류들은 AWS 자격 증명이 유효하지 않거나, 누락되었거나, 필요한 권한이 없을 때 발생해요. 다음 표로 오류 메시지를 가장 가능성 높은 원인과 해결 섹션에 매칭해 보세요.

오류 메시지 가능한 원인 참고
AccessDenied: User is not authorized to perform: cloudwatch:... IAM 정책에 필요한 CloudWatch 권한이 없음 Access Denied 또는 Not authorized to perform this operation
InvalidClientTokenId 또는 UnrecognizedClientException: The security token included in the request is invalid 자격 증명이 유효하지 않거나, 비활성화되었거나, 회전되었거나, 일시적인 Grafana Cloud 인시던트가 진행 중 InvalidClientTokenId 또는 UnrecognizedClientException
AccessDenied: ... not authorized to perform: sts:AssumeRole 역할 신뢰 관계, 역할 ARN 또는 외부 ID가 잘못됨 Unable to assume role
AccessDenied: ... no VPC endpoint policy allows the cloudwatch:ListMetrics action VPC 엔드포인트 정책 또는 서비스 제어 정책(SCP)이 작업을 차단 Access blocked by a VPC endpoint policy or service control policy

"Access Denied" 또는 "Not authorized to perform this operation":

증상: Save & test가 "Access Denied"로 실패, 쿼리가 인증 오류 반환, 네임스페이스·메트릭·차원이 로드되지 않음.

원인 해결
IAM 정책에 필수 권한 누락 사용자/역할에 적절한 IAM 정책을 부착. 메트릭에는 cloudwatch:ListMetrics, cloudwatch:GetMetricData 등이, 로그에는 logs:DescribeLogGroups, logs:StartQuery, logs:GetQueryResults 등이 필요. 전체 정책 예시는 CloudWatch 구성 문서 참고.
잘못된 액세스 키/시크릿 키 AWS Console > IAM > Users > 사용자 > Security credentials에서 자격 증명 확인. 필요 시 새 자격 증명 생성.
자격 증명 만료 임시 자격 증명은 새로 생성. 액세스 키는 비활성화·삭제되지 않았는지 확인.
잘못된 AWS 리전 데이터 소스 구성의 기본 리전이 리소스 위치와 일치하는지 확인.
IAM 역할이 쿼리 지역에 권한 없음 AWS는 지역별로 권한을 평가. 역할이 일부 지역에서만 CloudWatch 접근이 있으면 다른 지역 쿼리는 AccessDenied를 반환하며 오류가 지역을 명명하지 않을 수 있음. 데이터 소스 Default Region을 역할에 권한이 있는 지역으로 설정하고 IAM 정책이 허용하는 지역만 쿼리.
Assume Role ARN이 잘못됨 역할 ARN 형식(arn:aws:iam::<account-id>:role/<role-name>) 검증. AWS Console에서 역할이 존재하는지 확인.

"InvalidClientTokenId" 또는 "UnrecognizedClientException":

증상: Save & test 실패, 쿼리 실패, 구성 변경 없이 갑자기 오류 발생.

원인 해결
액세스 키/시크릿 키가 유효하지 않거나 오타 AWS Console에서 자격 증명 확인. 데이터 소스 구성에 다시 입력.
자격 증명 비활성화·삭제·회전 AWS에서 새 자격 증명 생성 후 데이터 소스 구성 업데이트.
임시 자격 증명 만료 새 임시 자격 증명 생성, 또는 Assume Role 같은 장기 인증 방법으로 전환.
일시적 Grafana Cloud 인시던트 자격 증명이 변경되지 않았는데 여러 데이터 소스가 동시에 InvalidClientTokenId로 실패하면, 자격 증명 회전 전에 Grafana Cloud 상태 페이지에서 진행 중인 인시던트 확인.

"Unable to assume role":

증상: Assume Role ARN 사용 시 인증 실패, 오류가 STS 또는 AssumeRole을 참조.

  • IAM 역할의 신뢰 관계가 Grafana 자격 증명이 이를 assume하도록 허용하는지 확인.
  • 신뢰 정책에 올바른 프린시펄(Grafana를 실행하는 사용자/역할)이 포함되어 있는지 확인.
  • Grafana Assume Role 인증 방법을 사용한다면, 신뢰 정책이 데이터 소스 Settings 탭의 지침 상자에 표시된 정확한 Grafana AWS 계정 ID와 외부 ID를 사용하는지 확인. 다른 계정 ID 입력은 assume-role 요청 실패의 흔한 원인.
  • 외부 ID를 사용한다면 역할 신뢰 정책과 Grafana 데이터 소스 구성 양쪽에서 정확히 일치하는지 확인.
  • 기본 자격 증명이 sts:AssumeRole 권한을 가지는지 확인.
  • 역할 ARN이 정확하고 역할이 존재하는지 확인.
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::<account-id>:user/<user>"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "<external-id>"
        }
      }
    }
  ]
}

"Save & test"는 통과하지만 쿼리가 데이터를 반환하지 않음:

증상: Save & test 성공하지만 패널과 쿼리 편집기가 데이터를 반환하지 않음. Assume Role ARN 사용 시에만 발생.

원인 해결
연결 테스트가 assume-role 단계만 검증 Assume Role ARN을 구성하면 Save & test는 기본 자격 증명이 sts:AssumeRole을 수행할 수 있는지만 확인. assume된 역할이 CloudWatch/Logs 권한을 가지는지는 확인하지 않음. 기본 자격 증명뿐 아니라 assume된 역할에 필요한 쿼리 권한을 부착.
assume된 역할에 CloudWatch 권한 없음 assume된 역할의 정책에 메트릭·로그 작업(cloudwatch:ListMetrics, cloudwatch:GetMetricData, logs:DescribeLogGroups, logs:StartQuery 등) 추가.
권한이 잘못된 ID에 부착 정책이 IAM 사용자/역할이 아닌 Assume Role ARN에 명명된 역할에 부착되었는지 확인.

약 1시간 후 데이터 소스가 작동 중지:

증상: 데이터 소스가 처음엔 작동하다가 대략 1시간 후 쿼리 실패. 오류가 만료/유효하지 않은 보안 토큰 참조. 데이터 소스를 다시 저장하거나 Grafana를 재시작하면 일시적으로 복구 후 다시 실패.

원인 해결
임시 자격 증명 만료 및 갱신 안 됨 Assume Role이나 STS 같은 임시 자격 증명 방법은 단기 토큰을 발급. 데이터 소스가 정적 임시 자격 증명을 사용한다면 자동 갱신되는 인증 방법(장기 기본 자격 증명을 가진 Assume Role 또는 EKS/EC2 인스턴스 역할)으로 전환. AWS 인증 문서 참고.

VPC 엔드포인트 정책 또는 서비스 제어 정책이 접근 차단:

증상: 자격 증명이 유효하고 IAM 정책이 작업을 허용하지만 요청이 여전히 AccessDenied로 실패. 오류가 VPC 엔드포인트 정책을 참조. VPC 내 또는 FedRAMP 환경 같은 제한된 계정에서만 접근 실패.

원인 해결
VPC 엔드포인트 정책이 허용 작업 제한 CloudWatch, Logs, EC2, STS VPC 엔드포인트의 정책을 업데이트해 cloudwatch:ListMetrics, cloudwatch:GetMetricData 같은 작업 허용.
SCP가 필수 작업을 명시적으로 거부 계정/OU에 적용된 서비스 제어 정책 검토. SCP의 명시적 Deny는 IAM 정책의 Allow를 재정의하므로 두 수준 모두에서 작업이 허용되어야 함.
요청이 잘못된 엔드포인트로 라우팅 데이터 소스 리전과 커스텀 엔드포인트가 필수 작업을 허용하는 VPC 엔드포인트와 일치하는지 확인.

AWS SDK Default 인증이 작동하지 않음:

증상: AWS SDK Default 사용 시 데이터 소스 테스트 실패. 로컬에서는 작동하지만 프로덕션에서 실패.

  • Grafana가 실행되는 환경에 AWS 자격 증명이 구성되어 있는지 확인.
  • 기본 위치에서 자격 증명 확인: 환경 변수(AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY), 공유 자격 증명 파일(~/.aws/credentials), EC2 인스턴스 메타데이터(EC2에서 실행 시), ECS 태스크 역할(ECS에서), EKS 서비스 계정(EKS에서).
  • Grafana 프로세스가 자격 증명 파일을 읽을 권한이 있는지 확인.
  • IRSA가 있는 EKS의 경우 팟의 보안 컨텍스트를 설정해 사용자 472(grafana)가 프로젝트된 토큰에 접근하도록 허용. AWS 인증 문서 참고.

자격 증명 파일을 찾을 수 없음:

증상: 오류가 자격 증명 파일을 읽을 수 없다고 표시. "Credentials file" 옵션으로 인증 실패.

  • grafana-server 서비스를 실행하는 사용자에 대해 ~/.aws/credentials에 자격 증명 파일 생성.
  • 파일이 올바른 권한(0644)을 가지는지 확인.
  • 파일이 존재하지만 작동하지 않으면 /usr/share/grafana/로 이동하고 권한을 0644로 설정.
  • 데이터 소스 구성의 프로필 이름이 자격 증명 파일의 프로필과 일치하는지 확인.

연결 오류 (Connection errors)

Grafana가 AWS CloudWatch 엔드포인트에 도달할 수 없을 때 발생해요.

"Request timed out" 또는 연결 실패:

증상: 데이터 소스 테스트 시간 초과, 쿼리 시간 초과 오류, 간헐적 연결 문제.

  • Grafana 서버에서 AWS 엔드포인트로의 네트워크 연결 확인.
  • 방화벽 규칙이 AWS 서비스로의 아웃바운드 HTTPS(443 포트)를 허용하는지 확인.
  • VPC를 사용한다면 NAT 게이트웨이 또는 VPC 엔드포인트 구성이 올바른지 확인.
  • Grafana Cloud가 프라이빗 리소스에 연결한다면 Private data source connect 구성.
  • 기본 리전이 올바른지 확인 — 잘못된 리전은 더 긴 시간 초과를 유발할 수 있음.
  • 큰 데이터 볼륨을 포함하는 쿼리라면 시간 초과 설정 증가.

커스텀 엔드포인트 구성 문제:

증상: 커스텀 엔드포인트 사용 시 연결 실패, 엔드포인트 URL 거부.

  • 엔드포인트 URL 형식이 올바른지 확인.
  • 엔드포인트가 Grafana 서버에서 접근 가능한지 확인.
  • 엔드포인트가 필요한 AWS API를 지원하는지 확인.
  • VPC 엔드포인트라면 정책이 필요한 작업을 허용하는지 확인.

CloudWatch Metrics 쿼리 오류

"No data" 또는 빈 결과:

증상: 쿼리가 오류 없이 실행되지만 데이터 반환 없음. 차트가 "No data" 표시.

원인 해결
시간 범위에 데이터 없음 대시보드 시간 범위 확장. CloudWatch 메트릭은 해상도에 따라 보존 기간이 다름.
잘못된 네임스페이스/메트릭 이름 네임스페이스(예: AWS/EC2)와 메트릭 이름(예: CPUUtilization)이 올바른지 확인.
잘못된 차원 차원 이름과 값이 AWS 리소스와 정확히 일치하는지 확인.
Match Exact가 잘못 활성화 Match Exact가 활성화되면 모든 차원을 지정해야 함. 비활성화 시도.
Period가 너무 큼 Period를 줄이거나 "auto"로 설정해 시간 범위에 데이터 포인트가 반환되도록.
커스텀 메트릭 미구성 데이터 소스 구성의 Namespaces of Custom Metrics에 커스텀 메트릭 네임스페이스 추가.

"Metric not found" 또는 메트릭이 드롭다운에 안 나타남:

증상: 예상 메트릭이 쿼리 편집기에 나타나지 않음. 네임스페이스의 메트릭 드롭다운이 비어 있음. CloudWatch 콘솔에 존재하는데 드롭다운에서 특정 메트릭 누락.

  • 메트릭이 선택된 리전에 존재하는지 확인.
  • 커스텀 메트릭은 데이터 소스 구성의 Namespaces of Custom Metrics에 네임스페이스 추가.
  • IAM 정책에 cloudwatch:ListMetrics 권한이 포함되어 있는지 확인.
  • CloudWatch는 ListMetrics를 페이지당 500개 결과로 제한. 더 많은 메트릭을 검색하려면 Grafana 구성 파일의 list_metrics_page_limit 설정을 증가.
  • Metric name 필드에 메트릭 이름을 직접 입력. 일부 AWS 네임스페이스는 데이터 소스가 사전 정의 메트릭 목록을 사용하므로, 새로 등장했거나 덜 흔한 메트릭은 쿼리할 수 있어도 드롭다운에 안 나타날 수 있음. CloudWatch 콘솔에 존재하면 정확한 이름을 입력해 쿼리.
  • Query Inspector로 API 요청·응답 확인.

차원 값이 로드되지 않음:

증상: 차원 값 드롭다운이 채워지지 않음. 와일드카드 검색 결과 없음.

  • IAM 정책에 cloudwatch:ListMetrics 권한 포함 확인.
  • 차원 값 로드 전에 네임스페이스와 메트릭이 선택되었는지 확인.
  • EC2 차원은 ec2:DescribeTagsec2:DescribeInstances 권한 필요.
  • 차원 값은 기존 메트릭을 요구 — 일치하는 메트릭이 없으면 값도 없음.

"Too many data points" 또는 API 제한(throttling):

증상: 쿼리가 스로틀링 오류로 실패. 여러 패널로 성능 저하.

  • Period를 늘려 데이터 포인트 수 감소.
  • 쿼리 시간 범위 축소.
  • 패널당 차원이나 와일드카드 쿼리 수 줄임.
  • AWS Service Quotas 콘솔에서 초당 GetMetricData 요청 할당량 증가 요청.
  • Grafana에서 쿼리 캐시 활성화로 API 호출 감소.
  • 이 섹션은 쿼리 수준 스로틀링을 다룸. 계정 전체의 요율 제한과 할당량 증가는 API 스로틀링 오류 참고.

메트릭 수학 표현식 오류:

증상: 표현식이 오류 반환. 참조 메트릭을 찾을 수 없음.

  • 각 참조 메트릭에 고유한 ID가 설정되었는지 확인.
  • 메트릭 ID가 소문자로 시작하고 문자·숫자·밑줄만 포함하는지 확인.
  • 모든 참조 메트릭이 같은 쿼리에 있는지 확인.
  • 표현식 문법이 AWS Metric Math 문서를 따르는지 확인.
  • 메트릭 수학 표현식은 다른 쿼리 행을 참조하면 Grafana 알림과 함께 사용할 수 없음.

CloudWatch Logs 쿼리 오류

"Query failed" 또는 로그가 안 나타남:

증상: 로그 쿼리가 오류 반환. 로그 데이터 표시 안 됨.

  • 로그 그룹 이름이 올바르고 선택된 리전에 존재하는지 확인.
  • IAM 정책에 logs:StartQuery, logs:GetQueryResults, logs:DescribeLogGroups 권한 포함 확인.
  • 시간 범위에 로그 데이터가 있는지 확인.
  • 쿼리 문법이 유효한지 확인. CloudWatch Logs Insights QL은 AWS 콘솔에서 테스트.
  • 쿼리 문법에 따라 올바른 쿼리 언어(Logs Insights QL, OpenSearch PPL, OpenSearch SQL) 선택.

로그 쿼리 시간 초과:

증상: 쿼리가 오래 실행 후 실패. 오류가 시간 초과 언급.

  • 데이터 소스 구성의 Query Result Timeout 설정 증가(기본 30분).
  • 시간 범위를 좁혀 스캔되는 데이터량 감소.
  • 쿼리에 필터 추가로 결과 제한.
  • 복잡한 쿼리를 더 작고 집중된 쿼리로 분할.
  • 알림의 경우 Grafana 구성 파일에 정의된 시간 초과가 우선함.

로그 그룹이 선택기에 나타나지 않음:

증상: 로그 그룹 선택기가 비어 있음. 예상 로그 그룹을 찾을 수 없음.

  • IAM 정책에 logs:DescribeLogGroups 권한 포함 확인.
  • 선택된 리전에 로그 그룹이 존재하는지 확인.
  • 교차 계정 관측성은 oam:ListSinksoam:ListAttachedLinks에 대한 적절한 IAM 권한 확인.
  • 로그 그룹이 많다면 접두사 검색으로 필터링.
  • 교차 계정이라면 선택된 계정에 예상 로그 그룹이 있는지 확인.

OpenSearch SQL 쿼리 오류:

증상: OpenSearch SQL 쿼리 실패. SQL 쿼리 문법 오류.

  • FROM 절에 로그 그룹 식별자 또는 ARN 지정:
SELECT * FROM `log_group_name` WHERE `@message` LIKE '%error%'
  • 여러 로그 그룹에 대해 logGroups 함수 사용:
SELECT * FROM `logGroups(logGroupIdentifier: ['LogGroup1', 'LogGroup2'])`
  • Amazon CloudWatch는 OpenSearch SQL 명령의 일부만 지원. 지원 문법은 CloudWatch Logs 문서 참고.

템플릿 변수 오류

변수가 값을 반환하지 않음:

증상: 변수 드롭다운이 비어 있음. 대시보드가 변수 오류로 로드 실패.

  • 데이터 소스 연결이 작동하는지 확인.
  • IAM 정책이 변수 쿼리 유형에 대한 권한을 포함하는지 확인:
    • Regions: 추가 권한 불필요
    • Namespaces: 추가 권한 불필요
    • Metrics: cloudwatch:ListMetrics 필요
    • Dimension Values: cloudwatch:ListMetrics 필요
    • EC2 Instance Attributes: ec2:DescribeInstances 필요
    • EBS Volume IDs: ec2:DescribeVolumes 필요
    • Resource ARNs: tag:GetResources 필요
    • Log Groups: logs:DescribeLogGroups 필요
  • 의존 변수의 경우 부모 변수가 유효한 선택을 가지는지 확인.
  • 리전이 올바르게 설정되었는지 확인("default" 사용 시 데이터 소스 기본 리전).
  • 자세한 내용은 CloudWatch 템플릿 변수 문서 참고.

다중 값 템플릿 변수가 쿼리 실패 유발:

증상: 여러 차원 값을 선택할 때 쿼리 실패. 검색 표현식 제한 오류.

  • 검색 표현식은 1,024자로 제한. 선택 값 수 감소.
  • 차원의 모든 메트릭을 쿼리할 때 "All"을 선택하는 대신 별표(*) 와일드카드 사용.
  • 다중 값 템플릿 변수는 Region, Namespace, Metric Name이 아닌 차원 값에서만 지원.

교차 계정 관측성 오류

교차 계정 쿼리 실패:

증상: 연결된 계정의 메트릭/로그를 쿼리할 수 없음. 모니터링 계정 배지가 나타나지 않음.

  • AWS CloudWatch 콘솔에서 교차 계정 관측성이 구성되었는지 확인.
  • 필요한 IAM 권한 추가:
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Action": ["oam:ListSinks", "oam:ListAttachedLinks"],
      "Effect": "Allow",
      "Resource": "*"
    }
  ]
}
  • AWS에서 모니터링 계정과 소스 계정이 제대로 연결되었는지 확인.
  • 교차 계정 관측성은 단일 리전 내에서 작동 — 모든 계정이 같은 리전인지 확인.
  • EC2 Instance Attributes는 EC2 API를 사용하므로(CloudWatch API 아님) 계정 간에 쿼리할 수 없음.

할당량과 비용 문제

API 스로틀링 오류:

증상: "Rate exceeded" 오류. 대시보드 패널이 간헐적으로 로드 실패.

  • 대시보드 새로고침 빈도 줄임.
  • Period를 늘려 GetMetricData 요청 감소.
  • Grafana에서 쿼리 캐시 활성화(Enterprise/Cloud).
  • AWS Service Quotas 콘솔에서 할당량 증가 요청.
  • 메트릭 수학으로 유사한 쿼리 통합 고려.
  • 단일 쿼리가 너무 많은 데이터 포인트를 반환해 스로틀링이 발생하면 "Too many data points" 참고.

예상보다 높은 CloudWatch 비용:

증상: AWS CloudWatch 비용이 예상보다 높음. Grafana의 잦은 API 호출.

  • GetMetricData API는 CloudWatch API 무료 티어 자격이 없음.
  • 대시보드 자동 새로고침 빈도 줄임.
  • Period를 늘려 반환 데이터 포인트 감소.
  • 쿼리 캐시 사용으로 반복 API 호출 감소.
  • 변수 쿼리 설정 검토 — 변수 새로고침을 "On time range change" 대신 "On dashboard load"로 설정.
  • 가능하면 차원에서 와일드카드 사용 피하기 — 여러 API 호출이 있는 검색 표현식을 생성하므로.

기타 흔한 문제

커스텀 메트릭이 안 나타남:

증상: 애플리케이션/에이전트의 커스텀 메트릭이 네임스페이스 드롭다운에 안 보임. 표준 AWS 네임스페이스만 보임.

  • 데이터 소스 구성의 Namespaces of Custom Metrics 필드에 커스텀 메트릭 네임스페이스 추가.
  • 여러 네임스페이스는 콤마로 구분(예: CWAgent,CustomNamespace).
  • 선택된 리전에서 커스텀 메트릭이 CloudWatch에 게시되었는지 확인.

사전 구성 대시보드가 작동하지 않음:

증상: 가져온 대시보드가 데이터 표시 안 함. 대시보드 변수가 로드 안 됨.

  • 대시보드의 데이터 소스 이름이 CloudWatch 데이터 소스와 일치하는지 확인.
  • 대시보드의 AWS 리전 설정이 리소스 위치와 일치하는지 확인.
  • IAM 정책이 필요한 서비스(EC2, Lambda, RDS 등)에 접근을 부여하는지 확인.
  • 리소스가 존재하고 선택된 리전에서 메트릭을 방출하는지 확인.

Application Signals 트레이스 링크가 안 나타남:

증상: 로그 항목에 Application Signals 트레이스 링크가 안 보임. @xrayTraceId 필드가 안 나타남.

  • CloudWatch 데이터 소스 설정에서 Application Signals 데이터 소스가 구성·링크되었는지 확인.
  • 로그에 @xrayTraceId 필드가 포함되었는지 확인.
  • 로그 쿼리를 업데이트해 필드에 @xrayTraceId 포함, 예: fields @message, @xrayTraceId.
  • 애플리케이션이 Application Signals 트레이스 ID를 로깅하도록 구성. AWS Application Signals 문서 참고.

디버그 로깅 활성화 (Enable debug logging)

자세한 오류 정보를 잡으려면:

  • 구성 파일에서 Grafana 로그 레벨을 debug로 설정:
[log]
level = debug
  • /var/log/grafana/grafana.log(또는 구성된 로그 위치)에서 로그 검토.
  • 요청·응답 상세가 포함된 CloudWatch 특정 항목 확인.
  • 과도한 로그 볼륨을 피하려면 트러블슈팅 후 로그 레벨을 info로 재설정.

추가 도움 (Get additional help)

위 해결책을 시도해도 문제가 계속되면:

이슈 보고 시 포함할 것: Grafana 버전, AWS 리전, 오류 메시지(민감 정보는 redact), 재현 단계, 쿼리 구성(자격 증명·계정 ID는 redact).

더 알아보기 (Learn more)