Grafana를 사용하여 쿼리

Google Cloud Managed Service for Prometheus를 배포한 후 관리형 서비스에 전송된 데이터를 쿼리하고 결과를 차트 및 대시보드로 표시할 수 있습니다.

이 문서에서는 쿼리 가능한 데이터, Grafana를 사용해서 수집한 데이터를 검색하고 사용하는 방법을 결정하는 측정항목 범위에 대해 설명합니다.

Managed Service for Prometheus의 모든 쿼리 인터페이스는 Cloud Monitoring API를 사용하여 Monarch에서 데이터를 검색하도록 구성됩니다. 로컬 Prometheus 서버에서 데이터를 쿼리하는 대신 Monarch를 쿼리하면 규모에 맞게 전역 모니터링을 수행할 수 있습니다.

시작하기 전에

관리형 서비스를 아직 배포하지 않았으면 관리 컬렉션 또는 자체 배포 컬렉션을 설정합니다. PromQL을 사용하여 Cloud Monitoring 측정항목 쿼리에만 관심이 있는 경우 이 단계를 건너뛸 수 있습니다.

환경 구성

프로젝트 ID 또는 클러스터 이름을 반복해서 입력하지 않으려면 다음 구성을 수행합니다.

• 다음과 같이 명령줄 도구를 구성합니다.

  • Google Cloud 프로젝트의 ID를 참조하도록 gcloud CLI를 구성합니다.

    gcloud config set project PROJECT_ID
    

  • 클러스터를 사용하도록 kubectl CLI를 구성합니다.

    kubectl config set-cluster CLUSTER_NAME
    

  이러한 도구에 대한 자세한 내용은 다음을 참조하세요.

  • gcloud CLI 개요
  • kubectl 명령어

네임스페이스 설정

예시 애플리케이션의 일부로 만드는 리소스에 대해 NAMESPACE_NAME Kubernetes 네임스페이스를 만듭니다.

kubectl create ns NAMESPACE_NAME

서비스 계정 사용자 인증 정보 확인

Kubernetes 클러스터에 GKE용 워크로드 아이덴티티 제휴가 사용 설정되어 있으면 이 섹션을 건너뛸 수 있습니다.

GKE에서 실행될 때 Managed Service for Prometheus는 Compute Engine 기본 서비스 계정을 기반으로 환경에서 사용자 인증 정보를 자동으로 검색합니다. 기본적으로 기본 서비스 계정에는 필요한 권한 monitoring.metricWriter 및 monitoring.viewer가 있습니다. GKE용 워크로드 아이덴티티 제휴를 사용하지 않고 이전에 기본 노드 서비스 계정에서 이러한 역할 중 하나를 삭제한 경우 계속하기 전에 누락된 권한을 다시 추가해야 합니다.

GKE에서 실행하지 않는 경우 명시적으로 사용자 인증 정보 제공을 참조하세요.

GKE용 워크로드 아이덴티티 제휴 서비스 계정 구성

Kubernetes 클러스터에 GKE용 워크로드 아이덴티티 제휴가 사용 설정되어 있지 않아도 이 섹션을 건너뛸 수 있습니다.

Managed Service for Prometheus는 Cloud Monitoring API를 사용하여 측정항목 데이터를 캡처합니다. 클러스터에서 GKE용 워크로드 아이덴티티 제휴를 사용하는 경우 Kubernetes 서비스 계정에 Monitoring API에 대한 권한을 부여해야 합니다. 이 섹션에서는 다음을 설명합니다.

• 전용 Google Cloud 서비스 계정, gmp-test-sa를 만듭니다.
• 테스트 네임스페이스 NAMESPACE_NAME에서 Google Cloud 서비스 계정을 기본 Kubernetes 서비스 계정에 바인딩합니다.
• Google Cloud 서비스 계정에 필요한 권한을 부여합니다.

서비스 계정 만들기 및 바인딩

이 단계는 Managed Service for Prometheus 문서의 여러 위치에 표시됩니다. 이미 이전 태스크를 수행하는 동안 이 단계를 수행했으면 이를 반복할 필요가 없습니다. 서비스 계정 승인으로 건너뛰세요.

다음 명령어 시퀀스는 gmp-test-sa 서비스 계정을 만들고 NAMESPACE_NAME 네임스페이스의 기본 Kubernetes 서비스 계정에 바인딩합니다.

gcloud config set project PROJECT_ID \
&&
gcloud iam service-accounts create gmp-test-sa \
&&
gcloud iam service-accounts add-iam-policy-binding \
  --role roles/iam.workloadIdentityUser \
  --member "serviceAccount:PROJECT_ID.svc.id.goog[NAMESPACE_NAME/default]" \
  gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com \
