Prometheus 사용

Prometheus는 Kubernetes에서 자주 사용되는 모니터링 도구입니다. GKE용 Cloud Operations를 구성하고 Prometheus 지원을 포함하는 경우 Prometheus 설명 형식을 사용하는 서비스에서 생성된 측정항목을 클러스터에서 내보내고 Cloud Monitoring에서 외부 측정항목으로 표시할 수 있습니다.

이 페이지에서는 GKE용 Cloud Operations로 Prometheus를 구성하고 사용하는 방법을 설명합니다. 통합용 소스 코드는 무료로 제공됩니다.

시작하기 전에

Prometheus에서 기존 Logging 및 Monitoring을 사용하여 클러스터를 구성할 수 없습니다. 기존 Logging 및 Monitoring에 대한 자세한 내용은 기존 Logging 및 Monitoring 안내 가이드를 참조하세요.

이 페이지에는 Prometheus 서버를 설치하거나 GKE용 Cloud Operations를 사용하여 GKE 클러스터를 만드는 방법이 포함되어 있지 않습니다.

Stackdriver 수집기를 설치하기 전에 다음 요구사항을 자세히 검토하세요.

  • 호환되는 Prometheus 서버를 실행 중이며 클러스터의 애플리케이션을 모니터링하도록 구성한 상태여야 합니다. 클러스터에 Prometheus를 설치하는 방법을 알아보려면 Prometheus 시작 가이드를 참조하세요.

  • GKE용 Cloud Operations를 사용하려면 클러스터를 구성해야 합니다. 자세한 내용은 GKE용 Cloud Operations 설치를 참조하세요.

  • 클러스터에 대한 Kubernetes Engine 클러스터 관리자 역할이 있어야 합니다. 자세한 내용은 GKE 역할을 참조하세요.

  • 서비스 계정에 적절한 권한이 있는지 확인해야 합니다. 자세한 내용은 노드에 최소 권한 서비스 계정 사용을 참조하세요.

수집기 설치

Stackdriver 수집기를 배포하려면 다음 단계를 따르세요.

  1. 이름과 컨트롤러 유형으로 업데이트할 객체를 식별합니다. deployment 및 statefulset의 컨트롤러 유형만 지원됩니다.

  2. 다음 환경 변수를 설정합니다.

    • KUBE_NAMESPACE: 스크립트를 실행할 네임스페이스
    • KUBE_CLUSTER: 사이드카의 클러스터 이름 매개변수
    • GCP_REGION: 사이드카의 Google Cloud 리전 매개변수
    • GCP_PROJECT: 사이드카의 Google Cloud 프로젝트 매개변수
    • DATA_DIR: 사이드카의 데이터 디렉터리. Prometheus 서버가 쓰는 공유 볼륨을 수용하는 디렉터리입니다. 후속 명령에서 이 변수는 /data 값으로 설정됩니다.
    • DATA_VOLUME: Prometheus의 데이터가 포함된 DATA_DIR의 공유 볼륨 이름. 후속 명령에서 이 변수는 data-volume으로 설정됩니다.
    • SIDECAR_IMAGE_TAG: Prometheus 사이드카의 Docker 이미지 버전. 최신 출시 버전은 Container Registry에서 찾을 수 있습니다.

  3. 다음 스크립트를 실행하고 이 절차의 초기 단계에서 식별된 두 매개변수를 제공합니다.

    kube/patch.sh
    #!/bin/sh

set -e
set -u

CLEAN_UP_ORPHANED_REPLICA_SETS='--clean-up-orphaned-replica-sets'
usage() {
  echo -e "Usage: $0 <deployment|statefulset> <name> [${CLEAN_UP_ORPHANED_REPLICA_SETS}]\n"
}

