Prometheus용 관리형 서비스 문제 해결

이 문서에서는 Google Cloud Managed Service for Prometheus를 사용할 때 발생할 수 있는 몇 가지 문제에 대해 설명하고 문제 진단 및 해결에 관한 정보를 제공합니다.

Prometheus용 관리형 서비스를 구성했지만 Grafana 또는 Prometheus UI에 측정항목 데이터가 표시되지 않습니다. 대략적으로 원인은 다음 중 하나일 수 있습니다.

  • 쿼리 측 문제로 인해 데이터를 읽을 수 없습니다. 쿼리 측 문제는 주로 데이터를 읽는 서비스 계정에 대해 권한이 잘못되었거나 Grafana 구성이 잘못되어 발생합니다.

  • 수집 측 문제로 인해 데이터가 전송되지 않습니다. 수집 측 문제는 주로 서비스 계정, 수집기, 규칙 평가에 대한 구성 문제로 인해 발생할 수 있습니다.

문제가 수집 측인지 쿼리 측인지 확인하려면 Google Cloud 콘솔의 측정항목 탐색기 PromQL 탭을 사용하여 데이터를 쿼리해 봅니다. 이 페이지에서는 읽기 권한이나 Grafana 설정 관련 문제가 발생하지 않습니다.

이 페이지를 보려면 다음을 수행합니다.

  1. Google Cloud Console 프로젝트 선택 도구를 사용하여 데이터가 표시되지 않는 프로젝트를 선택합니다.

  2. Google Cloud 콘솔의 탐색 패널에서 Monitoring을 선택한 후 측정항목 탐색기를 선택합니다.

    측정항목 탐색기로 이동

  3. 쿼리 빌더 창의 툴바에서 이름이  MQL 또는  PromQL인 버튼을 선택합니다.

  4. 언어 전환 버튼에 PromQL이 선택되어 있는지 확인합니다. 언어 전환 버튼은 쿼리 형식을 지정할 수 있는 동일한 툴바에 있습니다.

  5. 편집기에 다음 쿼리를 입력한 후 쿼리 실행을 클릭합니다.

    up

up 측정항목을 쿼리하고 결과가 표시되면 쿼리 측 문제입니다. 이러한 문제 해결에 대한 자세한 내용은 쿼리 측 문제를 참조하세요.

up 측정항목을 쿼리하고 결과가 표시되지 않으면 수집 측 문제입니다. 이러한 문제 해결에 대한 자세한 내용은 수집 측 문제를 참조하세요.

방화벽으로 인해 수집 및 쿼리 문제가 발생할 수도 있습니다. 자세한 내용은 방화벽을 참조하세요.

Cloud Monitoring 측정항목 관리 페이지에서는 관측 가능성에 영향을 주지 않고 청구 가능 측정항목에 지출하는 금액을 제어하는 데 도움이 되는 정보를 제공합니다. 측정항목 관리 페이지에서는 다음 정보를 보고합니다.

  • 측정항목 도메인 및 개별 측정항목의 바이트 기반 및 샘플 기반 청구에 대한 수집량
  • 측정항목의 라벨 및 카디널리티에 대한 데이터
  • 알림 정책 및 커스텀 대시보드의 측정항목 사용
  • 측정항목 쓰기 오류의 비율

측정항목 관리 페이지를 보려면 다음을 수행합니다.

  1. Google Cloud 콘솔의 탐색 패널에서 Monitoring을 선택한 후 측정항목 관리를 선택합니다.

    측정항목 관리로 이동

  2. 툴바에서 기간을 선택합니다. 기본적으로 측정항목 관리 페이지에는 이전 1일 동안 수집된 측정항목에 대한 정보가 표시됩니다.

측정항목 관리 페이지에 대한 자세한 내용은 측정항목 사용량 보기 및 관리를 참조하세요.

쿼리 측 문제

대부분 쿼리 측 문제의 원인은 다음 중 하나입니다.

먼저 다음을 수행합니다.

  • 쿼리 설정 안내에 따라 구성을 자세히 확인합니다.

  • 워크로드 아이덴티티를 사용하는 경우 다음을 수행해서 서비스 계정에 올바른 권한이 있는지 확인합니다.

    1. Google Cloud 콘솔의 탐색 패널에서 IAM을 선택합니다.

      IAM으로 이동

    2. 주 구성원 목록에서 서비스 계정 이름을 식별합니다. 서비스 계정 이름의 철자가 올바른지 확인합니다. 그런 후 수정을 클릭합니다.

    3. 역할 필드를 선택한 후 현재 사용 중을 클릭하고 모니터링 뷰어 역할을 찾습니다. 서비스 계정에 이 역할이 없으면 지금 추가합니다.

문제가 지속되면 다음 가능성을 고려하세요.

잘못 구성되었거나 잘못 입력된 보안 비밀

다음 항목이 표시되면 보안 비밀이 누락되었거나 잘못 입력되었을 수 있습니다.

  • Grafana 또는 Prometheus UI에서 다음 '금지됨' 오류 중 하나가 표시되는 경우:

    • '경고: 서버 시간을 가져올 때 예상치 않은 응답 상태: 금지됨'
    • '경고: 측정항목 목록을 가져오는 중 오류 발생: 측정항목 이름을 가져올 때 예상치 않은 응답 상태: 금지됨'

  • 로그에 다음 메시지가 표시되는 경우:
    '사용자 인증 정보 파일을 읽을 수 없음: /gmp/key.json 열기: 해당 파일 또는 디렉터리가 없음'

데이터 소스 동기화를 사용하여 Grafana를 인증하고 구성하는 경우 다음을 시도하여 이러한 오류를 해결합니다.

  1. 올바른 Grafana API 엔드포인트, Grafana 데이터 소스 UID, Grafana API 토큰을 선택했는지 확인합니다. kubectl describe cronjob datasource-syncer 명령어를 실행하여 CronJob의 변수를 검사할 수 있습니다.

  2. 서비스 계정이 사용자 인증 정보를 갖고 있는 것과 동일한 측정항목 범위 또는 프로젝트로 데이터 소스 동기화의 프로젝트 ID를 설정했는지 확인합니다.

  3. Grafana 서비스 계정에 '관리자' 역할이 있고 API 토큰이 만료되지 않았는지 확인합니다.

  4. 서비스 계정에 선택한 프로젝트 ID의 모니터링 뷰어 역할이 있는지 확인합니다.

  5. kubectl logs job.batch/datasource-syncer-init를 실행하여 데이터 소스 동기화 작업의 로그에 오류가 없는지 확인합니다. 이 명령어는 datasource-syncer.yaml 파일을 적용한 후 즉시 실행해야 합니다.

  6. 워크로드 아이덴티티를 사용하는 경우 계정 키 또는 사용자 인증 정보를 올바르게 입력했는지 확인하고 이를 올바른 네임스페이스에 바인딩했는지 확인합니다.

