이 페이지의 일부 또는 모든 정보는 S3NS의 Cloud de Confiance에 적용되지 않을 수 있습니다. 자세한 내용은 Google Cloud와의 차이점을 참조하세요.

Cloud Monitoring용 PromQL

이 문서에서는 Cloud Monitoring에서 측정항목 데이터를 읽도록 Grafana를 구성하는 방법을 설명합니다. 그런 다음 PromQL을 사용하여 데이터를 시각화하고 차트로 작성할 수 있습니다. Grafana와 Cloud Monitoring은 데이터 소스 동기화라는 프로세스를 통해 연결되어 Grafana 데이터 소스와 Cloud Monitoring 간의 통신을 지원합니다. 데이터 소스 동기화는 다음 작업을 실행합니다.

구성 값을 Grafana 데이터 소스로 전송합니다.
Cloud Monitoring에서 측정항목 데이터를 읽을 수 있는 Cloud de Confiance by S3NS 서비스 계정의 인증 사용자 인증 정보를 유지합니다.

이 문서에서는 데이터 소스 동기화 도구를 설정하는 방법을 설명하고 Cloud Monitoring에서 PromQL을 사용하는 데 필요한 정보를 제공합니다. 이 문서에서는 사용자가 이미 Grafana에 익숙하다고 가정합니다.

Grafana가 측정항목 데이터를 읽을 수 있도록 승인

이 섹션에서는 데이터 소스 동기화 도구를 사용하여 사용자 인증 정보를 생성하고 동기화하여 Cloud Monitoring과 Grafana 간에 승인을 설정하는 방법을 설명합니다.

승인을 위해 데이터 소스 동기화 도구 사용

Cloud de Confiance by S3NS API는 모두 OAuth2를 사용하여 인증해야 합니다. 하지만 Grafana는 Prometheus 데이터 소스와 함께 사용되는 서비스 계정에 대한 OAuth2 인증을 지원하지 않습니다. Cloud Monitoring과 함께 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 및 쿼리 제한 시간 값

데이터 소스 동기화 도구는 반복적으로 실행되어야 합니다. 서비스 계정 액세스 토큰의 기본 수명은 1시간이므로 데이터 소스 동기화는 10분마다 실행되어 Grafana와 Cloud Monitoring API 간에 중단 없이 인증된 연결을 유지합니다.

Grafana 데이터 소스 구성 및 인증

Grafana를 사용하여 Google Kubernetes Engine 서비스 또는 기타 환경에서 Cloud Monitoring 측정항목 데이터를 쿼리할 수 있습니다. 안내에서는 수정 가능한 변수를 사용하여 실행 가능한 명령어를 만듭니다. 코드 샘플에 삽입된 수정 가능한 변수와 클릭 가능한 복사-붙여넣기 아이콘을 사용하는 것이 좋습니다.

GKE

Kubernetes 클러스터에서 데이터 소스 동기화를 배포하고 실행하려면 다음 단계를 따르세요.