&&
kubectl annotate serviceaccount \
  --namespace NAMESPACE_NAME \
  default \
  iam.gke.io/gcp-service-account=gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com

다른 GKE 네임스페이스 또는 서비스 계정을 사용하는 경우 적절하게 명령어를 조정합니다.

서비스 계정 승인

관련 권한 그룹이 역할에 수집되고 주 구성원(이 예시에서는 Google Cloud 서비스 계정)에 역할을 부여합니다. Monitoring 역할에 대한 자세한 내용은 액세스 제어를 참조하세요.

다음 명령어는 Google Cloud 서비스 계정 gmp-test-sa에 측정항목 데이터 읽기에 필요한 Monitoring API 역할을 부여합니다.

이미 이전 태스크를 수행하는 동안 Google Cloud 서비스 계정에 특정 역할을 부여한 경우 이를 다시 수행할 필요가 없습니다.

gcloud projects add-iam-policy-binding PROJECT_ID \
  --member=serviceAccount:gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com \
  --role=roles/monitoring.viewer \
&& \
gcloud projects add-iam-policy-binding PROJECT_ID \
  --member=serviceAccount:gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com \
  --role=roles/iam.serviceAccountTokenCreator

GKE용 워크로드 아이덴티티 제휴 구성 디버그

GKE용 워크로드 아이덴티티 제휴가 작동하지 않는 경우 GKE용 워크로드 아이덴티티 제휴 설정 확인 문서와 GKE용 워크로드 아이덴티티 제휴 문제 해결 가이드를 참조하세요.

GKE용 워크로드 아이덴티티 제휴를 구성할 때 오타 및 부분 복사-붙여넣기가 가장 일반적인 오류 소스이므로 이 안내의 코드 샘플에 삽입된 수정 가능한 변수 및 클릭 가능한 복사-붙여넣기 아이콘을 사용하는 것이 좋습니다.

프로덕션 환경의 GKE용 워크로드 아이덴티티 제휴

이 문서에 설명된 예시에서는 Google Cloud 서비스 계정을 기본 Kubernetes 서비스 계정에 바인딩하고 Google Cloud 서비스 계정에 Monitoring API를 사용하기 위해 필요한 모든 권한을 부여합니다.

프로덕션 환경에서는 각 구성요소에 대해 서비스 계정이 있고, 각각 최소 권한이 포함된 세분화된 방법을 사용해야 할 수 있습니다. 워크로드 아이덴티티 관리를 위한 서비스 계정 구성에 대한 자세한 내용은 GKE용 워크로드 아이덴티티 제휴 사용을 참조하세요.

쿼리 및 측정항목 범위

쿼리 가능한 데이터는 데이터 쿼리에 사용되는 방법에 관계없이 Cloud Monitoring 구문 측정항목 범위에 따라 결정됩니다. 예를 들어 Grafana를 사용하여 Managed Service for Prometheus 데이터를 쿼리할 경우 각 측정항목 범위를 개별 데이터 소스로 구성해야 합니다.

Monitoring 측정항목 범위는 여러 Google Cloud 프로젝트에 속하는 측정항목 데이터를 쿼리할 수 있게 해주는 읽기 전용 구문입니다. 모든 측정항목 범위는 범위 지정 프로젝트라고 부르는 지정된 Google Cloud 프로젝트에서 호스팅됩니다.

기본적으로 프로젝트는 자체 측정항목 범위에 대한 범위 지정 프로젝트이고, 측정항목 범위에는 해당 프로젝트에 대한 측정항목 및 구성이 포함되어 있습니다. 범위 지정 프로젝트는 측정항목 범위에 모니터링 프로젝트를 두 개 이상 가질 수 있으며 측정항목 범위에 있는 모든 모니터링 프로젝트의 측정항목과 구성은 범위 지정 프로젝트에 표시됩니다. 또한 모니터링 프로젝트는 측정항목 범위 두 개 이상에 포함될 수 있습니다.

범위 지정 프로젝트에서 측정항목을 쿼리하고 해당 범위 지정 프로젝트가 멀티 프로젝트 측정항목 범위를 호스팅하는 여러 프로젝트에서 데이터를 검색할 수 있습니다. 측정항목 범위에 모든 프로젝트가 포함되면 쿼리와 규칙이 전역적으로 평가됩니다.

범위 지정 프로젝트 및 측정항목 범위에 대한 자세한 내용은 측정항목 범위를 참조하세요. 다중 프로젝트 측정항목 범위 구성에 대한 자세한 내용은 다중 프로젝트의 측정항목 보기를 참조하세요.