기존 프런트엔드 UI 프록시를 사용하는 경우 다음을 시도하여 이러한 오류를 해결합니다.

  1. 프런트엔드 UI의 프로젝트 ID를 동일한 측정항목 범위 또는 서비스 계정에 사용자 인증 정보가 포함된 프로젝트로 설정했는지 확인합니다.

  2. --query.project-id 플래그에 대해 지정한 프로젝트 ID를 확인합니다.

  3. 서비스 계정에 선택한 프로젝트 ID의 모니터링 뷰어 역할이 있는지 확인합니다.

  4. 프런트엔드 UI를 배포할 때 올바른 프로젝트 ID를 설정했고 리터럴 문자열 PROJECT_ID로 설정된 상태로 두지 않았는지 확인합니다.

  5. 워크로드 아이덴티티를 사용하는 경우 계정 키 또는 사용자 인증 정보를 올바르게 입력했는지 확인하고 이를 올바른 네임스페이스에 바인딩했는지 확인합니다.

  6. 자체 보안 비밀을 마운트할 경우 보안 비밀이 있는지 확인합니다.

    kubectl get secret gmp-test-sa -o json | jq '.data | keys'

  7. 보안 비밀이 현재 마운트되었는지 확인합니다.

    kubectl get deploy frontend -o json | jq .spec.template.spec.volumes

kubectl get deploy frontend -o json | jq .spec.template.spec.containers[].volumeMounts

  8. 보안 비밀이 컨테이너에 올바르게 전달되었는지 확인합니다. 

    kubectl get deploy frontend -o json | jq .spec.template.spec.containers[].args

Grafana의 잘못된 HTTP 메서드

Grafana에서 다음 API 오류가 표시되면 Grafana가 GET 요청 대신 POST 요청을 전송하도록 구성된 것입니다.

  • '{'상태':'오류','errorType':'bad_data','오류':'제공된 match[] 매개변수 없음'}%"

이 문제를 해결하려면 데이터 소스 구성의 안내에 따라 GET 요청을 사용하도록 Grafana를 구성합니다.

대용량 또는 장기 실행 쿼리 제한 시간

Grafana에 다음 오류가 표시되면 기본 쿼리 제한 시간이 너무 짧은 것입니다.

  • "Post "http://frontend.NAMESPACE_NAME.svc:9090/api/v1/query_range": net/http: timeout awaiting response headers"

쿼리가 120초를 초과할 때까지 Managed Service for Prometheus는 타임아웃되지 않으며 기본적으로 30초 후에 Grafana가 타임아웃됩니다. 이 문제를 해결하려면 데이터 소스 구성의 안내에 따라 Grafana의 제한 시간을 120초로 늘립니다.

라벨 검증 오류

Grafana에 다음 오류 중 하나가 표시되는 경우는 지원되지 않는 엔드포인트를 사용 중일 수 있습니다.

  • '검증: 이름 이외의 라벨은 아직 지원되지 않음'
  • '템플릿 지정 [job]: 오류 업데이트 옵션: 이름 이외의 라벨은 아직 지원되지 않습니다.'

Prometheus용 관리형 서비스는 __name__ 라벨에 대해서만 /api/v1/$label/values 엔드포인트를 지원합니다. 이 제한으로 인해 Grafana에서 label_values($label) 변수를 사용하는 쿼리가 실패합니다.

대신 label_values($metric, $label) 양식을 사용하세요. 이 쿼리는 반환되는 라벨 값을 측정항목으로 제한하여 대시보드 내용과 관련이 없는 값이 검색되지 않도록 방지하기 때문에 권장됩니다. 이 쿼리는 Prometheus에 대해 지원되는 엔드포인트를 호출합니다.

지원되는 엔드포인트에 대한 자세한 내용은 API 호환성을 참조하세요.

할당량이 초과됨

다음 오류가 표시되면 Cloud Monitoring API의 읽기 할당량이 초과된 것입니다.

  • '429: RESOURCE_EXHAUSTED: 'project_number:...' 소비자의 .'monitoring.googleapis.com' 서비스에 대한 '시계열 쿼리' 할당량 측정항목 및 '분당 시계열 쿼리' 제한에 대해 할당량이 초과되었습니다.'

이 문제를 해결하려면 Monitoring API에 대해 읽기 할당량을 늘리도록 요청을 제출하세요. 도움이 필요하면 Google Cloud 지원팀에 문의하세요. 할당량에 대한 자세한 내용은 할당량 작업을 참조하세요.

여러 프로젝트의 측정항목

여러 Google Cloud 프로젝트의 측정항목을 보려는 경우에는 여러 데이터 소스 동기화를 구성하거나 Grafana에서 여러 데이터 소스를 만들 필요가 없습니다.

대신 모니터링하려는 프로젝트가 포함된 범위 지정 프로젝트인 하나의 Google Cloud 프로젝트에서 Cloud Monitoring 측정항목 범위를 만듭니다. 범위 지정 프로젝트를 사용해서 Grafana 데이터 소스를 구성하는 경우에는 측정항목 범위에 있는 모든 프로젝트의 데이터에 액세스합니다. 자세한 내용은 쿼리 및 측정항목 범위를 참조하세요.

모니터링 리소스 유형이 지정되지 않음

다음 오류가 표시되면 PromQL을 사용하여 Google Cloud 시스템 측정항목을 쿼리할 때 모니터링 리소스 유형을 지정해야 합니다.

  • '측정항목이 모니터링 리소스 유형 두 개 이상과 함께 사용하도록 구성되었습니다. 계열 선택기는 모니터링 리소스 이름에 라벨 일치자를 지정해야 합니다.'