if [  $# -le 1 ]; then
  usage
  exit 1
fi

SHOULD_CLEAN_UP=${3:-}

# Override to use a different Docker image name for the sidecar.
export SIDECAR_IMAGE_NAME=${SIDECAR_IMAGE_NAME:-'gcr.io/stackdriver-prometheus/stackdriver-prometheus-sidecar'}

kubectl -n "${KUBE_NAMESPACE}" patch "$1" "$2" --type strategic --patch "
spec:
  template:
    spec:
      containers:
      - name: sidecar
        image: ${SIDECAR_IMAGE_NAME}:${SIDECAR_IMAGE_TAG}
        imagePullPolicy: Always
        args:
        - \"--stackdriver.project-id=${GCP_PROJECT}\"
        - \"--prometheus.wal-directory=${DATA_DIR}/wal\"
        - \"--stackdriver.kubernetes.location=${GCP_REGION}\"
        - \"--stackdriver.kubernetes.cluster-name=${KUBE_CLUSTER}\"
        #- \"--stackdriver.generic.location=${GCP_REGION}\"
        #- \"--stackdriver.generic.namespace=${KUBE_CLUSTER}\"
        ports:
        - name: sidecar
          containerPort: 9091
        volumeMounts:
        - name: ${DATA_VOLUME}
          mountPath: ${DATA_DIR}
"
if [[ "${SHOULD_CLEAN_UP}" == "${CLEAN_UP_ORPHANED_REPLICA_SETS}" ]]; then
  # Delete the replica sets from the old deployment. If the Prometheus Server is
  # a deployment that does not have `revisionHistoryLimit` set to 0, this is
  # useful to avoid PVC conflicts between the old replica set and the new one
  # that prevents the pod from entering a RUNNING state.
  kubectl -n "${KUBE_NAMESPACE}" get rs | grep "$2-" | awk '{print $1}' | xargs kubectl delete -n "${KUBE_NAMESPACE}" rs
fi

스크립트 실행이 완료되면 Stackdriver 수집기가 절차의 1단계에서 식별된 객체의 pod에 사이드카로 추가됩니다. 주석 처리된 스크립트의 두 줄은 GKE 클러스터의 측정항목 데이터 수집과 관련이 없습니다. 그러나 이 두 줄은 일반 MonitoredResource를 채울 때 관련이 있습니다.

구성을 영구적으로 변경하려면 추가 단계를 수행해야 합니다. 다음 섹션에서 이 단계를 설명합니다.

설치 검증

Stackdriver 수집기 설치를 검증하려면 다음 명령어를 실행합니다.

kubectl -n "${KUBE_NAMESPACE}" get <deployment|statefulset> <name> -o=go-template='{{$output := "stackdriver-prometheus-sidecar does not exist."}}{{range .spec.template.spec.containers}}{{if eq .name "sidecar"}}{{$output = (print "stackdriver-prometheus-sidecar exists. Image: " .image)}}{{end}}{{end}}{{printf $output}}{{"\n"}}'

  • Prometheus 사이드카가 성공적으로 설치되었으면 스크립트 출력에 Container Registry에서 사용된 이미지가 나열됩니다. 다음 예시에서 이미지 버전은 0.4.3입니다. 설치 시 버전이 다를 수 있습니다.

    stackdriver-prometheus-sidecar exists. Image: gcr.io/stackdriver-prometheus/stackdriver-prometheus-sidecar:0.4.3

  • 그렇지 않으면 다음과 같은 스크립트 출력이 표시됩니다.

    stackdriver-prometheus-sidecar does not exist.

워크로드가 최신 상태이며 사용 가능한지 확인하려면 다음을 실행합니다.

kubectl -n "${KUBE_NAMESPACE}" get <deployment|statefulset> <name>

구성 변경사항을 영구적으로 적용

수집기가 성공적으로 설치되었는지 확인한 후 클러스터 구성을 업데이트하여 변경사항을 영구적으로 적용하세요.

  1. Prometheus 서버를 구성하여 공유 볼륨에 씁니다. 다음 예시 단계에서는 DATA_DIR이 /data로 설정되고 DATA_VOLUME이 data-volume으로 설정되었다고 가정합니다.

    1. Prometheus pod에 공유 볼륨이 있는지 확인합니다.

      volumes:
  - name: data-volume
    emptyDir: {}

    2. Prometheus가 /data 아래에 볼륨을 마운트하도록 합니다.

      volumeMounts:
- name: data-volume
  mountPath: /data

    3. args 컨테이너에 다음을 추가하여 Prometheus 서버가 /data의 공유 볼륨에 쓰도록 지시합니다.

      --storage.tsdb.path=/data

  2. 워크로드 구성을 관리하는 데 사용하는 도구를 통해 클러스터에 구성을 다시 적용하고 Stackdriver 수집기 컨테이너를 새 구성의 사이드카로 포함합니다.

    - name: sidecar
  image: gcr.io/stackdriver-prometheus/stackdriver-prometheus-sidecar:[SIDECAR_IMAGE_TAG]
  args:
  - "--stackdriver.project-id=[GCP_PROJECT]"
  - "--prometheus.wal-directory=/data/wal"
  - "--prometheus.api-address=[API_ADDRESS]"
  - "--stackdriver.kubernetes.location=[GCP_REGION]"
  - "--stackdriver.kubernetes.cluster-name=[KUBE_CLUSTER]"
  ports:
  - name: sidecar
    containerPort: 9091
  volumeMounts:
  - name: data-volume
    mountPath: /data

    이전 표현식에서 [API_ADDRESS]는 Prometheus의 API 주소(일반적으로 http://127.0.0.1:9090)를 나타냅니다.

수집기에 대한 추가 구성 세부정보는 Stackdriver Prometheus 사이드카 문서를 참조하세요.

측정항목 보기

Prometheus는 측정항목을 Google Cloud 운영 제품군에 외부 측정항목으로 내보내도록 구성되어 있습니다.

이러한 측정항목을 보려면 다음 안내를 따르세요.

  1. Cloud Console에서 Monitoring을 선택합니다.

    Monitoring으로 이동

  2. Monitoring 탐색창에서 측정항목 탐색기를 클릭합니다.

  3. 리소스 유형 및 측정항목 찾기 메뉴에서 다음을 수행합니다.

    • 리소스 유형에 대해 Kubernetes 컨테이너(k8s_container)를 선택합니다.
    • 측정항목 필드에서 external/prometheus/ 프리픽스가 있는 필드를 선택합니다. 예를 들어 external/prometheus/go_memstats_alloc_bytes를 선택할 수 있습니다.

    다음 예시에서는 특정 클러스터의 측정항목을 표시하는 필터가 추가되었습니다. 클러스터 이름으로 필터링하면 여러 클러스터가 있을 때 유용합니다.

    Kubernetes 컨테이너의 샘플 Prometheus 측정항목

Prometheus에서 파생된 측정항목의 비용 관리

일반적으로 Prometheus는 애플리케이션에서 내보낸 모든 측정항목을 수집하도록 구성되며 기본적으로 Stackdriver 수집기는 이러한 측정항목을 Cloud Monitoring으로 보냅니다 이 컬렉션에는 애플리케이션이 의존하는 라이브러리에서 내보낸 측정항목이 포함됩니다. 예를 들어 Prometheus 클라이언트 라이브러리는 애플리케이션 환경에 대한 많은 측정항목을 내보냅니다.

Stackdriver 수집기에서 필터를 구성하여 Cloud Monitoring에 수집되는 측정항목을 선택할 수 있습니다. 예를 들어 kubernetes-pods 및 kubernetes-service-endpoints에 의해 생성된 측정항목만 가져오려면 stackdriver-prometheus-sidecar를 시작할 때 다음 --include 문을 사용합니다.

 --include={job=~"kubernetes-pods|kubernetes-service-endpoints"}

자세한 내용은 Stackdriver Prometheus 사이드카 문서를 참조하세요.

또한 이러한 측정항목이 청구서에 기여하는 금액을 추정할 수 있습니다.

Prometheus 통합 문제

Cloud Monitoring에 데이터가 표시되지 않습니다.

설치 단계를 수행한 후 Cloud Monitoring에 데이터가 표시되지 않으면 수집기 로그에서 오류 메시지를 검색합니다.

로그에 분명한 실패 메시지가 포함되지 않은 경우 --log.level=debug 플래그를 수집기에 전달하여 디버그 로깅을 사용 설정합니다. 로깅 변경사항을 적용하려면 수집기를 다시 시작해야 합니다. 수집기를 다시 시작한 후 수집기 로그에서 오류 메시지를 검색합니다.

데이터가 Cloud Monitoring으로 전송되는지 확인하려면 --stackdriver.store-in-files-directory 명령줄 매개변수를 사용하여 파일에 요청을 보낸 다음 이 디렉터리의 파일을 검사합니다.

권한이 거부됨

Monitoring API의 권한 거부 오류가 표시되면 시작하기 전에에 설명된 요구 사항을 검토하세요. 서비스 계정에 올바른 권한이 있는지 확인합니다. 워크로드 아이덴티티를 사용하는 경우 KSA와 GSA 간의 관계를 만들어야 합니다.

기록 규칙을 사용 중이지만 Cloud Monitoring에 측정항목이 표시되지 않습니다.

가능한 경우 기록 역할을 사용할 때 원시 측정항목을 Cloud Monitoring으로 수집하고 Cloud Monitoring의 기능을 사용하여 차트 또는 대시보드를 만들 때 데이터를 집계합니다.

원시 측정항목을 수집할 수 없다면 수집기 구성에 static_metadata 항목을 추가하면 됩니다. 이 옵션을 사용하려면 job 및 instance 라벨을 보존해야 합니다. 예를 들어 현재 구성은 유효합니다.

  • Prometheus 서버 구성:

    groups:
- name: my-groups
  rules:
  - record: backlog_avg_10m
    expr: avg_over_time(backlog_k8s[10m])
  - record: backlog_k8s
    expr: sum(total_lag) by (app, job, instance)

  • Prometheus 수집기 구성:

    static_metadata:
  - metric: backlog_avg_10m
    type: gauge

job 또는 instance 라벨을 변경하거나 삭제하는 기록 규칙은 지원되지 않습니다.

내 측정항목에 job 및 instance Prometheus 라벨이 없습니다.

Prometheus용 Stackdriver 수집기는 잘 알려진 Prometheus 라벨로 Kubernetes 객체의 Cloud Monitoring MonitoredResource를 생성합니다. 라벨 설명자를 변경하면 수집기가 Monitoring에 측정항목을 쓸 수 없습니다.

로그에 '중복 시계열' 또는 '쓰기 순서가 맞지 않음' 오류가 표시됩니다.

이러한 오류는 동일한 시계열에 측정항목 데이터를 두 번 쓰면 발생합니다. 이는 Prometheus 엔드포인트가 단일 Cloud Monitoring 모니터링 리소스에서 동일한 측정항목을 두 번 사용할 때 발생합니다.

예를 들어 Kubernetes 컨테이너는 여러 포트에서 Prometheus 측정항목을 전송할 수 있습니다. Monitoring k8s_container 모니터링 리소스는 포트를 기준으로 리소스를 구분하지 않으므로 Monitoring은 사용자가 동일한 시계열에 두 개의 포인트를 쓰는 것을 감지합니다. 이러한 상황을 방지하려면 Prometheus에 시계열을 구분하는 측정항목 라벨을 추가하세요. 예를 들어 __meta_kubernetes_pod_annotation_prometheus_io_port 라벨은 컨테이너가 다시 시작될 때 일정하게 유지되므로 사용할 수 있습니다.

로그에 '측정항목 종류는 X여야 하지만 Y입니다'라는 오류가 표시됩니다.

이러한 오류는 기존 측정항목 설명의 Prometheus 측정항목 유형을 변경하면 발생합니다. Cloud Monitoring 측정항목은 엄격하게 유형이 지정되며 게이지, 카운터 등의 측정항목 유형 변경은 지원하지 않습니다.

측정항목 유형을 변경하려면 해당 측정항목 설명을 삭제하고 새 설명자를 만들어야 합니다. 측정항목 설명을 삭제하면 기존 시계열 데이터에 액세스할 수 없게 됩니다.

전에 Prometheus 측정항목 유형을 분명히 본 적이 있는데 지금은 찾을 수 없습니다.

Prometheus는 측정항목을 Cloud Monitoring에 외부 측정항목으로 내보내도록 사전 구성되어 있습니다. 데이터를 내보내면 Monitoring이 외부 측정항목에 대한 적절한 측정항목 설명을 만듭니다. 최소 24개월 동안 해당 측정항목 유형의 데이터가 기록되지 않으면 측정항목 설명이 삭제될 수 있습니다.

사용하지 않은 측정항목 설명이 24개월 후에 삭제된다는 보장은 없지만 Monitoring은 이전 24개월 동안 사용되지 않은 Prometheus 측정항목 설명을 삭제할 권한이 있습니다.

지원 중단 정책

Cloud Monitoring과 Prometheus 통합에는 에이전트 지원 중단 정책이 적용됩니다.