Prometheus 데이터 소스 문제 해결

Prometheus 데이터 소스 문제 해결 (Troubleshoot Prometheus data source issues)

이 문서는 Grafana에서 Prometheus 데이터 소스를 사용할 때 흔히 겪는 오류에 대한 문제 해결 정보를 제공해요. 연결, 인증, 쿼리, 구성, 성능, 애노테이션, 알림 오류로 나눠서 설명합니다.

출처: 문서

본문

연결 오류 (Connection errors)

Prometheus에 연결 실패

  • 오류 메시지: "There was an error returned querying the Prometheus API"
  • 원인: Grafana가 Prometheus 서버에 네트워크 연결을 할 수 없어요.
  • 해결: Prometheus URL과 접근성을 확인하고, 방화벽·프록시 및 Grafana 서버에서의 네트워크 경로를 점검하세요.

요청 시간 초과 (Request timed out)

  • 오류 메시지: "context deadline exceeded" 또는 "request timeout"
  • 원인: 응답을 받기 전에 Prometheus 연결이 타임아웃됐어요.
  • 해결: 타임아웃 설정을 늘리고, Prometheus 서버 부하와 네트워크 대기 시간을 점검하세요.

데이터 소스 URL 파싱 실패

  • 오류 메시지: "Failed to parse data source URL"
  • 원인: 데이터 소스 구성에 입력한 URL이 유효하지 않아요.
  • 해결: URL 형식(프로토콜, 호스트, 포트)을 확인하세요.

Metrics Drilldown이나 Explore에 데이터가 안 보임

  • 증상: 데이터 소스 연결 테스트는 성공했지만 Explore나 Metrics Drilldown에 메트릭 데이터가 나타나지 않아요.
  • 원인: 잘못된 데이터 소스가 선택됐거나, 데이터 소스 이름이 기대와 다를 수 있어요.
  • 해결: 올바른 데이터 소스를 선택했는지 확인하세요.

PDC 연결 오류

  • 오류 메시지: host unreachable, EOF, network unreachable, connection reset by peer, dial tcp: lookup ... no such host
  • 증상: Private data source connect(PDC)로 프라이빗 네트워크 뒤의 Prometheus에 접근할 때 쿼리가 간헐적/지속적으로 실패해요.
  • 원인: PDC는 Grafana Cloud와 PDC 에이전트 사이의 SSH 연결로 트래픽을 터널링해요. 연결 실패는 DNS 해석 문제, 고객 측 네트워크 구성, 또는 쿼리 볼륨에 비해 PDC 에이전트의 기본 연결 한도가 낮은 것이 흔한 원인이에요.
  • 해결: DNS 해석, 방화벽 규칙, 라우팅을 점검하고 PDC 에이전트 연결 한도를 늘려보세요.

    참고: PDC 연결 문제는 거의 항상 Grafana Cloud가 아니라 고객 측 네트워킹(DNS, 방화벽 규칙, 라우팅) 때문이에요. 데이터 소스 테스트 통과가 부하 상태에서 지속적인 연결을 보장하지는 않아요. 단일 쿼리가 성공하는 것만 확인할 뿐이에요.

인증서 검증 실패

  • 오류 메시지: "x509: certificate signed by unknown authority" 또는 "certificate verify failed"
  • 원인: Grafana가 Prometheus가 제시한 TLS 인증서를 검증하지 못해요.
  • 해결: Prometheus에 신뢰할 수 있는 인증서를 사용하고, 필요한 경우 CA 번들을 Grafana에 추가하세요.

TLS 핸드셰이크 오류

  • 오류 메시지: "TLS: handshake failure" 또는 "connection reset"
  • 원인: Grafana와 Prometheus 사이의 TLS 핸드셰이크가 실패했어요.
  • 해결: TLS 버전, 사이퍼, 인증서를 점검하세요.

인증 오류 (Authentication errors)

인가되지 않음 (401)

  • 오류 메시지: "401 Unauthorized" 또는 "Authorization failed"
  • 원인: 인증 자격 증명이 유효하지 않거나 누락됐어요.
  • 해결: 자격 증명을 확인하고 다시 입력하세요.