monitored_resource 라벨을 사용하여 필터링해 모니터링 리소스 유형을 지정할 수 있습니다. 유효한 모니터링 리소스 유형을 식별하고 선택하는 방법에 대한 자세한 내용은 모니터링 리소스 유형 지정을 참조하세요.

수집기 UI와 Google Cloud 콘솔 사이의 카운터 합계가 일치하지 않음

원시 카운터 또는 카운터 합계를 쿼리할 때 로컬 수집기 Prometheus UI와 Google Cloud Console의 값에 차이가 있을 수 있습니다. 이는 예상되는 동작입니다.

Monarch에 시작 타임스탬프가 필요하지만 Prometheus에 시작 타임스탬프가 없습니다. Prometheus용 관리형 서비스는 시계열의 첫 번째 수집 지점을 건너뛰고 이를 시작 타임스탬프로 변환하여 시작 타임스탬프를 생성합니다. 그 결과 카운터 합계가 계속 부족하게 표시됩니다.

수집기 UI에서의 숫자와 Google Cloud console에서의 숫자 간 차이는 수집기 UI에 기록된 첫 번째 값과 동일하며, 이는 시스템이 해당 초기 값을 건너뛰기 때문에 예상되는 값입니다.

이는 프로덕션에서 원시 카운터 값에 대한 쿼리를 실행할 필요가 없기 때문에 허용됩니다. 카운터의 모든 유용한 쿼리에는 rate() 함수와 같은 것이 필요합니다. 여기에서 시간 범위 차이는 두 UI 사이에 동일합니다. 카운터만 증가하고, 시계열이 기준점에 한 번만 도달하므로 원시 쿼리에 대해 알림을 설정할 수 없습니다. 모든 유용한 알림 및 차트는 값의 변경 또는 변경 비율을 살펴봅니다.

수집기는 약 10분간의 데이터만 로컬에 보관합니다. 원시 카운터 합계의 불일치는 10분 범위 이전에 발생하는 카운터 재설정으로 인해 발생할 수도 있습니다. 이러한 가능성을 배제하려면 수집기 UI를 Google Cloud Console과 비교할 때 쿼리 전환 확인 기간을 10분만 설정해 보세요.

애플리케이션에 /metrics 엔드포인트가 있는 여러 작업자 스레드가 있으면 불일치가 발생할 수도 있습니다. 애플리케이션이 여러 스레드를 가동하는 경우 Prometheus 클라이언트 라이브러리를 다중 프로세스 모드로 설정해야 합니다. 자세한 내용은 Prometheus의 Python 클라이언트 라이브러리에서 다중 프로세스 모드 사용 문서를 참조하세요.

카운터 데이터 누락 또는 히스토그램 손상

이 문제의 가장 일반적인 신호는 일반 카운터 측정항목(예: metric_name_foo의 PromQL 쿼리)을 쿼리할 때 데이터가 없거나 데이터 격차가 보이는 것입니다. 쿼리에 rate 함수를 추가한 후(예: rate(metric_name_foo[5m])) 데이터가 표시되면 이를 확인할 수 있습니다.

또한 스크래핑 볼륨이 크게 변경되지 않고 수집된 샘플이 크게 증가하거나 Cloud Monitoring에서 "unknown" 또는 "unknown:counter" 서픽스로 새로운 측정항목이 생성되는 것을 확인할 수 있습니다.

또한 quantile() 함수와 같은 히스토그램 작업이 예상한 대로 작동하지 않는 것을 볼 수 있습니다.

이러한 문제는 Prometheus 측정항목 유형 없이 측정항목이 수집될 때 발생합니다. Monarch는 강력하게 유형화됩니다. 따라서 Managed Service for Prometheus는 유형화되지 않은 측정항목에 "알 수 없음"을 서픽스로 추가하고 각각 게이지 및 카운터로 한 번씩 두 번 처리합니다. 그런 다음 쿼리 엔진은 사용되는 쿼리 함수를 기반으로 기본 게이지 또는 카운터 측정항목을 쿼리할지 여부를 선택합니다.

이 휴리스틱은 일반적으로 잘 작동하지만 원시 "알 수 없음: 카운터" 측정항목을 쿼리할 때의 잘못된 결과와 같은 문제로 이어질 수 있습니다. 또한 Monarch에서 히스토그램은 특별하게 유형화된 객체이므로, 3개의 필수 히스토그램 측정항목을 개별 카운트 측정항목으로 처리하면 히스토그램 함수가 작동하지 않습니다. "알 수 없음" 유형의 측정항목은 두 번 처리되므로, TYPE을 설정하지 않으면 처리되는 샘플이 두 배로 증가합니다.

TYPE이 설정되지 않는 일반적인 이유는 다음과 같습니다.

  • Managed Service for Prometheus 수집기를 페더레이션 서버로 잘못 구성하는 경우. Prometheus용 관리형 서비스를 사용하는 경우 페데레이션이 지원되지 않습니다. 페더레이션은 TYPE 정보를 의도적으로 삭제하기 때문에 페더레이션을 구현하면 "알 수 없음" 유형의 측정항목이 발생합니다.
  • 처리 파이프라인의 임의 지점에서 Prometheus 원격 쓰기를 사용하는 경우. 이 프로토콜은 의도적으로 TYPE 정보를 삭제합니다.
  • 측정항목 이름을 수정하는 라벨 재지정 규칙을 사용하는 경우. 그러면 이름이 바뀐 측정항목이 원래 측정항목 이름과 연결된 TYPE 정보에서 연결 해제됩니다.
  • 내보내기 도구가 각 측정항목에 대해 TYPE을 내보내지 않는 경우.
  • 수집기가 처음 시작될 때 TYPE이 삭제되는 일시적인 문제.

이 문제를 해결하려면 다음 단계를 따르세요.

  • Prometheus용 관리형 서비스에 페더레이션을 사용 중지합니다. Monarch로 데이터를 전송하기 전에 데이터를 '롤업'하여 카디널리티와 비용을 줄이려면 로컬 집계 구성을 참조하세요.
  • 컬렉션 경로에서 Prometheus 원격 쓰기 사용을 중지합니다.
  • /metrics 엔드포인트를 방문하여 각 측정항목에 대해 # TYPE 필드가 존재하는지 확인합니다.
  • 측정항목 이름을 수정하는 라벨 재지정 규칙을 삭제합니다.
  • DeleteMetricDescriptor를 호출하여 'unknown' 또는 'unknown:counter' 서픽스가 있는 충돌 측정항목을 삭제합니다.
  • 또는 항상 rate 또는 다른 카운터 처리 함수를 사용하여 카운터를 쿼리합니다.

