일반 데이터 소스 문제 해결
일반 데이터 소스 문제 해결 (Troubleshoot general data source issues)
이 페이지는 Grafana의 데이터 소스 전반에 걸쳐 나타나는 흔한 문제들의 해결책을 다뤄요. 특정 데이터 소스의 문제 해결이 필요하다면, 각 데이터 소스 설명서 안의 문제 해결 페이지를 참고하면 돼요. 연결 오류부터 인증·쿼리·프로비저닝 오류까지 원인별로 증상과 해법을 정리해드릴게요.
출처: 문서
본문
이 페이지는 Grafana의 데이터 소스 전반에 걸쳐 적용되는 흔한 문제들의 해결책을 제공해요. 특정 데이터 소스에 한정된 문제 해결은 해당 데이터 소스 설명서의 문제 해결 페이지를 참고해요.
연결 오류 (Connection errors)
이 오류들은 Grafana가 데이터 소스 백엔드에 도달하지 못할 때 발생해요.
"Connection refused" 또는 타임아웃 오류
증상 (Symptoms):
- Save & test가 연결 오류 또는 타임아웃으로 실패해요
- 패널에 "error"가 표시되거나 데이터 로드가 실패해요
- 간헐적인 연결 문제가 발생해요
가능한 원인과 해결책:
| 원인 | 해결책 |
|---|---|
| 잘못된 URL | 데이터 소스 URL이 올바른지 확인해요. 프로토콜(http:// 또는 https://)과 포트 번호를 포함해야 해요. |
| 네트워크 또는 방화벽 규칙 | Grafana 서버가 데이터 소스 엔드포인트에 도달할 수 있는지 확인해요. 방화벽 규칙이 필요한 포트의 아웃바운드 트래픽을 허용하는지 점검해요. |
| 데이터 소스 다운 | 데이터 소스 서비스가 실행 중이고 연결을 수락하고 있는지 확인해요. |
| DNS 해석 실패 | Grafana 서버에서 호스트네임이 올바르게 해석되는지 확인해요. |
| 사설 네트워크 접근 | 데이터 소스가 사설 네트워크에 있고 Grafana Cloud를 사용한다면 Private data source connect를 구성해요. |
TLS/SSL 오류
증상 (Symptoms):
- "certificate", "TLS handshake", "x509"를 언급하는 오류
- Save & test가 SSL 관련 메시지로 실패해요
해결책 (Solutions):
- 데이터 소스가 유효한 TLS 인증서를 사용하는지 확인해요.
- 자체 서명(self-signed) 인증서를 사용한다면 데이터 소스 구성에서 Skip TLS Verify를 활성화하거나(운영 환경에는 비권장), CA 인증서를 Grafana의 신뢰 인증서 목록에 추가해요.
- 인증서가 만료되지 않았는지 확인해요.
- 인증서의 Common Name 또는 Subject Alternative Name이 데이터 소스 URL의 호스트네임과 일치하는지 확인해요.
인증 오류 (Authentication errors)
이 오류들은 자격 증명이 잘못되었거나, 누락되었거나, 필요한 권한이 없을 때 발생해요.
"Unauthorized" 또는 "Access denied"
증상 (Symptoms):
- Save & test가
401 Unauthorized또는403 Forbidden으로 실패해요 - 쿼리가 액세스 거부 메시지를 반환해요
- 드롭다운 메뉴가 채워지지 않아요
가능한 원인과 해결책:
| 원인 | 해결책 |
|---|---|
| 잘못된 자격 증명 | 사용자 이름, 비밀번호, API 키, 토큰을 다시 확인해요. 필요하면 자격 증명을 재생성해요. |
| 만료된 자격 증명 | 새 자격 증명을 만들고 데이터 소스 구성을 업데이트해요. |
| 권한 부족 | 계정 또는 API 키가 데이터 소스에 필요한 권한을 갖고 있는지 확인해요. 필요한 권한은 해당 데이터 소스 설명서를 참고해요. |
| 잘못된 인증 방법 | 설정에 맞는 올바른 인증 유형을 선택했는지 확인해요. |
쿼리 오류 (Query errors)
이 오류들은 제대로 연결된 데이터 소스에 대해 쿼리를 실행할 때 발생해요.
"No data" 또는 빈 결과
증상 (Symptoms):
- 쿼리가 오류 없이 실행되지만 데이터를 반환하지 않아요
- 패널에 "No data"가 표시돼요
- 그래프가 비어 있어요
가능한 원인과 해결책:
| 원인 | 해결책 |
|---|---|
| 시간 범위에 데이터가 없음 | 대시보드 시간 범위를 넓히거나, 선택한 기간에 데이터 소스에 데이터가 존재하는지 확인해요. |
| 잘못된 쿼리 | 쿼리 문법을 검토해요. 데이터 소스의 쿼리 편집기로 쿼리를 작성하거나 검증해요. |
| 잘못된 데이터 소스 선택 | 패널 또는 Explore에서 올바른 데이터 소스를 선택했는지 확인해요. |
| 권한 문제 | 자격 증명이 쿼리 대상 리소스나 인덱스에 대한 읽기 권한을 갖고 있는지 확인해요. |
쿼리 타임아웃
증상 (Symptoms):
- 쿼리가 오랫동안 실행되다가 실패해요
- 오류 메시지가 타임아웃이나 쿼리 한도를 언급해요
해결책 (Solutions):
- 대시보드 시간 범위를 좁혀 데이터의 양을 줄여요.
- 쿼리에 필터를 추가해 결과 집합을 줄여요.
- 복잡한 쿼리를 더 작은 부분으로 나눠요.
- 데이터 소스가 합법적으로 더 많은 시간이 필요하다면 데이터 소스 타임아웃 설정을 늘려요.
데이터 소스 구성 오류 (Data source configuration errors)
프로비저닝 후 "Save & test" 실패
증상 (Symptoms):
- 프로비저닝된 데이터 소스가 연결 테스트를 실패해요
- 프로비저닝 YAML 파일 배포 후 오류가 나타나요
해결책 (Solutions):
- 프로비저닝 YAML 문법이 올바른지 확인해요. 예상 형식은 Provision data sources를 참고해요.
secureJsonData값(비밀번호, API 키, 토큰 등)이 올바르게 설정됐는지 확인해요. 이 값들은 저장 후에는 다시 읽을 수 없어요.- 프로비저닝 파일이 올바른 디렉터리에 있고 Grafana가 읽기 권한을 갖고 있는지 확인해요.
- 프로비저닝 파일 변경 후 Grafana를 재시작해요.
데이터 소스가 사라지거나 리셋됨
증상 (Symptoms):
- Grafana 재시작 후 데이터 소스 변경 사항이 되돌아가요
- UI를 통해 데이터 소스 구성을 저장할 수 없어요
해결책 (Solutions):
- 프로비저닝된 데이터 소스는 UI로 편집할 수 없어요. 대신 프로비저닝 YAML 파일에서 변경해요.
- 다른 프로비저닝 파일이 데이터 소스 구성을 덮어쓰고 있지 않은지 확인해요.
디버그 로깅 활성화 (Enable debug logging)
문제 해결을 위한 상세 오류 정보를 수집하려면:
- 구성 파일에서 Grafana 로그 레벨을
debug로 설정해요:
[log]
level = debug
- 변경 사항을 적용하려면 Grafana를 재시작해요.
- 문제를 재현하고
/var/log/grafana/grafana.log(또는 설정한 로그 위치)에서 로그를 확인해요. - 데이터 소스와 관련된 요청·응답 상세가 포함된 항목을 찾아봐요.
- 문제 해결 후 과도한 로그 양을 피하려면 로그 레벨을
info로 되돌려요.
추가 도움 받기 (Get additional help)
이 페이지의 해결책으로 문제가 해결되지 않는다면:
- 특정 데이터 소스의 문제 해결 페이지를 확인해요.
- Grafana 커뮤니티 포럼에서 비슷한 이슈를 검색해요.
- 알려진 버그는 Grafana GitHub issues에서 확인해요.
- Grafana Enterprise, Cloud Pro, Cloud Advanced 사용자라면 Grafana Support에 문의해요.
이슈를 보고할 때는 다음을 포함해요:
- Grafana 버전과 데이터 소스 플러그인 버전
- 정확한 오류 메시지(민감한 정보는 삭제)
- 문제를 재현하는 단계
- 관련 구성(자격 증명은 삭제)