Google Cloud Monitoring 데이터 소스 문제 해결

이 문서는 Google Cloud Monitoring 데이터 소스를 구성하거나 사용할 때 겪을 수 있는 일반적인 문제와 해결책을 다뤄요. 구성 지침은 Google Cloud Monitoring 구성을 참고하세요. 인증, 연결, 지표 쿼리, SLO, 템플릿 변수, 대시보드 순서로 문제를 진단해 보세요.

출처: Troubleshoot Google Cloud Monitoring data source issues

본문

인증 오류

이 오류는 GCP 자격 증명이 유효하지 않거나, 없거나, 필요한 권한이 없을 때 발생해요.

"Permission denied" 또는 "Access denied"

증상:

Save & test가 권한 오류로 실패
쿼리가 권한 부여 오류를 반환
프로젝트, 지표, 라벨이 로드되지 않음

가능한 원인과 해결책:

원인	해결책
서비스 계정에 필요한 권한 없음	GCP Console의 IAM & Admin > IAM에서 서비스 계정에 Monitoring Viewer 역할을 할당해요. 자세한 내용은 구성 문서 참고.
잘못된 서비스 계정 키 파일	JSON 키 파일이 올바르게 다운로드됐고 유효한 자격 증명을 담고 있는지 확인해요. 필요하면 새 키를 생성해요.
서비스 계정 키가 삭제됨	GCP Console의 IAM & Admin > Service Accounts에서 서비스 계정을 확인해요. 키가 삭제됐으면 새로 만들어요.
잘못된 프로젝트 선택	데이터 소스 구성의 기본 프로젝트가 서비스 계정이 접근할 수 있는 프로젝트와 일치하는지 확인해요.
API가 활성화되지 않음	GCP Console에서 Monitoring API와 Cloud Resource Manager API를 활성화해요.

"Invalid JWT" 또는 "JWT token error"

증상:

Google JWT File 사용 시 인증 실패
오류 메시지가 유효하지 않거나 형식이 잘못된 JWT를 참조

해결책:

개인 키 부분만이 아니라 완전한 JSON 키 파일을 업로드했는지 확인해요.
JSON 파일이 올바르게 형식화되어 있고 손상되지 않았는지 확인해요.
키 파일에 type, project_id, private_key_id, private_key, client_email, client_id, auth_uri, token_uri 필드가 모두 있는지 확인해요.
새 서비스 계정 키를 생성해 다시 업로드해요.

GCE Default Service Account가 작동하지 않음

증상:

GCE Default Service Account 사용 시 데이터 소스 테스트 실패
JWT로는 되지만 GCE 인증으로는 실패

해결책:

Grafana가 Google Compute Engine(GCE) 가상 머신에서 실행 중인지 확인해요.
GCE 인스턴스에 Cloud Monitoring API 스코프가 활성화되어 있는지 확인해요.
GCE 기본 서비스 계정에 Monitoring Viewer 역할이 있는지 확인해요.
VM이 필요한 스코프 없이 생성됐다면 인스턴스를 중지하고 스코프를 추가해 편집한 뒤 다시 시작해야 할 수 있어요.

서비스 계정 가장(impersonation) 오류

증상:

서비스 계정 가장이 활성화되면 인증 실패
"Unable to impersonate service account" 오류

해결책:

기본 서비스 계정이 대상 서비스 계정에 roles/iam.serviceAccountTokenCreator 역할을 갖고 있는지 확인해요.
대상 서비스 계정 이메일이 올바르게 입력됐는지 확인해요.
대상 서비스 계정에 Monitoring Viewer 역할이 있는지 확인해요.
두 서비스 계정이 필요한 API가 활성화된 프로젝트에 있는지 확인해요.

Forward OAuth Identity가 403 반환

증상:

Forward OAuth Identity 사용 시 Save & Test가 403 Forbidden으로 실패
일부 사용자에게는 쿼리가 성공하고 다른 사용자에게는 실패

해결책:

Grafana에 Google로 로그인했는지, 로컬 admin 사용자가 아닌지 확인해요. Forward OAuth Identity 방식은 현재 세션에 토큰이 있을 때만 토큰을 전달해요.
Grafana Google 인증에 https://www.googleapis.com/auth/monitoring.read 스코프가 포함됐는지 확인해요 (Google OAuth 스코프 구성).
스코프를 추가한 뒤 Grafana에서 로그아웃하고 https://myaccount.google.com/permissions에서 기존 승인을 해지한 다음 다시 로그인해요. Google은 이전 동의를 재사용하므로 승인을 해지하기 전까지는 새 스코프로 토큰을 재발급하지 않아요.
로그인한 사용자가 Default project에 설정된 프로젝트에서 Monitoring Viewer 역할(roles/monitoring.viewer)을 갖고 있는지 확인해요.
Default project 필드가 채워졌는지 확인해요. 사용자의 OAuth 토큰은 프로젝트 컨텍스트를 담지 않으므로 데이터 소스가 자격 증명에서 프로젝트로 폴백할 수 없어요.