포드를 다시 시작한 후 Grafana 데이터가 유지되지 않음

포드가 다시 시작된 후 데이터가 Grafana에서 사라진 것처럼 보이지만 Cloud Monitoring에 표시되면 Grafana를 사용하여 Prometheus용 관리형 서비스 대신 로컬 Prometheus 인스턴스를 쿼리합니다.

관리형 서비스를 데이터 소스로 사용하도록 Grafana를 구성하는 방법은 Grafana를 참조하세요.

Grafana 대시보드 가져오기

대시보드 가져오기 도구의 사용 및 문제 해결에 대한 자세한 내용은 Cloud Monitoring으로 Grafana 대시보드 가져오기를 참조하세요.

대시보드 콘텐츠 변환 문제에 대한 자세한 내용은 가져오기 도구의 README 파일을 참조하세요.

수집 측 문제

수집 측 문제는 컬렉션 또는 규칙 평가와 관련될 수 있습니다. 먼저 오류 로그에서 관리형 컬렉션을 찾아봅니다. 다음 명령어를 실행할 수 있습니다.

kubectl logs -f -n gmp-system -lapp.kubernetes.io/part-of=gmp

kubectl logs -f -n gmp-system -lapp.kubernetes.io/name=collector -c prometheus

GKE Autopilot 클러스터에서 다음 명령어를 실행할 수 있습니다.

kubectl logs -f -n gke-gmp-system -lapp.kubernetes.io/part-of=gmp

kubectl logs -f -n gke-gmp-system -lapp.kubernetes.io/name=collector -c prometheus

대상 상태 기능은 스크래핑 대상을 디버깅하는 데 도움이 됩니다. 자세한 내용은 대상 상태 정보를 참조하세요.

엔드포인트 상태가 없거나 너무 오래됨

대상 상태 기능을 사용 설정했지만 하나 이상의 PodMonitoring 또는 ClusterPodMonitoring 리소스에 Status.Endpoint Statuses 필드 또는 값이 누락된 경우 다음 문제 중 하나일 수 있습니다.

  • Managed Service for Prometheus가 엔드포인트 중 하나와 동일한 노드의 수집기에 연결할 수 없습니다.
  • PodMonitoring 또는 ClusterPodMonitoring 구성 중 하나 이상이 유효한 대상이 아닙니다.

유사한 문제로 인해 Status.Endpoint Statuses.Last Update Time 필드의 값이 스크래핑 간격에 몇 분을 더한 것을 초과할 수도 있습니다.

이 문제를 해결하려면 먼저 스크래핑 엔드포인트와 연결된 Kubernetes 포드가 실행 중인지 확인하세요. Kubernetes 포드가 실행 중이고 라벨 선택기가 일치하며 스크래핑 엔드포인트(일반적으로 /metrics 엔드포인트 방문)에 수동으로 액세스할 수 있으면 Managed Service for Prometheus 수집기가 실행 중인지 확인하세요.

수집기 비율이 1 미만

대상 상태 기능을 사용 설정한 경우 리소스에 대한 상태 정보를 가져옵니다. PodMonitoring 또는 ClusterPodMonitoring 리소스의 Status.Endpoint Statuses.Collectors Fraction 값은 연결할 수 있는 0에서 1로 표현되는 수집기의 비율을 나타냅니다. 예를 들어 0.5 값은 수집기의 50%에 연결할 수 있음을 나타내고 1 값은 수집기의 100%에 연결할 수 있음을 나타냅니다.

Collectors Fraction 필드에 1 이외의 값이 있으면 하나 이상의 수집기에 연결할 수 없으며, 해당 노드의 측정항목이 스크레이핑되지 않을 수 있습니다. 모든 수집기가 실행 중이고 클러스터 네트워크를 통해 연결 가능한지 확인합니다. 다음 명령어를 사용하여 수집기 포드의 상태를 볼 수 있습니다.

kubectl -n gmp-system get pods --selector="app.kubernetes.io/name=collector"

GKE Autopilot 클러스터에서 이 명령어는 약간 다릅니다.

kubectl -n gke-gmp-system get pods --selector="app.kubernetes.io/name=collector"

다음 명령어를 사용하여 개별 수집기 포드(예: collector-12345라는 수집기 포드)를 조사할 수 있습니다.

kubectl -n gmp-system describe pods/collector-12345

GKE Autopilot 클러스터에서 다음 명령어를 실행합니다.

kubectl -n gke-gmp-system describe pods/collector-12345

수집기가 정상이 아니면 GKE 워크로드 문제 해결을 참조하세요.

수집기가 정상이면 연산자 로그를 확인합니다. 연산자 로그를 확인하려면 먼저 다음 명령어를 실행하여 연산자 포드 이름을 찾습니다.

kubectl -n gmp-system get pods --selector="app.kubernetes.io/name=gmp-collector"

GKE Autopilot 클러스터에서 다음 명령어를 실행합니다.

kubectl -n gke-gmp-system get pods --selector="app.kubernetes.io/name=gmp-collector"

그런 후 다음 명령어로 연산자 로그(예: gmp-operator-12345라는 연산자 포드)를 확인합니다.

kubectl -n gmp-system logs pods/gmp-operator-12345

GKE Autopilot 클러스터에서 다음 명령어를 실행합니다.

kubectl -n gke-gmp-system logs pods/gmp-operator-12345

비정상 대상

대상 상태 기능을 사용 설정했지만 하나 이상의 PodMonitoring 또는 ClusterPodMonitoring 리소스에 값이 0이 아닌 Status.Endpoint Statuses.Unhealthy Targets 필드가 있는 경우 수집기는 하나 이상의 대상을 스크래핑할 수 없습니다.