데이터 소스 동기화를 배포할 프로젝트, 클러스터, 네임스페이스를 선택합니다.
그런 다음 데이터 소스 동기화를 올바르게 구성하고 승인했는지 확인합니다.
- GKE용 워크로드 아이덴티티 제휴를 사용 중인 경우 안내에 따라 서비스 계정을 만들고 승인합니다. 데이터 소스 동기화를 실행하려는 Kubernetes 네임스페이스에 바인딩해야 합니다.
- GKE용 워크로드 아이덴티티 제휴를 사용하지 않는 경우 기본 Compute Engine 서비스 계정을 수정하지 않았는지 확인합니다.
Grafana 인스턴스의 URL을 확인합니다(예: Grafana Cloud 배포의 경우 https://yourcompanyname.grafana.net 또는 테스트 배포 YAML을 사용하여 구성된 로컬 인스턴스의 경우 http://grafana.NAMESPACE_NAME.svc:3000).

Grafana를 로컬로 배포하고 TLS를 사용하여 모든 클러스터 내 트래픽을 보호하도록 클러스터를 구성한 경우 URL에서 https://를 사용하고 지원되는 TLS 인증 옵션 중 하나를 사용하여 인증해야 합니다.
새 데이터 소스 또는 기존 데이터 소스일 수 있는 Cloud Monitoring에 사용할 Grafana Prometheus 데이터 소스를 선택한 다음 데이터 소스 UID를 찾아 기록합니다. 데이터 소스 UID는 데이터 소스를 탐색하거나 구성할 때 URL의 마지막 부분에서 찾을 수 있습니다. 예를 들면 https://yourcompanyname.grafana.net/connections/datasources/edit/GRAFANA_DATASOURCE_UID.의 경우, 전체 데이터 소스 URL를 복사하지 마세요. URL의 고유 식별자만 복사합니다.
서비스 계정을 만들고 계정에서 사용할 토큰을 생성하여 Grafana 서비스 계정을 설정합니다.
1. Grafana 탐색 사이드바에서 관리 > 사용자 및 액세스 > 서비스 계정을 클릭합니다.
2. 서비스 계정 추가를 클릭하여 서비스 계정을 만들고 이름을 지정한 후 Grafana에서 '관리자' 역할을 부여합니다. Grafana 버전에서 더 세부적인 권한을 허용하는 경우 데이터 소스 > 작성자 역할을 사용할 수 있습니다.
3. 서비스 계정 토큰 추가를 클릭합니다.
4. 토큰 만료 설정을 '만료 없음'으로 설정하고 토큰 생성을 클릭한 후 생성된 토큰을 클립보드에 복사하여 다음 단계에서 GRAFANA_SERVICE_ACCOUNT_TOKEN으로 사용합니다.

이전 단계의 결과를 사용하여 다음 환경 변수를 설정합니다.

# These values are required.
PROJECT_ID=SCOPING_PROJECT_ID # The value from Step 1.
GRAFANA_API_ENDPOINT=GRAFANA_INSTANCE_URL # The value from step 2. This is a URL.
DATASOURCE_UIDS=GRAFANA_DATASOURCE_UID # The value from step 3. This is not a URL.
GRAFANA_API_TOKEN=GRAFANA_SERVICE_ACCOUNT_TOKEN # The value from step 4.
GCM_ENDPOINT_OVERRIDE=--gcm-endpoint-override="https://monitoring.s3nsapis.fr/v1/projects/PROJECT_ID/location/global/prometheus/"

다음 명령어를 실행하여 초기화 시 데이터 소스를 새로고침한 후 10분마다 새로고침하는 CronJob을 만듭니다. GKE용 워크로드 아이덴티티 제휴를 사용하는 경우 NAMESPACE_NAME 값은 이전에 서비스 계정에 바인딩한 네임스페이스와 동일해야 합니다.

curl https://raw.githubusercontent.com/GoogleCloudPlatform/prometheus-engine/v0.15.3/cmd/datasource-syncer/datasource-syncer.yaml \
| sed 's|$DATASOURCE_UIDS|'"$DATASOURCE_UIDS"'|; s|$GRAFANA_API_ENDPOINT|'"$GRAFANA_API_ENDPOINT"'|; s|$GRAFANA_API_TOKEN|'"$GRAFANA_API_TOKEN"'|; s|$PROJECT_ID|'"$PROJECT_ID"'|;' s|$GCM_ENDPOINT_OVERRIDE|'"$GCM_ENDPOINT_OVERRIDE"'|; \
| kubectl -n NAMESPACE_NAME apply -f -

새로 구성된 Grafana 데이터 소스로 이동하여 Prometheus 서버 URL 값이 https://monitoring.s3nsapis.fr으로 시작하는지 확인합니다. 페이지를 새로 고쳐야 할 수도 있습니다. 확인되면 페이지 하단으로 이동하여 저장 및 테스트를 선택합니다. Grafana의 라벨 자동 완성이 작동하려면 이 버튼을 한 번 이상 선택해야 합니다.

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

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

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

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

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

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

전용 Cloud de Confiance by S3NS 서비스 계정, SERVICE_ACCT_NAME를 만듭니다.
테스트 네임스페이스 NAMESPACE_NAME에서 Cloud de Confiance 서비스 계정을 기본 Kubernetes 서비스 계정에 바인딩합니다.
Cloud de Confiance 서비스 계정에 필요한 권한을 부여합니다.

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

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

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

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

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

서비스 계정 승인

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

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

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

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

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

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

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

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

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

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

기타

Google Kubernetes Engine 이외의 환경에서 데이터 소스 동기화를 배포하고 실행하려면 다음 단계를 따르세요.

데이터 소스 동기화 도구에서 사용할 서비스 계정을 설정합니다.

gcloud 명령어의 기본 프로젝트를 설정합니다.
```
gcloud config set project PROJECT_ID
```
데이터 소스 동기화 도구가 사용할 서비스 계정을 만듭니다.
```
gcloud iam service-accounts create DS_SYNCER_SVCACCT_NAME
```

서비스 계정에 측정항목 데이터를 읽을 수 있는 권한을 부여합니다.

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

서비스 계정의 키를 만듭니다.
```
gcloud iam service-accounts keys create DS_SYNCER_SVCACCT_KEYFILE_NAME.json \
--iam-account DS_SYNCER_SVCACCT_NAME@PROJECT_ID.s3ns.iam.gserviceaccount.com
```
이 디렉터리의 경로는 후속 단계에서 환경 변수를 설정하는 데 사용됩니다. 경로를 가져오려면 pwd 명령어를 실행하고 값을 기록합니다.
```
pwd
DS_SYNCER_SVCACCT_KEYFILE_DIR
```

Grafana 인스턴스의 URL을 확인합니다(예: Grafana Cloud 배포의 경우 https://yourcompanyname.grafana.net 또는 로컬 테스트 인스턴스의 경우 https://localhost:3000). 이 값은 데이터 소스 동기화 도구를 실행하는 명령어에 사용됩니다.

TLS를 사용하여 모든 클러스터 내 트래픽을 보호하도록 구성된 Kubernetes 클러스터에 Grafana를 로컬로 배포하는 경우 URL에서 https://를 사용하고 다음 단계에서 지원되는 TLS 인증 옵션 중 하나를 사용하여 인증해야 합니다.
Grafana에서 Cloud Monitoring에 사용할 Prometheus 데이터 소스를 추가하고 데이터 소스의 UID를 기록합니다.
1. 연결 > 데이터 소스 > 새 데이터 소스 추가를 클릭합니다. 시계열 데이터베이스 목록에서 Prometheus를 선택합니다.
2. Prometheus 서버 URL 필드에 다음 값을 입력합니다.
```
https://monitoring.s3nsapis.fr/v1/projects/PROJECT_ID/location/global/prometheus/
```
3. 저장 및 테스트를 클릭합니다.
  
  데이터 소스 페이지의 브라우저 URL에 데이터 소스 UI가 포함되어 있습니다(예: https://yourcompanyname.grafana.net/connections/datasources/edit/GRAFANA_DATASOURCE_UID.).
4. 데이터 소스 UID를 기록합니다. 이 값은 데이터 소스 동기화 도구를 실행하는 명령어에 사용됩니다. 전체 데이터 소스 URL을 복사하지 마세요. URL의 고유 식별자만 복사합니다. 고유 식별자는 ee0z3woqjah34e와 같은 값입니다.
```
GRAFANA_DATASOURCE_UID
```
서비스 계정을 만들고 서비스 계정에서 사용할 토큰을 생성하여 Grafana 서비스 계정을 설정합니다.
1. Grafana 탐색 사이드바에서 관리 > 사용자 및 액세스 > 서비스 계정을 클릭합니다.
2. 서비스 계정 추가를 클릭하여 서비스 계정을 만들고 이름을 지정한 후 Grafana에서 '관리자' 역할을 부여합니다.
3. 서비스 계정 토큰 추가를 클릭합니다.
4. 토큰 만료 설정을 "만료 없음"으로 설정하고 토큰 생성을 클릭한 후 생성된 토큰을 다음 수정 가능한 변수에 복사합니다. 이 값은 데이터 소스 동기화 도구를 실행하는 명령어에 사용됩니다.
```
GRAFANA_SERVICE_ACCOUNT_TOKEN
```
데이터 소스 동기화를 실행합니다. Docker를 사용하여 사전 빌드된 컨테이너 이미지에서 동기화를 실행하거나 소스에서 코드를 빌드하고 수동으로 실행할 수 있습니다. 데이터 소스 동기화는 Go 애플리케이션이므로 소스에서 동기화 도구를 빌드하려면 Go가 설치되어 있어야 합니다.
Docker

컨테이너 이미지 gke.gcr.io/prometheus-engine/datasource-syncer:v0.15.3-gke.0을 사용하여 Docker에서 데이터 소스 동기화 도구를 실행합니다. 테스트를 위해 동기화 도구를 수동으로 실행할 수 있습니다. 연결이 작동하는지 확인한 후에는 액세스 토큰의 수명이 1시간이므로 크론 작업과 같은 자동화된 메커니즘을 사용하여 10분마다 데이터 소스 동기화 도구를 실행하여 연결이 중단되지 않도록 해야 합니다.

다음 Docker 명령어를 사용하여 데이터 소스 동기화를 실행합니다.
```
docker run --network container:grafana -v "DS_SYNCER_SVCACCT_KEYFILE_DIR/DS_SYNCER_SVCACCT_KEYFILE_NAME.json:/app/DS_SYNCER_SVCACCT_KEYFILE_NAME.json" gke.gcr.io/prometheus-engine/datasource-syncer:v0.15.3-gke.0
-datasource-uids=UID_OF_GRAFANA_DATASOURCE
-grafana-api-token=GRAFANA_SERVICE_ACCOUNT_TOKEN
-grafana-api-endpoint=URL_OF_GRAFANA_INSTANCE
-project-id=PROJECT_ID
-query.credentials-file=DS_SYNCER_SVCACCT_KEYFILE_DIR/DS_SYNCER_SVCACCT_KEYFILE_NAME.json
-gcm-endpoint-override="https://monitoring.s3nsapis.fr/v1/projects/PROJECT_ID/location/global/prometheus/"
```
데이터 소스 동기화를 실행하는 cron 작업을 만들려면 다음을 실행하세요.
1. cron 테이블을 수정합니다.
  cron -e
2. 10분마다 앞의 명령어를 실행하는 항목을 추가합니다.
  */10 * * * * * docker run --network container:grafana -v "DS_SYNCER_SVCACCT_KEYFILE_DIR/DS_SYNCER_SVCACCT_KEYFILE_NAME.json:/app/<KEY_ID>" gke.gcr.io/prometheus-engine/datasource-syncer:v0.15.3-gke.0 -datasource-uids=UID_OF_GRAFANA_DATASOURCE -grafana-api-token=GRAFANA_SERVICE_ACCOUNT_TOKEN -grafana-api-endpoint=URL_OF_GRAFANA_INSTANCE -project-id=PROJECT_ID -query.credentials-file=DS_SYNCER_SVCACCT_KEYFILE_DIR/DS_SYNCER_SVCACCT_KEYFILE_NAME.json -gcm-endpoint-override="https://monitoring.s3nsapis.fr/v1/projects/PROJECT_ID/location/global/prometheus/"
데이터 소스 동기화 도구를 실행할 때 사용할 수 있는 명령줄 옵션에 대한 자세한 내용은 README 문서를 참고하세요.
소스 코드
1. 데이터 소스 동기화를 직접 빌드하려면 다음을 실행하세요.
  1. 코드를 포함할 디렉터리를 만들고 해당 디렉터리로 변경합니다.
    
    mkdir data-source-syncer-code cd data-source-syncer-code
    
    이 디렉터리의 경로는 후속 단계에서 환경 변수를 설정하는 데 사용됩니다. 경로를 가져오려면 pwd 명령어를 실행하고 수정 가능한 변수에 기록합니다.
    
    pwd PATH_TO_LOCAL_REPO_COPY
  2. 저장소의 현재 버전에서 코드를 클론합니다.
    
    git clone -b 'v0.15.3' --single-branch https://github.com/GoogleCloudPlatform/prometheus-engine
  3. datasource-syncer 디렉터리로 이동하여 코드를 빌드합니다.
    
    cd prometheus-engine/cmd/datasource-syncer go build main.go
2. 데이터 소스 동기화를 실행합니다. 테스트를 위해 동기화 도구를 수동으로 실행할 수 있습니다. 연결이 작동하는지 확인한 후에는 액세스 토큰의 수명이 1시간이므로 cron 작업과 같은 자동 메커니즘을 사용하여 10분마다 데이터 소스 동기화 도구를 실행하여 연결이 중단되지 않도록 해야 합니다.
  
  다음 명령어를 사용하여 데이터 소스 동기화를 수동으로 실행합니다.
  main -datasource-uids=UID_OF_GRAFANA_DATASOURCE -grafana-api-token=GRAFANA_SERVICE_ACCOUNT_TOKEN -grafana-api-endpoint=URL_OF_GRAFANA_INSTANCE -project-id=PROJECT_ID -query.credentials-file=DS_SYNCER_SVCACCT_KEYFILE_DIR/DS_SYNCER_SVCACCT_KEYFILE_NAME.json -gcm-endpoint-override="https://monitoring.s3nsapis.fr/v1/projects/PROJECT_ID/location/global/prometheus/"
  데이터 소스 동기화를 실행하는 cron 작업을 만들려면 다음을 실행하세요.
  1. cron 테이블을 수정합니다.
    
    cron -e
  2. 10분마다 앞의 명령어를 실행하는 항목을 추가합니다.
    
    */10 * * * * * main -datasource-uids=UID_OF_GRAFANA_DATASOURCE -grafana-api-token=GRAFANA_SERVICE_ACCOUNT_TOKEN -grafana-api-endpoint=URL_OF_GRAFANA_INSTANCE -project-id=PROJECT_ID -query.credentials-file=DS_SYNCER_SVCACCT_KEYFILE_DIR/DS_SYNCER_SVCACCT_KEYFILE_NAME.json -gcm-endpoint-override="https://monitoring.s3nsapis.fr/v1/projects/PROJECT_ID/location/global/prometheus/"
  데이터 소스 동기화 도구를 실행할 때 사용할 수 있는 명령줄 옵션에 대한 자세한 내용은 README 문서를 참고하세요.
새로 구성된 Grafana 데이터 소스로 이동하여 Prometheus 서버 URL 값이 https://monitoring.s3nsapis.fr으로 시작하는지 확인합니다. 페이지를 새로 고쳐야 할 수도 있습니다. 확인되면 페이지 하단으로 이동하여 저장 및 테스트를 클릭합니다. Grafana의 라벨 자동 완성이 작동하려면 이 버튼을 한 번 이상 클릭해야 합니다.

Grafana에서 측정항목 보기

Grafana에서 Cloud de Confiance 프로젝트의 측정항목을 보려면 다음 단계를 따르세요.

탐색 패널 또는 데이터 소스 페이지에서 탐색을 클릭합니다.
측정항목 필드에서 드롭다운 메뉴를 사용하여 측정항목을 선택합니다. 측정항목 탐색기를 선택하여 특정 측정항목을 검색할 수도 있습니다. 측정항목이 모니터링 리소스 2개 이상과 연결되어 있는 경우 쿼리에 monitored_resource 라벨 필터를 추가하고 리소스 유형을 선택해야 합니다.
라벨 필터와 작업을 추가하여 쿼리를 구성합니다.

Grafana에서 시각화 및 대시보드를 빌드하는 방법에 대한 자세한 내용은 패널 및 시각화를 참고하세요.

PromQL을 사용하여 Cloud Monitoring 측정항목 쿼리

PromQL의 UTF-8 사양을 사용하여 Cloud Monitoring 측정항목을 쿼리할 수 있습니다. UTF-8 측정항목 이름은 따옴표로 묶고 중괄호 안에 있어야 합니다. 라벨 이름에 기존 버전과 호환되지 않는 문자가 포함된 경우에도 따옴표로 묶어야 합니다. Cloud Monitoring 측정항목 kubernetes.io/container/cpu/limit_utilization의 경우 다음 쿼리는 동일합니다.

{"kubernetes.io/container/cpu/limit_utilization", pod_name="foo"}
{__name__="kubernetes.io/container/cpu/limit_utilization", pod_name="foo"}.
{"__name__"="kubernetes.io/container/cpu/limit_utilization", "pod_name"="foo"}.

Cloud Monitoring 분포 값 측정항목은 측정항목 이름에 _count, _sum 또는 _bucket 서픽스가 추가된 Prometheus 히스토그램처럼 쿼리될 수 있습니다.

UTF-8 호환성 이전에 만들어진 차트와 대시보드는 이름을 기존 PromQL 호환 이름으로 변환하여 Cloud Monitoring 측정항목을 쿼리합니다. 기존 PromQL 변환 규칙에 대한 자세한 내용은 Cloud Monitoring 측정항목을 기존 PromQL에 매핑을 참고하세요.

PromQL 학습

PromQL 사용에 대한 기본사항을 학습하려면 오픈소스 문서를 참조하는 것이 좋습니다. 다음은 시작하는 데 도움이 되는 리소스입니다.

모니터링 리소스 유형 지정

Cloud Monitoring 측정항목이 단일 Cloud Monitoring 모니터링 리소스 유형에만 연결된 경우 PromQL 쿼리는 리소스 유형을 수동으로 지정하지 않고도 작동합니다. 하지만 일부 시스템 측정항목을 포함하여 Cloud Monitoring 내 일부 측정항목은 리소스 유형 두 개 이상에 매핑됩니다.

Cloud de Confiance by S3NS 측정항목 목록을 참조하여 측정항목에 매핑되는 모니터링 리소스 유형을 확인할 수 있습니다. 문서의 각 항목에는 연결된 모니터링 리소스 유형이 유형 아래의 각 항목의 첫 번째 열에 나열됩니다. 모니터링 리소스 유형이 나열되지 않으면 측정항목을 모든 유형에 연결할 수 있습니다.

측정항목이 리소스 유형 2개 이상과 연결되어 있는 경우 PromQL 쿼리에서 리소스 유형을 지정해야 합니다. 리소스 유형을 선택하는 데 사용할 수 있는 특수 라벨 monitored_resource가 있습니다.

모니터링 리소스 유형은 대부분의 경우 gce_instance와 같은 짧은 문자열이지만 monitoring.googleapis.com/MetricIngestionAttribution과 같이 전체 URI로 표시되는 경우도 있습니다. 올바른 형식의 PromQL 쿼리는 다음과 같습니다.

logging_googleapis_com:byte_count{monitored_resource="k8s_container"}
loadbalancing_googleapis_com:l3_external_egress_bytes_count{monitored_resource="loadbalancing.googleapis.com/ExternalNetworkLoadBalancerRule"}

필요할 때 monitored_resource 라벨을 사용하지 않으면 다음 오류가 발생합니다.

metric is configured to be used with more than one monitored resource type; series selector must specify a label matcher on monitored resource name

라벨 충돌 해결

Cloud Monitoring에서 라벨은 측정항목이나 리소스에 속할 수 있습니다. 측정항목 라벨에 리소스 라벨과 동일한 키 이름이 있으면 쿼리의 라벨 키 이름에 metric_ 프리픽스를 추가하여 구체적으로 측정항목 라벨을 참조할 수 있습니다.

예를 들어 example.googleapis.com/user/widget_count 측정항목에 pod_name이라는 리소스 라벨과 측정항목 라벨이 있다고 가정해 보겠습니다.

리소스 라벨 값을 필터링하려면
example_googleapis_com:user_widget_count{pod_name="RESOURCE_LABEL_VALUE"}를 사용합니다.
측정항목 라벨 값을 필터링하려면
example_googleapis_com:user_widget_count{metric_pod_name="METRIC_LABEL_VALUE"}를 사용합니다.

Cloud Monitoring 측정항목 이름을 기존 PromQL에 매핑

Cloud Monitoring 측정항목 이름에는 도메인(예: compute.googleapis.com/)과 경로(예: instance/disk/max_read_ops_count)의 두 가지 구성요소가 있습니다. 기존 PromQL은 특수문자 : 및 _만 지원하므로 다음 규칙을 적용하여 Monitoring 측정항목 이름을 기존 PromQL과 호환되도록 해야 합니다.

첫 번째 /를 :으로 바꿉니다.
다른 모든 특수 문자(. 및 기타 / 문자 포함)를 _로 바꿉니다.

다음 표에는 몇 가지 측정항목 이름과 해당하는 기존 PromQL이 나열되어 있습니다.

Cloud Monitoring 측정항목 이름	기존 PromQL 측정항목 이름
`compute.googleapis.com/instance/cpu/utilization`	`compute_googleapis_com:instance_cpu_utilization`
`logging.googleapis.com/log_entry_count`	`logging_googleapis_com:log_entry_count`

Cloud Monitoring 분포 값 측정항목은 측정항목 이름에 _count, _sum 또는 _bucket 서픽스가 추가된 Prometheus 히스토그램처럼 쿼리될 수 있습니다.

Cloud Monitoring 측정항목 이름	기존 PromQL 측정항목 이름
`networking.googleapis.com/vm_flow/rtt`	`networking_googleapis_com:vm_flow_rtt_sum` `networking_googleapis_com:vm_flow_rtt_count` `networking_googleapis_com:vm_flow_rtt_bucket`

PromQL 호환성

Cloud Monitoring용 PromQL은 업스트림 PromQL과 약간 다르게 작동할 수 있습니다.

Cloud Monitoring의 PromQL 쿼리는 내부 쿼리 언어를 사용하여 Monarch 백엔드에서 부분적으로 평가되며 쿼리 결과에는 몇 가지 알려진 차이점이 있습니다. 이 섹션에 나열된 차이점 외에도 Cloud Monitoring의 PromQL은 Prometheus 버전 2.44에서 사용 가능한 PromQL과 동일합니다.

Prometheus 버전 2.44 이후에 추가된 PromQL 함수는 지원되지 않을 수 있습니다.

UTF-8 지원

Cloud Monitoring용 PromQL은 UTF-8 쿼리를 지원합니다.

Prometheus 측정항목 이름이 영숫자 문자, _ 또는 : 문자로만 구성되고 라벨 키가 영숫자 문자, _ 문자로만 구성된 경우 기존 PromQL 구문을 사용하여 쿼리할 수 있습니다. 예를 들어 유효한 쿼리는 job:my_metric:sum{label_key="label_value"}와 같습니다.

하지만 Prometheus 측정항목 이름에 _ 또는 : 문자 이외의 특수 문자가 사용되거나 라벨 키에 _ 문자 이외의 특수 문자가 사용되는 경우에는 PromQL의 UTF-8 사양에 따라 쿼리를 구성해야 합니다.

UTF-8 측정항목 이름은 따옴표로 묶고 중괄호 안에 있어야 합니다. 라벨 이름에 기존 버전과 호환되지 않는 문자가 포함된 경우에도 따옴표로 묶어야 합니다. 다음 유효한 쿼리 예시는 모두 동일합니다.

{"my.domain.com/metric/name_bucket", "label.key"="label.value"}
{__name__="my.domain.com/metric/name_bucket", "label.key"="label.value"}
{"__name__"="my.domain.com/metric/name_bucket", "label.key"="label.value"}

측정항목 이름 일치

측정항목 이름의 정확한 일치만 지원됩니다. 쿼리에 측정항목 이름의 정확한 일치를 포함해야 합니다.

__name__ 라벨에서 정규 표현식 일치자를 사용하는 일반적인 시나리오에 다음 해결 방법을 사용하는 것이 좋습니다.

Prometheus 어댑터 구성은 여러 측정항목 이름에 일치시키기 위해 =~ 연산자를 사용하는 경우가 많습니다. 이 방법을 수정하려면 각 측정항목에 별도의 정책을 사용하도록 구성을 확장하고 각 측정항목의 이름을 명시적으로 지정합니다. 이렇게 하면 예상치 못한 측정항목을 실수로 자동 확장하는 것도 방지할 수 있습니다.
정규 표현식은 동일한 차트에 여러 무차원 측정항목을 그래프로 표시하는 데 자주 사용됩니다. 예를 들어 cpu_servicename_usage와 같은 측정항목이 있는 경우 와일드 카드를 사용하여 모든 서비스를 함께 그래프로 표시할 수 있습니다. 이와 같은 무차원 측정항목을 사용하는 것은 Cloud Monitoring에서 명시적으로 좋지 않은 방법으로, 이로 인해 쿼리 성능이 크게 저하됩니다. 이 방법을 수정하려면 측정항목 이름에 차원을 삽입하는 대신 모든 차원을 측정항목 라벨로 이동합니다.
여러 측정항목을 쿼리하는 것은 쿼리할 수 있는 측정항목을 확인하는 데 자주 사용됩니다. 대신 /labels/__name__/values 호출을 사용하여 측정항목을 검색하는 것이 좋습니다.

비활성

비활성은 Monarch 백엔드에서 지원되지 않습니다.

`irate` 계산

irate 함수의 전환 확인 기간이 단계 크기보다 작으면 기간을 단계 크기로 늘립니다. Monarch에서 이러한 변경은 출력에서 어떠한 입력 데이터도 완전히 무시되지 않도록 보장하기 위해 필요합니다. 이 차이점은 rate 계산에도 적용됩니다.

`rate` 및 `increase` 계산

rate 함수의 전환 확인 기간이 단계 크기보다 작으면 기간을 단계 크기로 늘립니다. Monarch에서 이러한 변경은 출력에서 어떠한 입력 데이터도 완전히 무시되지 않도록 보장하기 위해 필요합니다. 이 차이점은 irate 계산에도 적용됩니다.

내삽 및 외삽 계산에 차이점이 있습니다. Monarch는 Prometheus와 다른 내삽 알고리즘을 사용하며, 이러한 차이로 인해 약간 다른 결과로 이어질 수 있습니다. 예를 들어 Monarch 카운터 샘플은 Prometheus에 사용되는 단일 타임스탬프가 아닌 시간 범위로 저장됩니다. 따라서 Monarch의 카운터 샘플은 Prometheus 타임스탬프가 이를 제외하더라도 비율 계산에 포함될 수 있습니다. 특히 기본 시계열의 시작 또는 끝 부분에서 쿼리할 때 일반적으로 더 정확한 비율 결과가 제공됩니다.

`histogram_quantile` 계산

샘플이 없는 히스토그램의 PromQL histogram_quantile 계산은 NaN 값을 생성합니다. 내부 쿼리 언어의 계산은 값을 생성하지 않습니다. 대신 타임스탬프의 지점이 삭제됩니다.

비율 계산 차이는 histogram_quantile 쿼리에 대한 입력에도 영향을 줄 수 있습니다.

유형이 다른 측정항목에 대한 유형별 함수

업스트림 Prometheus는 약한 유형이지만 Monarch는 강력한 유형입니다. 즉, 이러한 함수가 업스트림 Prometheus에서 작동하더라도 다른 유형의 측정항목(예: GAUGE 측정항목에서 rate() 실행 또는 COUNTER 또는 유형이 지정되지 않은 측정항목에서 histogram_quantile() 실행)에서 단일 유형에 대한 함수 실행은 Cloud Monitoring에서 작동하지 않습니다.