OAuth 토큰 만료 오류 (GCP 및 Azure)

  • 오류 메시지: "ACCESS_TOKEN_EXPIRED", 알림에서만 "401 Unauthorized" (Explore에서는 정상)
  • 증상: Explore와 대시보드 쿼리는 정상이지만, 알림 규칙 평가가 401 오류로 간헐적으로 실패해요. OAuth/OIDC 인증을 사용하는 Google Managed Prometheus(GMP)와 Azure 관리 Prometheus 엔드포인트에서 가장 흔해요.
  • 원인: Grafana 알림 백엔드와 대화형 쿼리 경로(Explore, 대시보드)는 자격 증명 갱신을 다르게 처리해요. 알림 평가기가 토큰 만료 기간을 넘어 캐시된 OAuth 토큰을 사용할 수 있는데(토큰 오래됨 검사 문제), 그래서 대화형 쿼리는 새 토큰 교환을 트리거해 성공하지만 알림은 만료된 자격 증명으로 실패해요.
  • 해결:
    • GMP: 자격 증명 유효성 확인, 토큰 갱신 설정 점검.
    • Azure 관리 Prometheus: 관리 ID / 자격 증명 설정 확인.
    • 일반: Grafana를 최신 버전으로 업그레이드.

    참고: 이 토큰 캐싱 동작은 알려진 문제로 최근 Grafana 릴리스에서 수정됐어요. 구버전에서 겪고 있다면 업그레이드로 해결될 수 있어요.

Mimir가 아닌 백엔드에서 LBAC가 데이터를 제한하지 않음

  • 증상: 팀 LBAC 규칙을 구성했는데도 팀 할당과 관계없이 모든 메트릭이 보여요.
  • 원인: Prometheus 데이터 소스의 LBAC는 백엔드가 Grafana Cloud Metrics(Mimir) 또는 Grafana Enterprise Metrics(GEM)일 때만 동작해요. Google Managed Prometheus, 자체 관리 Prometheus, Thanos 등에서는 동작하지 않아요. LBAC 적용은 Mimir 전용 HTTP 헤더(X-Scope-OrgID와 팀 범위 라벨 매처)에 의존하는데, 다른 백엔드는 이를 무시해요.
  • 해결: Mimir/GEM 백엔드를 사용하거나 Mimir로 마이그레이션하세요.

Azure AD 또는 SigV4 인증 옵션 사용 불가

  • 증상: Prometheus 데이터 소스 구성 시 인증 드롭다운에 Azure AD나 SigV4 옵션이 나타나지 않아요.
  • 원인: 이 인증 방법은 기본적으로 활성화되지 않은 서버 측 기능 플래그가 필요해요.
  • 해결: Grafana Cloud는 지원 요청을 제출하고, 자체 관리 인스턴스는 구성 파일에서 기능 플래그를 활성화하세요.

금지됨 (403)

  • 오류 메시지: "403 Forbidden" 또는 "Access denied"
  • 원인: 인증된 사용자에게 요청 리소스에 대한 권한이 없어요.
  • 해결: 사용자 권한과 데이터 소스 권한을 확인하세요.

쿼리 오류 (Query errors)

쿼리 구문 오류

  • 오류 메시지: parse error: unexpected character 또는 bad_data: 1:X: parse error
  • 원인: PromQL 쿼리에 잘못된 구문이 포함됐어요.
  • 대체 원인: Grafana와 Prometheus 사이의 프록시가 인증을 요구하는 경우. 프록시 인증이 실패하면 프록시가 요청을 HTML 인증 페이지로 리다이렉트하고, Grafana는 HTML 응답을 파싱하지 못해 parse error가 발생해요. 쿼리 문제처럼 보이지만 실제로는 프록시 인증 문제예요.
  • 해결: 쿼리 구문을 확인하고, 프록시 인증 설정을 점검하세요.

메트릭에 데이터가 없음

  • 증상: 쿼리가 데이터를 반환하지 않고 시각화가 비어 있어요.
  • 원인: 지정한 메트릭이 Prometheus에 없거나, 선택한 시간 범위에 데이터가 없어요.
  • 해결: 메트릭 이름과 시간 범위를 확인하세요.

쿼리 타임아웃 한도 초과

  • 오류 메시지: "query timed out in expression evaluation" 또는 "query processing would load too many samples"
  • 원인: 쿼리가 구성된 타임아웃 한도를 초과했거나 너무 많은 샘플을 반환했어요.
  • 해결: 쿼리를 단순화하거나 시간 범위를 줄이세요.

너무 많은 타임시리즈 (Too many time series)

  • 오류 메시지: exceeded maximum resolution of 11,000 points per timeseries 또는 maximum number of series limit exceeded
  • 원인: 쿼리가 구성된 한도보다 더 많은 시리즈나 데이터 포인트를 반환해요.
  • 해결: 쿼리를 좁히고 집계를 사용하세요.

고카디널리티 쿼리 메모리 한도 초과

  • 오류 메시지: "max-estimated-memory-consumption-per-query limit exceeded", "query requires too much memory", "max samples limit reached"
  • 증상: 고카디널리티 메트릭(수천 개의 고유 라벨 조합)을 며칠~몇 주의 긴 시간 범위로 조회하면 메모리/샘플 한도 오류로 실패해요. 짧은 시간 범위는 동작하지만 범위를 늘리면 실패해요.
  • 원인: Prometheus와 Mimir는 시스템 리소스 고갈을 막기 위해 쿼리당 메모리·샘플 한도를 적용해요. 고카디널리티 메트릭(pod, request_id, user_id 라벨 등)에 긴 시간 범위를 곱하면 이 한도를 초과하는 결과 집합이 생겨요.
  • 해결: 시간 범위를 줄이고, 쿼리에서 집계·라벨 축소를 사용하며, 스크레이프 시 불필요한 고카디널리티 라벨을 제거하세요.