오류 메시지별로 대상을 그룹화하는 Sample Groups 필드를 확인하고 Last Error 필드를 찾습니다. Last Error 필드는 Prometheus에서 비롯되며 대상을 스크레이핑할 수 없는 이유를 알려줍니다. 이 문제를 해결하려면 샘플 대상을 참조로 사용하여 스크래핑 엔드포인트가 실행 중인지 확인합니다.

할당량이 초과됨

다음 오류가 표시되면 Cloud Monitoring API의 수집 할당량이 초과된 것입니다.

  • '429: 'project_number:PROJECT_NUMBER' 소비자의 'monitoring.googleapis.com' 서비스에 대해 '시계열 수집 요청' 할당량 측정항목 및 '분당 시계열 수집 요청' 한도에 대한 할당량이 초과되었습니다. rateLimitExceeded'

이 오류는 일반적으로 관리형 서비스를 처음 설정할 때 표시됩니다. 기본 할당량은 초당 100,000개 샘플이 수집될 때 소진됩니다.

이 문제를 해결하려면 Monitoring API에 대해 수집 할당량을 늘리도록 요청을 제출하세요. 도움이 필요하면 Google Cloud 지원팀에 문의하세요. 할당량에 대한 자세한 내용은 할당량 작업을 참조하세요.

노드의 기본 서비스 계정에 대한 권한 누락

다음 오류 중 하나가 표시되면 노드의 기본 서비스 계정에 권한이 누락되었을 수 있습니다.

  • '쿼리 실행: Prometheus 쿼리 중 오류 발생: client_error: 클라이언트 오류: 403'
  • '준비 프로브 실패: HTTP 프로브 오류 상태 코드: 503'
  • 'Prometheus 인스턴스 쿼리 오류'

관리형 컬렉션 및 Prometheus용 관리형 서비스의 관리되는 규칙 평가자 모두 노드에서 기본 서비스 계정을 사용합니다. 이 계정은 모든 필수 권한이 포함된 상태로 생성되지만 고객이 Monitoring 권한을 수동으로 삭제할 수도 있습니다. 이렇게 하면 컬렉션 및 규칙 평가가 실패할 수 있습니다.

서비스 계정의 권한을 확인하려면 다음 중 하나를 수행합니다.

  • 기본 Compute Engine 노드 이름을 식별한 후 다음 명령어를 실행합니다.

    gcloud compute instances describe NODE_NAME --format="json" | jq .serviceAccounts

    https://www.googleapis.com/auth/monitoring 문자열을 찾습니다. 필요한 경우 잘못 구성된 서비스 계정에 설명된 대로 Monitoring을 추가합니다.

  • 클러스터의 기본 VM으로 이동하고 노드 서비스 계정의 구성을 확인합니다.

    1. Google Cloud 콘솔의 탐색 패널에서 Kubernetes Engine을 선택한 후 클러스터를 선택합니다.

      Kubernetes 클러스터로 이동

    2. 노드를 선택한 후 노드 테이블에서 노드 이름을 클릭합니다.

    3. 세부정보를 클릭합니다.

    4. VM 인스턴스 링크를 클릭합니다.

    5. API 및 ID 관리 창을 찾고 세부정보 표시를 클릭합니다.

    6. 전체 액세스 권한이 있는 Stackdriver Monitoring API를 찾습니다.

또한 데이터 소스 동기화 또는 Prometheus UI가 잘못된 프로젝트를 조회하도록 구성되었을 수 있습니다. 의도한 대로 측정항목 범위가 쿼리되는지 확인하기 위해서는 쿼리되는 프로젝트 변경을 참조하세요.

잘못 구성된 서비스 계정

다음 오류 메시지 중 하나가 표시되면 수집기에 사용된 서비스 계정에 올바른 권한이 없는 것입니다.

  • '코드 = PermissionDenied 설명 = 권한 monitoring.timeSeries.create 거부됨(또는 리소스 존재 안함)'
  • 'google: 기본 사용자 인증 정보를 찾을 수 없습니다. 자세한 내용은 https://developers.google.com/accounts/docs/application-default-credentials를 참조하세요.'

서비스 계정에 올바른 권한이 있는 확인하려면 다음을 수행합니다.

  1. Google Cloud 콘솔의 탐색 패널에서 IAM을 선택합니다.

    IAM으로 이동

  2. 주 구성원 목록에서 서비스 계정 이름을 식별합니다. 서비스 계정 이름의 철자가 올바른지 확인합니다. 그런 후 수정을 클릭합니다.

  3. 역할 필드를 선택한 후 현재 사용 중을 클릭하고 모니터링 측정항목 작성자 또는 모니터링 편집자 역할을 검색합니다. 서비스 계정에 이러한 역할이 없으면 서비스 계정에 모니터링 측정항목 작성자(roles/monitoring.metricWriter) 역할을 부여합니다.

비GKE Kubernetes에서 실행하는 경우 사용자 인증 정보를 수집기 및 규칙 평가자 모두에 명시적으로 전달해야 합니다. rules 및 collection 섹션 모두에서 사용자 인증 정보를 반복해야 합니다. 자세한 내용은 명시적으로 사용자 인증 정보 제공(컬렉션) 또는 명시적으로 사용자 인증 정보 제공(규칙)을 참조하세요.

서비스 계정은 범위가 단일 Google Cloud 프로젝트로 지정되는 경우가 많습니다. 하나의 관리되는 규칙 평가자가 여러 프로젝트 측정항목 범위를 쿼리할 때와 같이 하나의 서비스 계정을 사용해서 여러 프로젝트에 대해 측정항목 데이터를 기록하려고 하면 이 권한 오류가 발생할 수 있습니다. 기본 서비스 계정을 사용하는 경우 여러 프로젝트에 대해 monitoring.timeSeries.create 권한을 안전하게 추가할 수 있도록 전용 서비스 계정을 구성하는 것이 좋습니다. 이 권한을 부여할 수 없으면 측정항목 라벨 재지정을 사용해서 project_id 라벨을 다른 이름으로 다시 작성할 수 있습니다. 그런 후 프로젝트 ID가 기본적으로 Prometheus 서버 또는 규칙 평가자가 실행되는 Google Cloud 프로젝트로 지정됩니다.

잘못된 스크레이핑 구성