Cloud Monitoring의 Managed Service for Prometheus 데이터

Prometheus 데이터 내보내기가 수행되는지 확인하는 가장 간단한 방법은 PromQL을 지원하는 Google Cloud 콘솔에서 Cloud Monitoring 측정항목 탐색기 페이지를 사용하는 것입니다. 자세한 내용은 Cloud Monitoring에서 PromQL을 사용하여 쿼리를 참조하세요.

또한 Grafana 대시보드를 Cloud Monitoring에 가져올 수 있습니다. 이렇게 하면 Grafana 인스턴스를 구성하거나 배포할 필요 없이 커뮤니티에서 만든 대시보드 또는 개인 Grafana 대시보드를 계속 사용할 수 있습니다.

Grafana

Managed Service for Prometheus는 Grafana용으로 기본 제공되는 Prometheus 데이터 소스를 사용하므로 커뮤니티에서 만든 대시보드나 개인 Grafana 대시보드를 변경 없이 계속 사용할 수 있습니다.

필요한 경우 Grafana 배포

클러스터에 실행 중인 Grafana 배포가 없으면 임시 테스트 배포를 만들어 실험해볼 수 있습니다.

임시 Grafana 배포를 만들려면 Managed Service for Prometheus grafana.yaml 매니페스트를 클러스터에 적용하고 grafana 서비스를 로컬 머신에 포트 전달합니다. CORS 제한으로 인해 Cloud Shell을 사용하여 Grafana 배포에 액세스할 수 없습니다.

1. grafana.yaml 매니페스트를 적용합니다.

   kubectl -n NAMESPACE_NAME apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/prometheus-engine/v0.13.0/examples/grafana.yaml
   

2. grafana 서비스를 로컬 머신으로 포트 전달합니다. 이 예시에서는 서비스를 포트 3000으로 전달합니다.

   kubectl -n NAMESPACE_NAME port-forward svc/grafana 3000
   

   이 명령어는 결과를 반환하지 않고, 실행되는 동안 URL에 대한 액세스를 보고합니다.

   사용자 이름:암호 admin:admin를 사용하여 URL http://localhost:3000의 브라우저에서 Grafana에 액세스할 수 있습니다.

그런 후 다음을 수행하여 새 Prometheus 데이터 소스를 Grafana에 추가합니다.

1. 예를 들어 URL http://localhost:3000을 사용해서 Grafana 배포로 이동하여 Grafana 시작 페이지에 연결합니다.

2. 기본 Grafana 메뉴에서 연결을 선택한 후 데이터 소스를 선택합니다.

   

3. 데이터 소스 추가를 선택하고 시계열 데이터베이스로 Prometheus를 선택합니다.

   

4. 데이터 소스의 이름을 지정하고 URL 필드를 http://localhost:9090으로 설정한 다음 저장 및 테스트를 선택합니다. 데이터 소스가 올바르게 구성되지 않았음을 알리는 오류는 무시해도 됩니다.

5. 배포의 로컬 서비스 URL을 아래에 복사합니다. 이 URL은 다음과 같습니다.

   http://grafana.NAMESPACE_NAME.svc:3000
   

Grafana 데이터 소스 구성 및 인증

Google Cloud API는 모두 OAuth2를 사용하여 인증해야 합니다. 하지만 Grafana는 Prometheus 데이터 소스와 함께 사용되는 서비스 계정에 대한 OAuth2 인증을 지원하지 않습니다. Managed Service for Prometheus와 함께 Grafana를 사용하려면 데이터 소스 동기화를 사용해 서비스 계정에 대한 OAuth2 사용자 인증 정보를 생성한 후 Grafana 데이터 소스 API를 통해 Grafana와 동기화합니다.

데이터 소스 동기화를 사용하여 전역적으로 데이터를 쿼리하도록 Grafana를 구성하고 승인해야 합니다. 이러한 단계를 따르지 않으면 Grafana는 로컬 Prometheus 서버의 데이터에 대해서만 쿼리를 실행합니다.

데이터 소스 동기화는 크론 작업을 사용하여 지정된 Grafana Prometheus 데이터 소스에 구성 값을 원격으로 동기화하는 명령줄 인터페이스 도구입니다. 이를 통해 Grafana 데이터 소스가 다음과 같이 올바르게 구성됩니다.

• OAuth2 액세스 토큰을 주기적으로 새로고침하여 인증 수행
• Prometheus 서버 URL로 설정된 Cloud Monitoring API
• GET으로 설정된 HTTP 메서드
• 최소 2.40.x로 설정된 Prometheus 유형 및 버전
• 2분으로 설정된 HTTP 및 쿼리 제한 시간 값