연결 오류

이 오류는 Grafana가 Google Cloud Monitoring 엔드포인트에 도달하지 못할 때 발생해요.

"Request timed out" 또는 연결 실패

증상:

데이터 소스 테스트 타임아웃
쿼리가 타임아웃 오류로 실패
간헐적 연결 문제

해결책:

Grafana 서버에서 Google Cloud 엔드포인트(monitoring.googleapis.com)로의 네트워크 연결을 확인해요.
방화벽 규칙이 Google Cloud 서비스로의 아웃바운드 HTTPS(포트 443)를 허용하는지 확인해요.
Grafana Cloud가 프라이빗 리소스에 연결하는 경우 Private data source connect를 구성해요.
회사 프록시가 Google Cloud 연결을 차단하는지 확인해요.

"SSL certificate problem"

증상:

SSL/TLS 핸드셰이크 오류
인증서 검증 실패

해결책:

Grafana 서버의 시스템 시간이 올바른지 확인해요.
Grafana 서버에 최신 CA 인증서가 설치되어 있는지 확인해요.
회사 프록시가 HTTPS 트래픽을 가로채는지 확인해요.

지표 쿼리 오류

이 오류는 Google Cloud Monitoring 지표를 질의할 때 발생해요.

"No data" 또는 빈 결과

증상:

쿼리가 오류 없이 실행되지만 데이터를 반환하지 않음
차트에 "No data" 메시지 표시

가능한 원인과 해결책:

원인	해결책
시간 범위에 데이터가 없음	대시보드 시간 범위를 넓혀요. GCP 지표는 지표 유형에 따라 보존 기간이 달라요.
잘못된 프로젝트 선택	쿼리 편집기에서 올바른 프로젝트를 선택했는지 확인해요.
잘못된 지표 유형	서비스, 지표 유형, 지표가 올바른지 확인해요. GCP Console Metrics Explorer에서 사용 가능한 지표를 확인하세요.
라벨/필터 누락	일부 지표는 데이터를 반환하려면 특정 라벨 필터가 필요해요. 필터를 제거해 데이터가 나타나는지 시도해 보세요.
리소스가 지표를 방출하지 않음	리소스가 존재하고 활발히 지표를 방출하는지 확인해요. 일부 지표는 특정 조건에서만 채워져요.

지표가 드롭다운에 나타나지 않음

증상:

예상 지표가 쿼리 편집기에 나타나지 않음
서비스에 대한 지표 드롭다운이 비어 있음

해결책:

지표가 선택한 프로젝트와 리전에 존재하는지 확인해요.
서비스 계정에 Monitoring Viewer 역할이 있는지 확인해요.
일부 지표는 특정 리소스 유형에서만 사용할 수 있어요. Google Cloud metrics list를 확인하세요.
Query Inspector로 API 요청과 응답을 확인해요.

라벨 값이 로드되지 않음

증상:

라벨 값 드롭다운이 채워지지 않음
필터를 적용할 수 없음

해결책:

서비스 계정에 Monitoring Viewer 역할이 있는지 확인해요.
라벨 값이 로드되기 전에 프로젝트, 서비스, 지표가 선택되어 있는지 확인해요.
라벨 값은 기존 지표 데이터에서 채워져요. 현재 선택과 일치하는 지표가 없으면 값이 나타나지 않아요.

MQL 쿼리 오류

증상:

Monitoring Query Language(MQL) 쿼리가 문법 오류로 실패
MQL 쿼리가 예상치 못한 결과를 반환

해결책:

MQL 레퍼런스 문서로 MQL 문법을 검증해요.
지표 유형, 라벨 이름, 함수 이름에 오타가 없는지 확인해요.
쿼리의 시간 범위 문법이 유효한지 확인해요.
Grafana에서 사용하기 전에 GCP Console Metrics Explorer에서 쿼리를 테스트해요.

"Too many data points" 또는 API 스로틀링

증상:

쿼리가 할당량 오류로 실패
여러 패널에서 성능 저하

해결책:

정렬 기간을 늘려 데이터 포인트 수를 줄여요.
쿼리의 시간 범위를 줄여요.
패널당 지표 쿼리를 더 적게 사용해요.
GCP Console의 APIs & Services > Quotas에서 할당량 증가를 요청해요.
Grafana에서 쿼리 캐싱을 활성화해 API 호출을 줄여요.

SLO 쿼리 오류

이 오류는 Service Level Objective(SLO) 쿼리에 특화된 문제예요.

SLO 서비스가 나타나지 않음