다음 오류가 표시되면 PodMonitoring 또는 ClusterPodMonitoring의 형식이 잘못 지정된 것입니다.

  • "Internal error occurred: failed calling webhook "validate.podmonitorings.gmp-operator.gmp-system.monitoring.googleapis.com": Post "https://gmp-operator.gmp-system.svc:443/validate/monitoring.googleapis.com/v1/podmonitorings?timeout=10s": EOF""

이 오류를 해결하려면 커스텀 리소스의 형식을 사양에 맞게 제대로 지정해야 합니다.

스크래핑 간격 및 시간 제한 문제

Prometheus용 관리형 서비스를 사용하는 경우에는 스크래핑 제한 시간이 스크래핑 간격보다 클 수 없습니다. 로그에서 이 문제를 확인하려면 다음 명령어를 실행합니다.

kubectl -n gmp-system logs ds/collector prometheus

GKE Autopilot 클러스터에서 다음 명령어를 실행합니다.

kubectl -n gke-gmp-system logs ds/collector prometheus

다음 메시지를 찾아봅니다.

  • '작업 이름이 'PodMonitoring/gmp-system/example-app/go-metrics'인 스크래핑 구성에서 스크래핑 제한 시간이 스크래핑 간격보다 큼'

이 문제를 해결하려면 스크래핑 간격의 값을 스크래핑 제한 시간의 값보다 크거나 같게 설정합니다.

측정항목에서 TYPE 누락

다음 오류가 표시되면 측정항목에 유형 정보가 누락된 것입니다.

  • '측정항목 이름 '{metric_name}'의 메타데이터를 찾을 수 없음'

누락된 유형 정보가 문제인지 확인하려면 내보내기 애플리케이션의 /metrics 출력을 확인합니다. 다음과 같은 줄이 없으면 유형 정보가 누락된 것입니다.

# TYPE {metric_name} <type>

버전 1.28.0 이전 VictoriaMetrics의 라이브러리와 같은 특정 라이브러리는 유형 정보를 의도적으로 삭제합니다. 이러한 라이브러리는 Prometheus용 관리형 서비스에서 지원되지 않습니다.

시계열 충돌

다음 오류 중 하나가 표시되면 수집기 중 하나 이상이 동일한 시계열에 쓰기를 시도할 수 있습니다.

  • '하나 이상의 시계열을 기록할 수 없음: 하나 이상의 포인트가 측정항목에 구성된 최대 샘플링 기간보다 더 자주 기록되었습니다.'
  • '하나 이상의 시계열을 기록할 수 없음: 포인트를 순서대로 기록해야 합니다. 지정된 포인트 중 하나 이상이 최근 포인트보다 오래된 종료 시간을 갖습니다.'

가장 일반적인 원인과 해결 방법은 다음과 같습니다.

  • 고가용성 쌍을 사용합니다. Prometheus용 관리형 서비스는 기존의 고가용성 컬렉션을 지원하지 않습니다. 이 구성을 사용하면 데이터를 동일한 시계열에 기록하려고 시도해서 이 오류를 일으키는 여러 수집기가 생성될 수 있습니다.

    이 문제를 해결하려면 복제본 수를 1로 줄여서 중복 수집기를 사용 중지하거나 지원되는 고가용성 메서드를 사용합니다.

  • 라벨링 규칙, 특히 작업 또는 인스턴스에서 작동하는 규칙을 사용합니다. Prometheus용 관리형 서비스는 {project_id, location, cluster, namespace, job, instance} 라벨을 조합해서 고유한 시계열을 부분적으로 식별합니다. 이러한 라벨, 특히 job 및 instance 라벨을 삭제하도록 라벨 재지정 규칙을 사용하면 충돌이 자주 발생할 수 있습니다. 이러한 라벨을 다시 작성하는 것은 권장되지 않습니다.

    문제를 해결하려면 원인이 되는 규칙을 삭제합니다. 이 규칙은 종종 labeldrop 작업을 사용하는 metricRelabeling 규칙에 의해 수행될 수 있습니다. 모든 라벨 재지정 규칙을 주석 처리하고 오류가 다시 발생할 때까지 한 번에 하나씩 복구하는 방식으로 문제가 되는 규칙을 식별할 수 있습니다.

시계열 충돌을 일으키는 덜 일반적인 원인은 5초 미만의 스크래핑 간격을 사용하는 것입니다. Managed Service for Prometheus에서 지원되는 최소 스크래핑 간격은 5초입니다.

라벨 수 한도 초과

다음 오류가 표시되는 경우 측정항목 중 하나에 너무 많은 라벨이 정의되어 있을 수 있습니다.

  • '하나 이상의 시계열을 기록할 수 없음: 새 라벨로 인해 prometheus.googleapis.com/METRIC_NAME 측정항목에서 PER_PROJECT_LIMIT 라벨이 초과됩니다.'

이 오류는 일반적으로 한 측정항목 이름에 측정항목의 전체 기간 동안 독립적인 라벨 키 집합 여러 개가 효과적으로 포함되도록 측정항목 정의를 빠르게 변경할 때 발생합니다. Cloud Monitoring은 측정항목마다 라벨 수를 제한합니다. 자세한 내용은 사용자 정의 측정항목 한도를 참조하세요.

이 문제를 해결하려면 다음 3단계를 수행합니다.

  1. 특정 측정항목에 라벨이 너무 많거나 자주 변경되는 이유를 확인합니다.

  2. PodMonitoring의 라벨 재지정 규칙 조정, 내보내기 도구 변경 또는 계측 문제 해결과 같은 문제의 원인을 해결합니다.

  3. 더 작고 안정적인 라벨 집합을 사용하여 측정항목을 다시 만들 수 있도록 데이터가 손실될 측정항목의 측정항목 설명을 삭제합니다. 이렇게 하려면 metricDescriptors.delete 메서드를 사용하면 됩니다.