데이터 소스 동기화는 Google Cloud 서비스 계정을 사용하여 Cloud Monitoring 데이터를 쿼리하는 데 필요한 IAM 권한이 있는 Google Cloud API 액세스 토큰을 주기적으로 생성합니다. Google Cloud API 액세스 토큰의 수명은 1시간이므로 데이터 소스 동기화는 30분마다 실행되어 Grafana와 Cloud Monitoring API 간에 중단 없이 인증된 연결을 유지합니다.

데이터 소스 동기화를 실행하려면 Kubernetes CronJob을 사용하거나 완전한 서버리스 환경을 위해 Cloud Run 및 Cloud Scheduler를 사용하도록 선택할 수 있습니다. 오픈소스 Grafana 또는 Grafana Enterprise와 같이 로컬에 Grafana를 배포하는 경우 Grafana가 실행되는 동일한 클러스터에서 데이터 소스 동기화 도구를 실행하는 것이 좋습니다. Grafana Cloud를 사용하는 경우 완전히 서버리스 옵션을 선택하는 것이 좋습니다.

Grafana를 사용하여 쿼리 실행

이제 Grafana 대시보드를 만들고 구성된 데이터 소스를 사용하여 쿼리를 실행할 수 있습니다. 다음 스크린샷은 up 측정항목을 표시하는 Grafana 차트를 보여줍니다.

PromQL을 사용하여 Google Cloud 시스템 측정항목을 쿼리하는 방법에 대한 자세한 내용은 Cloud Monitoring 측정항목용 PromQL을 참조하세요.

GKE 외부에서 데이터 소스 동기화 실행

Google Kubernetes Engine 클러스터에서 데이터 소스 동기화 도구를 실행 중이거나 서버리스 옵션을 사용하는 경우 이 섹션을 건너뛸 수 있습니다. GKE에 인증 문제가 있으면 서비스 계정 사용자 인증 정보 확인을 참조하세요.

GKE에서 실행할 때 데이터 소스 동기화는 노드의 서비스 계정이나 GKE용 워크로드 아이덴티티 제휴 설정에 따라 환경에서 사용자 인증 정보를 자동으로 검색합니다. 비GKE Kubernetes 클러스터에서는 GOOGLE_APPLICATION_CREDENTIALS 환경 변수를 사용하여 데이터 소스 동기화에 사용자 인증 정보를 명시적으로 제공해야 합니다.

1. 컨텍스트를 대상 프로젝트에 설정합니다.

   gcloud config set project PROJECT_ID
   

2. 서비스 계정을 만듭니다.

   gcloud iam service-accounts create gmp-test-sa
   

   이 단계에서는 GKE용 워크로드 아이덴티티 제휴 안내에 따라 이미 생성되었을 수 있는 서비스 계정을 만듭니다.

3. 서비스 계정에 필요한 권한을 부여합니다.

   gcloud projects add-iam-policy-binding PROJECT_ID \
     --member=serviceAccount:gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com \
     --role=roles/monitoring.viewer \
   && \
   gcloud projects add-iam-policy-binding PROJECT_ID \
     --member=serviceAccount:gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com \
     --role=roles/iam.serviceAccountTokenCreator
   

4. 서비스 계정에 대해 키를 만들고 다운로드합니다.

   gcloud iam service-accounts keys create gmp-test-sa-key.json \
     --iam-account=gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com
   

5. GOOGLE_APPLICATION_CREDENTIALS 환경 변수를 사용하여 키-파일 경로를 설정합니다.

데이터 소스 동기화가 다중 프로젝트 모니터링을 가져오도록 승인

Prometheus용 관리형 서비스는 측정항목 범위를 사용하여 다중 프로젝트 모니터링을 지원합니다.

서버리스 옵션을 사용하는 경우 선택한 프로젝트가 다중 프로젝트 측정항목 범위의 범위 지정 프로젝트인 경우 다중 프로젝트 쿼리가 제공됩니다.

Kubernetes에 데이터 소스 동기화 도구를 배포하는 경우 로컬 프로젝트가 범위 지정 프로젝트이고 로컬 프로젝트에 대한 서비스 계정 확인 또는 구성 안내를 따랐다면 추가 구성 없이도 다중 프로젝트 쿼리가 작동합니다.