잘못된 함수 또는 집계

  • 오류 메시지: "unknown function" 또는 "parse error: unexpected aggregation"
  • 원인: 쿼리가 잘못되었거나 지원되지 않는 PromQL 함수를 사용해요.
  • 해결: 함수 이름과 버전 호환성을 확인하세요.

rate() 또는 increase()가 예상치 못한 값 반환

  • 증상: increase()가 정수 카운터에서 분수 값을 반환하고, rate()가 안정된 초당 속도 대신 계속 증가하는 값을 보이며, 카운터 리셋이 시각화에서 큰 스파이크를 발생시켜요.
  • 원인 및 해결:
원인 해결
increase() 분수 값 기대되는 동작. Prometheus는 선형 보간을 사용. 정수가 필요하면 ceil()/floor() 사용
rate()가 시간이 지나며 증가 여러 인스턴스가 고유 라벨 없이 같은 시리즈에 기록. 각 타깃에 고유한 instance/pod 라벨을 주고 sum by로 집계
Pod 재시작 후 카운터 리셋 스파이크 $__rate_interval이나 더 긴 range vector로 스파이크를 완화. 잦은 재시작이 근본 원인인지 조사
편집 모드와 대시보드 값이 다름 패널 너비가 $__interval에 영향, rate() 창 계산에 영향. 쿼리에 Min step 설정

점이 있는 라벨로 집계

  • 증상: 이름에 점이 있는 라벨(예: container.name)로 집계하는 쿼리가 잘못되거나 불완전한 결과를 반환해요.
  • 원인: Grafana 13 이전에는 sum by나 avg by 같은 집계 연산 중 이름에 점이 있는 라벨이 제대로 처리되지 않는 버그가 있었어요.
  • 해결: Grafana 13 이상으로 업그레이드하세요.

구성 오류 (Configuration errors)

잘못된 Prometheus 유형

  • 오류 메시지: 메트릭이나 라벨 조회 시 예기치 않은 동작
  • 원인: Prometheus 유형 설정이 실제 Prometheus 호환 데이터베이스와 일치하지 않아요.
  • 해결: 데이터 소스 구성에서 올바른 Prometheus 유형을 선택하세요.

스크레이프 간격 불일치

  • 증상: 데이터가 드문드문 보이거나, rate() 쿼리가 데이터를 반환하지 않거나 불완전해요.
  • 원인: Grafana의 Scrape interval 설정이 Prometheus의 실제 스크레이프 간격과 일치하지 않아요. 특히 rate() 쿼리는 지정된 시간 창 안에 최소 2개의 데이터 포인트가 필요해요. 예를 들어 실제 스크레이프 간격이 5분인데 Grafana가 기본값(OSS는 15초, Grafana Cloud는 1분)을 쓰면 rate(http_requests_total[1m])은 그 1분 창 안에 데이터 포인트가 없어 데이터를 반환하지 않아요.
  • 해결: 데이터 소스 구성의 Interval behavior에서 Scrape interval을 실제 스크레이프 간격과 일치시키세요.

$__rate_interval이 데이터를 반환하지 않거나 잘못된 값 반환

  • 증상: $__rate_interval을 쓰는 쿼리가 데이터를 반환하지 않거나, 편집 모드와 대시보드에서 값이 다르거나, 예기치 않은 공백이 생겨요.
  • 원인: $__rate_interval은 max($__interval + scrape_interval, 4 * scrape_interval)로 계산돼요. 이 공식의 어느 입력이 잘못되면 결과 창도 잘못돼요(너무 작아 데이터 없음, 또는 컨텍스트 간 불일치).
  • 원인과 해결:
원인 해결
데이터 소스 스크레이프 간격이 기본 15s인데 실제 Prometheus 스크레이프 간격이 더 길다(예: 60s) 데이터 소스 구성의 Interval behavior에서 Scrape interval을 Prometheus scrape_interval과 일치시키기
편집 모드에서는 동작하지만 대시보드에 공백 패널 크기가 $__interval에 영향. 작은 패널일수록 큰 간격이 됨. 쿼리에 Min step 설정
LBAC 활성화 데이터 소스가 스크레이프 간격을 상속하지 않음 데이터 소스 상속에 의존하지 말고 각 쿼리 패널에 Min step을 명시적으로 설정
recording rules나 알림에서 $__rate_interval 사용 패널/대시보드가 없는 컨텍스트에서는 고정 간격(예: [5m]) 사용