문제의 가장 일반적인 원인은 다음과 같습니다.

  • 측정항목에 동적 라벨을 연결하는 내보내기 도구 또는 애플리케이션에서 측정항목 수집. 예를 들어 추가 컨테이너 라벨 및 환경 변수나 동적 주석을 삽입하는 DataDog 에이전트를 통해 자체 배포된 cAdvisor입니다.

    이 문제를 해결하려면 PodMonitoring의 metricRelabeling 섹션을 사용하여 라벨을 유지하거나 삭제하면 됩니다. 일부 애플리케이션 및 내보내기 도구는 내보낸 측정항목을 변경하는 구성도 허용합니다. 예를 들어 cAdvisor에는 라벨을 동적으로 추가할 수 있는 여러 고급 런타임 설정이 있습니다. 관리형 컬렉션을 사용할 때는 기본 제공 자동 kubelet 컬렉션을 사용하는 것이 좋습니다.

  • 라벨링 규칙, 특히 라벨 이름을 동적으로 연결하는 규칙을 사용하면 라벨 수에서 예상치 못한 문제가 발생할 수 있습니다.

    문제를 해결하려면 원인이 되는 규칙 항목을 삭제합니다.

측정항목 및 라벨 생성 및 업데이트에 대한 비율 제한

다음 오류가 표시되면 새 측정항목 만들기 및 기존 측정항목에 새 측정항목 라벨 추가에 대한 분당 비율 제한에 도달한 것입니다.

  • '요청이 제한되었습니다. 측정항목 정의 또는 라벨 정의 분당 변경사항에 대한 프로젝트별 한도에 도달했습니다.'

일반적으로는 자체 배포된 컬렉션을 사용하도록 기존 Prometheus 배포를 마이그레이션할 때와 같이 Managed Service for Prometheus를 처음 통합할 때만 이러한 비율 제한에 도달합니다. 이것은 데이터 포인트 수집에 대한 비율 제한이 아닙니다. 이 비율 제한은 이전에 없던 측정항목을 만들거나 기존 측정항목에 새 라벨을 추가할 때에만 적용됩니다.

이 할당량은 고정되어 있지만 분당 최대 한도까지 새 측정항목 및 측정항목 라벨이 생성됨에 따라 문제가 자동으로 해결됩니다.

측정항목 설명 수 제한

다음 오류가 표시되면 단일 Google Cloud 프로젝트 내에서 측정항목 설명 수의 할당량 한도에 도달한 것입니다.

  • "측정항목 설명 할당량이 소진되었습니다."

기본적으로 이 한도는 25,000으로 설정됩니다. 측정항목이 잘 구성된 경우 요청에 따라 이 할당량을 늘릴 수 있지만 이 한도에 도달하는 이유는 일반적으로 잘못된 형식의 측정항목 이름이 시스템에 수집되기 때문입니다.

Prometheus에는 측정기준 데이터 모델이 있습니다. 여기에서 클러스터 또는 네임스페이스 이름과 같은 정보는 라벨 값으로 인코딩됩니다. 측정기준 정보가 측정항목 이름 자체에 대신 임베딩되면 측정항목 설명 수가 무한정 늘어납니다. 또한 이 시나리오에서는 라벨이 올바르게 사용되지 않기 때문에 클러스터, 네임스페이스, 서비스 간에 데이터를 쿼리하고 집계하는 것이 훨씬 더 어렵습니다.

Cloud Monitoring 또는 Managed Service for Prometheus는 StatsD 또는 Graphite에 사용되는 측정항목과 같이 측정기준에 연결되지 않은 측정항목을 지원하지 않습니다. 대부분의 Prometheus 내보내기 도구는 처음부터 올바르게 구성되지만 StatsD 내보내기 도구, Vault 내보내기 도구, Istio에 제공되는 Envoy Proxy와 같은 특정 내보내기 도구는 측정항목 이름에 정보를 임베딩하는 대신 라벨을 사용하도록 명시적으로 구성되어야 합니다. 잘못된 형식의 측정항목 이름 예시는 다음과 같습니다.

  • request_path_____path_to_a_resource____istio_request_duration_milliseconds
  • envoy_cluster_grpc_method_name_failure
  • envoy_cluster_clustername_upstream_cx_connect_ms_bucket
  • vault_rollback_attempt_path_name_1700683024
  • service__________________________________________latency_bucket

이 문제를 해결하려면 다음을 수행합니다.

  1. Google Cloud 콘솔 내에서 오류와 연결된 Google Cloud 프로젝트를 선택합니다.

  2. Google Cloud 콘솔의 탐색 패널에서 Monitoring을 선택한 후 측정항목 관리를 선택합니다.

    측정항목 관리로 이동

  3. 활성 측정항목과 비활성 측정항목의 합계가 25,000을 넘는지 확인합니다. 대부분의 경우 비활성 측정항목 수가 많게 표시됩니다.
  4. 청구 가능한 볼륨 샘플을 오름차순으로 정렬하고, 목록을 훑어보면서 패턴을 찾습니다.

또는 측정항목 탐색기를 사용해서 이 문제를 확인할 수 있습니다.

  1. Google Cloud 콘솔 내에서 오류와 연결된 Google Cloud 프로젝트를 선택합니다.

  2. Google Cloud 콘솔의 탐색 패널에서 Monitoring을 선택한 후 측정항목 탐색기를 선택합니다.

    측정항목 탐색기로 이동

  3. 쿼리 빌더에서 측정항목을 선택한 후 "활성" 체크박스를 선택 취소합니다.
  4. 검색창에 "prometheus"를 입력합니다.
  5. 측정항목 이름에서 패턴을 찾습니다.

잘못된 형식의 측정항목을 나타내는 패턴이 확인되었으면 소스에서 내보내기 도구를 수정한 후 잘못된 측정항목 설명을 삭제하여 문제를 해결할 수 있습니다.

이 문제가 다시 발생하지 않도록 방지하려면 잘못된 형식의 측정항목을 더 이상 내보내지 않도록 관련 내보내기 도구를 구성해야 합니다. 도움이 필요하면 내보내기 도구에 대한 문서를 참조하세요. /metrics 엔드포인트를 직접 방문하고 내보낸 측정항목 이름을 조사하여 문제가 해결되었는지 확인할 수 있습니다.

그런 후 projects.metricDescriptors.delete 메서드를 사용해서 잘못된 형식의 측정항목을 삭제하여 할당량을 비울 수 있습니다. 잘못된 형식의 측정항목 목록을 더 쉽게 반복할 수 있게 하려면 사용할 수 있는 Golang 스크립트를 제공합니다. 이 스크립트에는 잘못된 형식의 측정항목을 식별하고 패턴과 일치하는 측정항목 설명을 삭제할 수 있는 정규 표현식을 사용할 수 있습니다. 측정항목 삭제는 되돌릴 수 없으므로, 먼저 테스트 실행 모드를 사용해서 스크립트를 실행하는 것이 좋습니다.