증상:

SLO 서비스 선택기가 비어 있음
예상 SLO 서비스를 찾을 수 없음

해결책:

선택한 프로젝트의 Google Cloud Monitoring에 SLO가 정의되어 있는지 확인해요.
서비스 계정에 SLO를 볼 수 있는 권한이 있는지 확인해요.
GCP Console의 Service Monitoring 섹션에 프로젝트의 서비스가 구성되어 있는지 확인해요.

SLO 쿼리가 데이터를 반환하지 않음

증상:

SLO 쿼리가 실행되지만 데이터가 반환되지 않음
SLO 값이 비어 있음

해결책:

GCP Console에서 SLO가 존재하고 활성 상태인지 확인해요.
시간 범위에 SLO에 데이터가 있던 기간이 포함되는지 확인해요.
선택한 SLO 셀렉터(SLI value, compliance, error budget 등)가 SLO 유형에 적합한지 확인해요.
기본 서비스가 트래픽을 받지 않았다면 일부 SLO에는 데이터가 없을 수 있어요.

템플릿 변수 오류

이 오류는 Google Cloud Monitoring 데이터 소스에서 템플릿 변수를 사용할 때 발생해요.

변수가 값을 반환하지 않음

증상:

변수 드롭다운이 비어 있음
변수 오류로 대시보드 로드 실패

해결책:

데이터 소스 연결이 작동하는지 확인해요.
서비스 계정에 요청한 리소스를 나열할 권한이 있는지 확인해요.
종속 변수의 경우 부모 변수의 선택이 유효한지 확인해요.
변수 쿼리에서 프로젝트가 올바르게 선택됐는지 확인해요.

변수 로드가 느림

증상:

대시보드 로드에 오랜 시간이 걸림
변수 선택기 채우기가 느림

해결책:

변수 새로고침을 On time range change 대신 On dashboard load로 설정해요.
변수 쿼리 범위를 줄여요(특정 프로젝트나 서비스로 필터).
체인에 있는 종속 변수의 수를 제한해요.

템플릿 변수에 대한 자세한 내용은 템플릿 변수 문서를 참고하세요.

대시보드 문제

이 문제는 Google Cloud Monitoring 데이터 소스를 사용하는 대시보드에서 발생해요. 플러그인 버전 12.6.1부터 플러그인은 큐레이션된 대시보드를 더 이상 번들하지 않으므로 데이터 소스 Dashboards 탭에 이들이 나열되지 않아요. 대시보드를 만들려면 Grafana dashboards catalog의 커뮤니티 및 Grafana 작성 대시보드를 사용하거나 쿼리 편집기로 패널을 다시 만드세요.

가져온 대시보드에 데이터가 표시되지 않음

증상:

가져온 대시보드에 빈 패널이 표시됨
템플릿 변수가 로드되지 않음

해결책:

대시보드의 데이터 소스 이름이 Google Cloud Monitoring 데이터 소스와 일치하는지 확인해요.
서비스 계정이 프로젝트 변수에 표시된 프로젝트에 접근할 수 있는지 확인해요.
리소스(Compute Engine 인스턴스, Cloud SQL 등)가 존재하고 지표를 방출하는지 확인해요.
프로젝트에서 필요한 GCP 서비스가 활성화되어 있는지 확인해요.

디버그 로깅 활성화

문제 해결을 위한 상세 오류 정보를 캡처하려면:

구성 파일에서 Grafana 로그 레벨을 debug로 설정해요:

[log]
level = debug

/var/log/grafana/grafana.log(또는 설정한 로그 위치)에서 로그를 검토해요.
요청과 응답 세부 정보를 포함한 Google Cloud Monitoring 특정 항목을 찾아요.
문제 해결 후 과도한 로그 양을 피하려면 로그 레벨을 info로 재설정해요.

추가 도움말

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

Grafana 커뮤니티 포럼에서 유사한 이슈를 확인해요.
GitHub의 Google Cloud Monitoring 이슈에서 알려진 버그를 검토해요.
Google Cloud Monitoring 문서에서 서비스별 지침을 참고해요.
Enterprise, Cloud Pro, Cloud Contracted 사용자라면 Grafana Support에 문의해요.
이슈를 보고할 때는 다음을 포함해요:
- Grafana 버전
- GCP 프로젝트(민감하면 편집)
- 오류 메시지(민감 정보 편집)
- 재현 단계
- 쿼리 구성(자격 증명 편집)

더 알아보기 (Learn more)

Configure Google Cloud Monitoring - 데이터 소스 구성
Google Cloud Monitoring query editor - 쿼리 편집기
Google Cloud Monitoring alerting - 알림 구성
Google Cloud monitoring docs - GCP 공식 문서
Troubleshoot Google Cloud Monitoring data source issues - 원문 문서