API 작업

이 문서에서는 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
맞춤 서비스: 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 데이터 가져오기를 참조하세요.

또한 시계열 선택기를 사용하여 프로그래매틱 방식으로 알림 정책을 설정합니다. 자세한 내용은 소진율 알림을 참조하세요.

API 작업

유효한 식별자

curl 사용 예시

인증

curl 호출

서비스 관리

서비스 ID

서비스 나열

프로토콜

서비스 만들기

프로토콜

서비스 삭제

프로토콜

SLO 관리

SLO 나열

프로토콜

특정 SLO 검색

프로토콜

SLO 만들기

SLO의 골조

예

프로토콜

SLO 삭제

프로토콜

SLO 시계열에 액세스

`curl` 사용 예시

`curl` 호출