이 문서에서는 Cloud Monitoring API를 사용하여 서비스와 서비스 수준 목표(SLO)를 관리하는 방법을 설명합니다.
서비스 모니터링은 Monitoring API에 다음 리소스를 추가합니다.
이 문서에서는 이러한 추가 리소스를 SLO API로 통칭하여 기본 용도를 보여줍니다. SLO API의 구조에 대한 일반적인 개요는 API의 구성을 참조하세요. Cloud Monitoring API v3 아래에 포괄적인 참조 자료가 표시됩니다.
SLO API를 사용하여 다음을 수행할 수 있습니다.
서비스를 만들고 관리합니다.
모든 서비스의 커스텀 또는 사전 정의된 서비스 수준 지표(SLI)를 기반으로 서비스 수준 목표(SLO)를 만듭니다.
유효한 식별자
SLO API의 여러 메서드는 다양한 요소, 특히 프로젝트 및 서비스의 식별자를 사용합니다. 이러한 ID는 다음 규칙을 준수합니다.
- 길이: 1~63자(영문 기준)
- 문자: 소문자, 숫자, 하이픈만
- 첫 문자: 소문자
- 마지막 문자: 소문자 또는 숫자이며 하이픈은 아님
이 규칙의 정규 표현식은 [a-z](?:[-a-z0-9]{0,61}[a-z0-9])?
입니다.
curl
사용 예시
이 섹션에서는 curl
도구를 사용하여 SLO API를 호출하는 데 사용되는 규칙 및 설정에 대해 설명합니다. 클라이언트 라이브러리를 통해 이 API를 사용하는 경우에는 이 섹션을 건너뛸 수 있습니다.
이 페이지의 예시에서는 curl
도구를 사용하여 REST 엔드포인트로 HTTP 요청을 전송하여 SLO API에 액세스합니다. 인증 및 curl
호출에 대한 다음 정보를 사용하여 호출에 쓰이는 변수를 설정합니다.
인증
측정항목 범위의 범위 지정 프로젝트 ID를 보존할 환경 변수를 만듭니다. 다음 예시에서는
PROJECT_ID
를 사용합니다.PROJECT_ID=my-test-service
Google Cloud CLI에 인증합니다.
gcloud auth login
각 명령어로 프로젝트 ID를 지정하지 않으려면 gcloud CLI를 사용하여 프로젝트 ID를 기본값으로 설정합니다.
gcloud config set project ${PROJECT_ID}
승인 토큰을 만들고 환경 변수에 저장합니다. 이 예에서는 변수
ACCESS_TOKEN
를 호출합니다.ACCESS_TOKEN=`gcloud auth print-access-token`
정기적으로 액세스 토큰을 새로고침해야 합니다. 작업한 명령어에서 사용자가 인증되지 않았다고 갑자기 보고하면 이 명령어를 다시 실행합니다.
액세스 토큰을 받았는지 확인하려면
ACCESS_TOKEN
변수를 출력합니다.echo ${ACCESS_TOKEN} ya29.GluiBj8o....
curl
호출
각 curl
호출에는 인수 집합과 SLO API 리소스의 URL이 포함됩니다. 일반적인 인수에는 PROJECT_ID
및 ACCESS_TOKEN
환경 변수로 지정된 값이 포함됩니다.
HTTP 요청의 유형을 지정하기 위해 다른 인수를 지정해야 할 수도 있습니다(예: -X DELETE
). 기본 요청은 GET
이므로 예시에서는 이를 지정하지 않습니다.
각 curl
호출은 다음과 같은 일반적인 구조를 취합니다.
curl --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" <other_args> https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/<request>
예를 들어 프로젝트의 모든 서비스를 나열하기 위해 다음 GET
요청을 실행합니다.
curl --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services
이 요청은 서비스 ID가 'my-test-service'인 GKE 워크로드 서비스 같은 항목이 포함된 서비스 설명 배열을 반환합니다.
{ "services": [ { "name": "projects/PROJECT_NUMBER/services/my-test-service", "displayName": "My Test GKE Workload Service", "basicService": { "serviceType": "GKE_WORKLOAD", "serviceLabels": { "cluster_name": "workload-test", "location": "us-central1-c", "namespace_name": "kube-system", "project_id": "lesser-weevil", "top_level_controller_name": "gke-metrics-controller", "top_level_controller_type": "DaemonSet" } }, "gkeWorkload": { "projectId": "lesser-weevil", "location": "us-central1-c", "clusterName": "workload-test", "namespaceName": "kube-system", "topLevelControllerType": "DaemonSet", "topLevelControllerName": "gke-metrics-controller" }, "source": "USER", "telemetry": { "resourceName": "//container.googleapis.com/projects/PROJECT_ID/zones/us-central1-c/clusters/workload-test/k8s/namespaces/kube-system/apps/daemonsets/gke-metrics-controller" } }, ... ] }
이 서비스를 만드는 데 사용된 구성을 보려면 서비스 만들기를 참조하세요. 이 목록의 gkeWorkload
구조는 서비스를 만드는 데 사용된 basicService
구조에서 파생됩니다.
서비스 구조에 대한 자세한 내용은 Service
를 참조하세요.
서비스 관리
Service
리소스는 서비스 구성을 위한 루트 요소 역할을 합니다. 예를 들어 SLO와 같은 특정 서비스의 측면은 서비스 이름 아래에 구성됩니다. 지원되는 서비스 유형은 다음과 같습니다.
- App Engine 서비스:
APP_ENGINE
- Cloud Endpoints 서비스:
CLOUD_ENDPOINTS
- 표준 Istio 서비스:
ISTIO_CANONICAL_SERVICE
- 클러스터 Istio 서비스:
CLUSTER_ISTIO
- Cloud Run 서비스:
CLOUD_RUN
- Google Kubernetes Engine 기반 서비스 집합:
- GKE 서비스:
GKE_SERVICE
- GKE 네임스페이스:
GKE_NAMESPACE
- GKE 워크로드:
GKE_WORKLOAD
- GKE 서비스:
- 맞춤 서비스:
CUSTOM
자세한 내용은 기본 서비스 유형 또는 기본 GKE 서비스 유형을 참조하세요.
API를 사용하여 SLO를 프로젝트의 모든 서비스에 추가할 수 있습니다. SLO 관리에서는 SLO를 조작하는 명령어를 다룹니다.
서비스 ID
각 서비스에는 리소스 이름이라는 정규화된 식별자가 있습니다. 이 식별자는 서비스 설명의 name
필드에 저장됩니다. 예를 들면 다음과 같습니다.
"name": "projects/PROJECT_NUMBER/services/PROJECT_ID-zone-us-central1-a-cloudrun-istio-system-cluster-local-gateway",
리소스 이름에는 하위 문자열 projects/PROJECT_NUMBER/services/
뒤에 리소스 이름 일부를 붙인 더 짧은 서비스 ID가 포함됩니다.
리소스 이름이 projects/PROJECT_NUMBER/services/my-test-service
인 자체 서비스를 만든 경우 서비스 ID는 my-test-service
입니다.
간결성과 정확성을 위해 curl
예시에서는 서비스 ID가 환경 변수 SERVICE_ID
에 보관되어 있다고 가정하므로 서비스 ID를 반복적으로 참조할 수 있습니다.
서비스 나열
프로젝트의 모든 서비스에 대한 정보를 검색하려면 services.list
메서드를 호출합니다. 서비스 ID로 특정 서비스에 대한 정보를 검색하려면 services.get
메서드를 사용합니다.
프로토콜
curl
을 사용하여 서비스에 대한 정보를 나열하려면 GET
요청을 다음으로 전송하여 services.list
또는 services.get
메서드를 호출합니다.
https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services
: 모든 서비스 나열https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID
: 특정 서비스 가져오기
예를 들어 다음 요청은 환경 변수 SERVICE_ID
에 저장된 값으로 식별된 서비스에 대한 정보를 검색합니다.
curl --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services/${SERVICE_ID}
서비스 만들기
서비스를 만들려면 서비스 유형의 표현을 지정하고 services.create
메서드로 보냅니다.
기본 서비스 유형 및 기본 GKE 서비스 유형에 설명된 서비스 유형 구조를 선택할 수 있습니다.
구조는 다양하지만 API를 호출하는 프로세스는 동일합니다.
서비스의 표시 이름과 서비스 표현을 포함하는 basicService
필드를 지정해야 합니다.
서비스에 원하는 서비스 ID를 선택적으로 지정할 수 있습니다. 다음 예시에서는 {[gke_name_short}} 워크로드 서비스를 만드는 방법을 보여줍니다.
프로토콜
curl
을 사용하여 서비스를 만들려면 POST
메시지를 https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services
엔드포인트에 보냅니다.
서비스 ID를 제공하려면 서비스 ID의 변수를 만듭니다.
SERVICE_ID=my-test-service
이 값은 URL 쿼리 매개변수
service_id
에 제공됩니다.서비스를 설명하는 요청 본문을 저장할 변수를 만듭니다.
CREATE_SERVICE_POST_BODY=$(cat <<EOF { "displayName": "My Test GKE Workload Service", "basicService": { "serviceType": "GKE_WORKLOAD", "serviceLabels": { "cluster_name": "workload-test", "location": "us-central1-c", "namespace_name": "kube-system", "project_id": "PROJECT_ID", "top_level_controller_name": "gke-metrics-controller", "top_level_controller_type": "DaemonSet" } } } EOF )
엔드포인트에 요청 본문을 게시하고 서비스 ID를
service_id
쿼리 매개변수의 값으로 지정합니다.curl --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" --header "Content-Type: application/json" -X POST -d "${CREATE_SERVICE_POST_BODY}" https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services?service_id=${SERVICE_ID}
다른 서비스와 연결된 구조의 예시는 기본 서비스 유형 또는 기본 GKE 서비스 유형을 참조하세요.
서비스 삭제
생성된 서비스를 삭제하려면 services.delete
메서드를 호출하고 서비스 ID를 지정합니다.
프로토콜
curl
을 사용하여 서비스를 삭제하려면 DELETE
요청을 https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID
엔드포인트에 전송합니다.
curl --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" -X DELETE https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services/${SERVICE_ID}
SLO 관리
SLO API를 사용하여 SLO를 생성, 삭제, 검색할 수 있습니다. 서비스마다 SLO를 최대 500개까지 사용할 수 있습니다.
서비스의 SLO를 관리하려면 서비스 ID가 있어야 합니다. SLO는 속한 서비스를 기반으로 이름이 지정됩니다. 서비스 ID 식별에 대한 자세한 내용은 서비스 ID를 참조하세요.
SLO 나열
서비스와 연결된 모든 SLO에 대한 정보를 검색하려면 services.serviceLevelObjectives.list
메서드를 호출합니다.
특정 SLO에 대한 정보를 이름으로 검색하려면 services.serviceLevelObjectives.get
메서드를 사용합니다.
프로토콜
curl
을 사용하여 서비스에 대한 정보를 나열하려면 GET
요청을 다음으로 전송하여 services.serviceLevelObjectives.list
또는 services.serviceLevelObjectives.get
메서드를 호출합니다.
https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/[SERVICE_ID]/serviceLevelObjectives
: 모든 SLO 나열https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/[SERVICE_ID]/serviceLevelObjectives/SLO_ID
: 특정 SLO 가져오기
예를 들어, 다음 요청은 환경 변수 SERVICE_ID
에 저장된 서비스 ID와 연관된 모든 SLO를 나열합니다.
curl --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services/${SERVICE_ID}/serviceLevelObjectives
다음은 'currencyservice' 서비스에서 가져온 가용성 SLO입니다.
{ "name": "projects/PROJECT_NUMBER/services/PROJECT_ID-zone-us-central1-c-csm-main-default-currencyservice/serviceLevelObjectives/3kavNVTtTMuzL7KcXAxqCQ", "displayName": "98% Availability in Calendar Week" "serviceLevelIndicator": { "basicSli": { "availability": {}, "location": [ "us-central1-c" ] } }, "goal": 0.98, "calendarPeriod": "WEEK", },
이 SLO는 가용성 SLI를 기반으로 하며, 타겟 성능 목표를 98%로 설정하고, 1주일 동안 규정 준수를 측정합니다. 가용성 SLI에 대한 자세한 내용은 서비스 수준 지표를 참조하세요.
SLO의 구조에 대한 자세한 내용은 ServiceLevelObjective
를 참조하세요.
특정 SLO 검색
각 SLO는 서비스 내에 고유 식별자가 있으며 식별자는 SLO의 name
필드에서 문자열과 serviceLevelObjectives
로 구성됩니다. 아래 예시를 참조하세요.
"name": "projects/PROJECT_NUMBER/services/PROJECT_ID-zone-us-central1-c-csm-main-default-currencyservice/serviceLevelObjectives/3kavNVTtTMuzL7KcXAxqCQ",
SLO ID는 3kavNVTtTMuzL7KcXAxqCQ
문자열입니다.
이 특정 SLO에 대한 정보를 검색하려면 ID로 SLO를 요청합니다.
프로토콜
curl
을 사용하여 특정 SLO를 가져오려면 GET
요청을 https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID/serviceLevelObjectives/SLO_ID
에 전송하여 services.serviceLevelObjectives.get
메서드를 호출합니다.
SLO_ID=dhefHDM4TwSRZEKIV4ZYEg curl --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services/${SERVICE_ID}/serviceLevelObjectives/${SLO_ID}
SLO 만들기
SLO API를 사용하여 SLO를 만들려면 ServiceLevelObjective
객체를 만들고 serviceLevelObjectives.create
메서드에 전달해야 합니다.
SLO 구조는 serviceLevelIndicator
필드의 값에 대한 구조를 포함하여 여러 개의 삽입된 구조가 있습니다.
Cloud Service Mesh, Google Kubernetes Engine의 Istio, App Engine 서비스의 경우 SLI는 사전 정의됩니다. Cloud Service Mesh 콘솔을 사용하여 SLO를 만들 수 있습니다. 실적 목표와 규정 준수 기간만 지정하면 됩니다.
다른 서비스의 경우 SLO API를 사용하여 SLO를 정의해야 합니다. SLO를 지정하려면
serviceLevelIndicator
필드의 값도 만들어야 합니다. 일부 기술에 대해서는 서비스 수준 지표 만들기를, 다양한 소스를 기반으로 한 예시는 측정항목에서 SLI 만들기를 참조하세요.
Google Cloud 콘솔을 사용하여 SLI를 만들 수도 있습니다. 자세한 내용은 SLO 만들기를 참조하세요.
SLO의 골조
SLO를 빌드하기 위한 기본 골조는 다음과 같습니다.
{ "displayName": string, "serviceLevelIndicator": { object (ServiceLevelIndicator) }, "goal": number, // Union field period can be only one of the following: "rollingPeriod": string, "calendarPeriod": enum (CalendarPeriod) // End of list of possible types for union field period. }
다음을 지정해야 합니다.
- 표시 이름: SLO의 설명
- 세 가지 유형 중 하나인 서비스 수준 지표:
- 실적 목표(백분율)
- 규정 준수 기간(2가지 유형 중 하나):
- 일정 기간(초)의 연속 기간
- 캘린더 기간
SLI, 실적 목표, 규정 준수 기간에 대한 자세한 내용은 서비스 모니터링 개념을 참조하세요.
Cloud Service Mesh, Google Kubernetes Engine의 Istio, App Engine 서비스의 경우 SLI 유형은 기본 SLI입니다.
다른 서비스의 경우 요청 기반 SLI 또는 기간 기반 SLI를 만들어야 합니다. 일부 기술의 경우 서비스 수준 지표 만들기를 참조하세요.
예
SLI가 준비되면 SLO를 빌드할 수 있습니다. 다음 예시에서는 기본 SLI를 사용하는 서비스의 SLO를 정의합니다. 단일 SLI에 여러 SLO가 있을 수 있습니다(예: 95% 가용성 및 99% 가용성). 다음 예시는 1주일 동안 95%의 가용성을 위한 SLO입니다.
{ "serviceLevelIndicator": { "basicSli": { "availability": {}, "location": [ "us-central1-c" ] } }, "goal": 0.95, "calendarPeriod": "WEEK", "displayName": "95% Availability in Calendar Week" }
이 예에서는 3일 순환 기간에 75% 가용성을 위한 SLO를 지정합니다.
{ "serviceLevelIndicator": { "basicSli": { "availability": {}, "location": [ "us-central1-c" ] } }, "goal": 0.75, "rollingPeriod": "259200s", "displayName": "75% Availability in Rolling 3 Days" }
프로토콜
curl
을 사용하여 SLO를 만들려면 POST
메시지를 https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID/serviceLevelObjectives
엔드포인트에 전송합니다.
서비스 ID에 대한 변수를 만듭니다.
SERVICE_ID=custom:my-test-service
ServiceLevelObjective
객체의 인스턴스인 요청 본문을 저장할 변수를 만듭니다. 이 예시에서는 앞에서 설명한 SLO 중 하나를 사용합니다.CREATE_SLO_POST_BODY=$(cat <<EOF { "serviceLevelIndicator": { "basicSli": { "availability": {}, "location": [ "us-central1-c" ] } }, "goal": 0.75, "rollingPeriod": "259200s", "displayName": "75% Availability in Rolling 3 Days" } EOF )
요청 본문을 엔드포인트에 게시합니다.
curl --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" --header "Content-Type: application/json" -X POST -d "${CREATE_SLO_POST_BODY}" https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services/${SERVICE_ID}/serviceLevelObjectives
원하는 경우 SLO에 원하는 ID를
service_level_objective_id
쿼리 매개변수의 값으로 지정할 수도 있습니다.SLO_ID=test-slo-id curl --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" --header "Content-Type: application/json" -X POST -d "${CREATE_SLO_POST_BODY}" https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services/${SERVICE_ID}/serviceLevelObjectives?service_level_objective_id=${SLO_ID}
SLO 삭제
SLO를 삭제하려면 services.serviceLevelObjectives.delete
메서드를 호출하고 프로젝트에서 SLO의 ID를 지정합니다.
프로토콜
curl
을 사용하여 SLO를 삭제하려면 https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID/serviceLevelObjectives/SLO_ID
엔드포인트에 DELETE
요청을 전송합니다.
curl --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" -X DELETE https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services/${SERVICE_ID}/serviceLevelObjectives/${SLO_ID}
SLO 시계열에 액세스
SLO 데이터는 시계열에 저장되므로 timeSeries.list
메서드를 사용하여 검색할 수 있습니다.
그러나 이 데이터는 표준 측정항목 유형에 저장되지 않으므로 timeSeries.list
메서드에 대해 측정항목 유형 필터를 지정하는 표준 메커니즘을 사용할 수 없습니다.
그 대신 filter
매개변수의 timeSeries.list
메서드에 대해 다른 유형의 필터인 시계열 선택기를 지정하여 SLO 시계열을 검색합니다.
이 선택기 사용에 대한 자세한 내용은 SLO 데이터 가져오기를 참조하세요.
또한 시계열 선택기를 사용하여 프로그래매틱 방식으로 알림 정책을 설정합니다. 자세한 내용은 소진율 알림을 참조하세요.