성능 문제 (Performance issues)

느린 쿼리 성능

  • 증상: 쿼리 실행이 오래 걸리고, 대시보드 로드가 느리며, 로딩 스피너가 계속돼요.
  • 원인: 쿼리가 너무 많은 데이터를 스캔하거나, Prometheus 서버가 과부하되거나, 네트워크 연결이 느려요.
  • 해결: 쿼리를 최적화하고 자주 쓰는 쿼리에 recording rules를 사용하세요.

데이터가 지연되거나 최근 포인트가 누락

  • 증상: 새로고침해도 최근 데이터가 표시되지 않아요.
  • 원인: 스크레이프 타이밍, 클록 드리프트, 대시보드 새로고침 설정.
  • 해결: 스크레이프 간격과 새로고침 설정을 확인하세요.

Exemplar가 표시되지 않음

  • 증상: 예상했는데도 그래프에 exemplar 데이터가 나타나지 않아요.
  • 원인: exemplar는 데이터 소스와 쿼리 에디터 양쪽 모두에서 특정 구성이 필요해요.
  • 해결: 데이터 소스의 exemplar 구성과 쿼리 에디터의 Exemplars 토글을 확인하세요.

애노테이션 오류 (Annotation errors)

애노테이션이 나타나지 않음

  • 원인과 해결:
원인 해결
현재 시간 범위에 쿼리가 데이터 없음 대시보드 시간 범위에서 Explore로 쿼리가 결과를 반환하는지 확인
쿼리가 연속 데이터를 반환(애노테이션 과다) 반환된 각 데이터 포인트가 애노테이션을 만듦. 수백 개면 너무 조밀. Min step을 늘리거나 이벤트 시점에만 데이터를 반환하도록 쿼리 개선
잘못된 데이터 소스 선택 애노테이션 구성에서 올바른 Prometheus 데이터 소스가 선택됐는지 확인
애노테이션 비활성화 대시보드 애노테이션 설정에서 토글(눈 아이콘)이 켜졌는지 확인
시간 범위 불일치 기대하는 이벤트를 포함하도록 대시보드 시간 범위 확장

참고: Prometheus 애노테이션은 쿼리가 반환하는 모든 데이터 포인트에 마커를 만들어요. 0 값을 자동 필터링하지 않아요. 특정 시점에만 애노테이션을 원한다면 PromQL 표현식이 그 시간에만 데이터를 반환해야 해요(예: > 0, changes() > 0, ALERTS 메트릭 사용).

알림 오류 (Alerting errors)

일시적 알림 오류로 거짓 경보 발생

  • 오류 메시지: sse.dependencyError, sse.dataQueryError, "context deadline exceeded", "i/o timeout"
  • 증상: 알림 규칙이 실제 임계값 위반이 아니라 실행 오류 때문에 간헐적으로 발화해요. 실제 메트릭 조건이 충족되지 않았는데도 일시적 백엔드 문제(네트워크 일시 끊김, HTTP 502/500 응답, 타임아웃)로 인한 오류 상태가 알림 상태 기록에 보여요.
  • 원인: 기본적으로 알림 규칙이 실행 오류나 타임아웃을 만나면 Grafana는 알림 상태를 Alerting으로 설정해 알림을 발화해요. Grafana와 Prometheus 사이의 일시적 연결 문제는 기본 메트릭이 임계값을 넘지 않았는데도 이 동작을 트리거해요.
  • 해결: 실행 오류 시 알림 상태를 이전 상태로 유지(또는 NoData) 하도록 구성해 일시적 오류 중에도 이전 상태를 유지하고, 성공적 평가로 임계값 위반이 확인됐을 때만 발화하세요. 오류가 잦다면 네트워크 안정성과 타임아웃 설정도 조사하세요.

알림 규칙 평가 실패

  • 원인과 해결:
원인 해결
쿼리에 템플릿 변수 알림 쿼리는 템플릿 변수를 지원하지 않음. 변수를 하드코딩된 값으로 교체
쿼리 타임아웃 쿼리를 단순화하거나 평가 타임아웃을 늘림. 복잡한 표현식은 recording rules 사용
데이터 소스 도달 불가 데이터 소스 연결이 동작하는지 확인(설정에서 테스트)
범위에 데이터 없음 메트릭에 최근 데이터가 있는지 확인. Prometheus가 타깃을 스크레이프 중인지 점검

데이터 소스 관리 규칙이 보이지 않음

  • 증상: Prometheus 알림 규칙이 Grafana Alerting UI에 나타나지 않아요.
  • 해결: Prometheus의 alerting 규칙 관리 방식과 Grafana 알림 보기 설정을 확인하세요.

더 알아보기 (Learn more)