로컬 프로젝트가 범위 지정 프로젝트가 아닌 경우, 범위 지정 프로젝트에 대한 monitoring.viewer 액세스 권한을 갖기 위해 로컬 프로젝트의 기본 컴퓨팅 서비스 계정 또는 GKE용 워크로드 아이덴티티 제휴 서비스 계정을 승인해야 합니다. 그런 다음 범위 지정 프로젝트의 ID를 PROJECT_ID 환경 변수의 값으로 전달합니다.

Compute Engine default 서비스 계정을 사용하는 경우 다음 중 하나를 수행할 수 있습니다.

• 범위 지정 프로젝트에 속한 클러스터에 데이터 소스 동기화를 배포합니다.

• 클러스터에 GKE용 워크로드 아이덴티티 제휴를 사용 설정하고 구성 단계를 수행합니다.

• 명시적 서비스 계정 키를 제공합니다.

서비스 계정에 다른 Google Cloud 프로젝트에 액세스하는 데 필요한 권한을 부여하려면 다음 단계를 따르세요.

1. 쿼리하려는 대상 프로젝트에서 읽기 권한을 서비스 계정에 부여합니다.

   gcloud projects add-iam-policy-binding SCOPING_PROJECT_ID \
     --member=serviceAccount:gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com \
     --role=roles/monitoring.viewer
   

2. 데이터 소스 동기화를 구성할 때 범위 지정 프로젝트의 ID를 PROJECT_ID 환경 변수 값으로 전달합니다.

Kubernetes CronJob 검사

Kubernetes에 데이터 소스 동기화 도구를 배포하는 경우 다음 명령어를 실행하여 CronJob을 검사하고 모든 변수가 올바르게 설정되었는지 확인할 수 있습니다.

kubectl describe cronjob datasource-syncer

Grafana를 처음 구성하는 작업의 로그를 보려면 datasource-syncer.yaml 파일을 적용한 직후 다음 명령어를 실행합니다.

kubectl logs job.batch/datasource-syncer-init

해체

Kubernetes에서 데이터 소스 동기화 Cronjob을 사용 중지하려면 다음 명령어를 실행합니다.

kubectl delete -f https://raw.githubusercontent.com/GoogleCloudPlatform/prometheus-engine/main/cmd/datasource-syncer/datasource-syncer.yaml

데이터 소스 동기화를 사용 중지하면 새로운 사용자 인증 정보로 연결된 Grafana 업데이트가 중지되므로 Managed Service for Prometheus 쿼리가 더 이상 작동하지 않습니다.

API 호환성

다음 Prometheus HTTP API 엔드포인트는 https://monitoring.googleapis.com/v1/projects/PROJECT_ID/location/global/prometheus/api/v1/ 프리픽스가 포함된 URL로 Managed Service for Prometheus에서 지원됩니다.

자세한 내용은 Cloud Monitoring API 참조 문서를 확인하세요. Cloud Monitoring 언어별 클라이언트 라이브러리에서는 Promethus HTTP 엔드포인트를 사용할 수 없습니다.

PromQL 호환성에 대한 자세한 내용은 PromQL 지원을 참조하세요.

• 다음 엔드포인트는 완전히 지원됩니다.

  • /api/v1/query
  • /api/v1/query_range
  • /api/v1/metadata
  • /api/v1/labels
  • /api/v1/query_exemplars

• /api/v1/label/<label_name>/values 엔드포인트는 <label_name> 값으로 사용하거나 계열 선택기를 사용하여 정확히 일치를 수행하여 __name__ 값이 제공된 경우에만 작동합니다. 예를 들어 다음 호출은 완전히 지원됩니다.

  • /api/v1/label/__name__/values
  • /api/v1/label/__name__/values?match[]={__name__=~".*metricname.*"}
  • /api/v1/label/labelname/values?match[]={__name__="metricname"}

  이 제한으로 인해 Grafana에서 label_values($label) 변수 쿼리가 실패합니다. 대신 label_values($metric, $label)을 사용할 수 있습니다. 이러한 쿼리 유형은 지정된 대시보드와 관련이 없는 측정항목에서 라벨 값을 가져올 필요가 없기 때문에 권장됩니다.

• /api/v1/series 엔드포인트는 GET에 지원되지만 POST 요청은 지원되지 않습니다. 데이터 소스 동기화 또는 프런트엔드 프록시를 사용하는 경우 이 제한이 자동으로 관리됩니다. 또한 GET 요청만 수행하도록 Grafana에서 Prometheus 데이터 소스를 구성할 수 있습니다. match[] 매개변수는 __name__ 라벨에서 정규 표현식 일치를 지원하지 않습니다.

다음 단계

• Cloud Monitoring에서 PromQL 알림 사용
• 관리 규칙 평가 설정
• 일반적으로 사용되는 내보내기 설정