오류 및 측정항목 없음

관리형 컬렉션을 사용하고 있고 오류가 표시되지 않지만 데이터가 Cloud Monitoring에 표시되지 않는 경우 이는 측정항목 내보내기 또는 스크레이핑 구성이 올바르게 구성되지 않았기 때문일 수 있습니다. 먼저 올바른 스크래핑 구성을 적용하지 않으면 Prometheus용 관리형 서비스가 시계열 데이터를 전송하지 않습니다.

이것이 원인인지 확인하려면 예시 애플리케이션 및 예시 PodMonitoring 리소스 배포를 시도해보세요. 이제 up 측정항목이 표시되면(몇 분 정도 걸릴 수 있음) 스크래핑 구성 또는 내보내기 도구가 문제입니다.

근본 원인은 여러 가지일 수 있습니다. 다음을 확인하는 것이 좋습니다.

  • PodMonitoring이 올바른 포트를 참조합니다.

  • 내보내기 도구의 배포 사양에 올바르게 이름 지정된 포트가 포함됩니다.

  • 선택기(일반적으로 app)가 배포 및 PodMonitoring 리소스에서 일치합니다.

  • 예상 엔드포인트 및 포트로 수동으로 이동해서 데이터를 볼 수 있습니다.

  • 스크래핑할 애플리케이션과 동일한 네임스페이스에 PodMonitoring 리소스를 설치했습니다. gmp-system 또는 gke-gmp-system 네임스페이스에 어떠한 커스텀 리소스나 애플리케이션도 설치하지 마세요.

  • 측정항목 및 라벨 이름은 Prometheus 정규 표현식 검증과 일치합니다. Prometheus용 관리형 서비스는 _ 문자로 시작하는 라벨 이름을 지원하지 않습니다.

  • 모든 데이터가 필터링되는 필터 집합을 사용하고 있지 않습니다. OperatorConfig 리소스에서 collection 필터를 사용할 때 충돌하는 필터가 없는지 주의하여 확인하세요.

  • Google Cloud 외부에서 실행 중인 경우 project 또는 project-id는 유효한 Google Cloud 프로젝트로 설정되고 location은 유효한 Google Cloud 리전으로 설정됩니다. global을 location 값으로 사용할 수 없습니다.

  • 측정항목은 4가지 Prometheus 측정항목 유형 중 하나입니다. Kube State Metrics와 같은 일부 라이브러리는 Info, Stateset, GaugeHistogram과 같은 OpenMetrics 측정항목 유형을 노출하지만 이러한 측정항목 유형은 Prometheus용 관리형 서비스에서 지원되지 않으며 자동으로 삭제됩니다.

내보내기 도구에서 수집 시 발생하는 문제

내보내기 도구의 측정항목이 수집되지 않는 경우 다음을 확인하세요.

  • kubectl port-forward 명령어를 사용하여 내보내기 도구가 작동하고 측정항목을 내보내는지 확인합니다.

    예를 들어 네임스페이스 test에서 선택기 app.kubernetes.io/name=redis가 있는 포드가 포트 9121의 /metrics 엔드포인트에서 측정항목을 내보내고 있는지 확인하려면 다음과 같이 포트를 전달하면 됩니다.

    kubectl port-forward "$(kubectl get pods -l app.kubernetes.io/name=redis -n test -o jsonpath='{.items[0].metadata.name}')" 9121

    다른 터미널 세션에서 브라우저 또는 curl을 사용하여 엔드포인트 localhost:9121/metrics에 액세스하여 내보내기 도구가 스크래핑할 측정항목을 노출하고 있는지 확인합니다.

  • 측정항목을 Google Cloud 콘솔에서 쿼리할 수 있지만 Grafana에서는 쿼리할 수 없는지 확인합니다. 그렇다면 측정항목 수집 문제가 아니라 Grafana에 문제가 있는 것입니다.

  • 수집기가 노출하는 Prometheus 웹 인터페이스를 검사하여 관리형 수집기가 내보내기 도구를 스크래핑할 수 있는지 확인합니다.

    1. 내보내기 도구가 실행 중인 노드와 동일한 노드에서 실행 중인 관리형 수집기를 식별합니다. 예를 들어 내보내기 도구가 네임스페이스 test의 포드에서 실행 중이고 포드에 app.kubernetes.io/name=redis 라벨이 지정된 경우 다음 명령어는 동일한 노드에서 실행 중인 관리형 수집기를 식별합니다.

      kubectl get pods -l app=managed-prometheus-collector --field-selector="spec.nodeName=$(kubectl get pods -l app.kubernetes.io/name=redis -n test -o jsonpath='{.items[0].spec.nodeName}')" -n gmp-system -o jsonpath='{.items[0].metadata.name}'

    2. 관리형 수집기의 포트 19090에서 포트 전달을 설정합니다.

      kubectl port-forward POD_NAME -n gmp-system 19090

    3. localhost:19090/targets라는 URL로 이동하여 웹 인터페이스에 액세스합니다. 내보내기 도구가 대상 중 하나로 나열되는 경우 관리형 수집기가 내보내기를 성공적으로 스크래핑하는 것입니다.

방화벽

방화벽은 수집 및 쿼리 문제를 모두 일으킬 수 있습니다. 수집 및 쿼리를 위해 Monitoring API 서비스 monitoring.googleapis.com에 대한 POST 및 GET 요청을 허용하도록 방화벽을 구성해야 합니다.

동시 수정 오류

'프로젝트 구성에 대한 동시 수정이 너무 많음' 오류 메시지는 일반적으로 일시적인 현상이며 몇 분 후 해결됩니다. 일반적으로는 여러 측정항목에 영향을 주는 라벨 재지정 규칙을 삭제할 때 발생합니다. 삭제하면 프로젝트의 측정항목 설명에 대해 업데이트 큐가 형성됩니다. 큐가 처리되면 이 오류가 사라집니다.

자세한 내용은 측정항목 및 라벨 생성 및 업데이트 제한사항을 참조하세요.