API 작업

Service Monitoring은 Monitoring API에 다음 리소스를 추가합니다.

이 페이지에서는 새 API 리소스의 기본 용도를 보여줍니다. 여기에서 사용되는 구조의 일반적인 개요는 API의 구조를 참조하세요. Cloud Monitoring API v3 아래에 포괄적인 참조 자료가 표시됩니다.

이 문서에서는 이러한 추가 사항을 Service Monitoring API라고 통칭합니다.

API를 사용해야 하는 경우

Service Monitoring API는 서비스 및 서비스 수준 목표(SLO)를 관리하는 데 사용할 수 있습니다. 이 페이지에서는 커스텀 서비스 및 서비스 수준 지표(SLI)를 중점적으로 다룹니다. App Engine, Google Kubernetes Engine의 Istio, Cloud Endpoints에서 실행되는 서비스가 자동으로 감지되며 서비스의 SLI가 사전 정의됩니다. SLO를 정의하려면 Anthos Service Mesh 콘솔 또는 Service Monitoring API를 사용할 수 있습니다. Anthos Service Mesh 대시보드를 사용하여 SLO를 만드는 방법에 대한 자세한 내용은 Anthos Service Mesh 설명서: SLO 만들기를 참조하세요.

자신만의 서비스와 SLO도 정의할 수 있지만 Service Monitoring API를 사용해야 합니다. 사용 가능한 Google Cloud Console 지원이 없습니다.

이 페이지의 예는 주로 커스텀 서비스와 SLI에 중점을 둡니다.

유효한 식별자

Service Monitoring API의 여러 메서드는 다양한 요소의 식별자, 특히 프로젝트 및 서비스의 식별자를 사용합니다. 이 ID는 다음 규칙을 준수합니다.

  • 길이: 1~63자(영문 기준)
  • 문자: 소문자, 숫자, 하이픈만
  • 첫 문자: 소문자
  • 마지막 문자: 소문자 또는 숫자이며 하이픈은 아님

이 규칙의 정규식은 [a-z](?:[-a-z0-9]{0,61}[a-z0-9])?입니다.

curl 사용 예시

이 섹션에서는 curl 도구를 사용하여 Service Monitoring API를 호출하는 데 사용되는 규칙 및 설정에 대해 설명합니다. 클라이언트 라이브러리를 통해 이 API를 사용하는 경우에는 이 섹션을 건너뛸 수 있습니다.

이 페이지의 예에서는 curl 도구를 사용하여 REST 엔드포인트에 HTTP 요청을 전송하여 Service Monitoring API에 액세스합니다. 인증 및 curl 호출에 대한 다음 정보를 사용하여 호출에 쓰이는 변수를 설정합니다.

인증

  1. Cloud Monitoring 작업공간의 ID를 저장할 환경 변수를 만듭니다. 다음 예에서는 PROJECT_ID를 사용합니다.

    PROJECT_ID=my-test-service
        
  2. Cloud SDK에 인증합니다.

    gcloud auth login
        
  3. 각 명령어로 프로젝트 ID를 지정하지 않으려면 Cloud SDK를 사용하여 프로젝트 ID를 기본값으로 설정합니다.

    gcloud config set project ${PROJECT_ID}
        
  4. 인증 토큰을 만들고 환경 변수에 캡처합니다. 다음 예에서는 ACCESS_TOKEN 변수를 호출합니다.

    ACCESS_TOKEN=`gcloud auth print-access-token`
        

    정기적으로 액세스 토큰을 새로고침해야 합니다. 작업한 명령어에서 사용자가 인증되지 않았다고 갑자기 보고하면 이 명령어를 다시 실행합니다.

  5. 액세스 토큰을 받았는지 확인하려면 ACCESS_TOKEN 변수를 출력합니다.

    echo ${ACCESS_TOKEN}
        ya29.GluiBj8o....
        

curl 호출

curl 호출에는 Service Monitoring API 리소스의 URL이 뒤에 오는 인수 세트가 포함됩니다. 일반적인 인수에는 PROJECT_IDACCESS_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
    

이 요청은 'currencyservice'라는 Istio 서비스와 같은 항목이 포함된 서비스 설명 배열을 반환합니다.

    {
      "services": [
        {
          "name": "projects/[PROJECT_NUMBER]/services/[PROJECT_ID]-zone-us-central1-c-csm-main-default-currencyservice",
          "displayName": "[PROJECT_ID]/us-central1-c/csm-main/default/currencyservice",
          "clusterIstio": {
            "location": "us-central1-c",
            "clusterName": "csm-main",
            "serviceNamespace": "default",
            "serviceName": "currencyservice"
          },
          "telemetry": {
            "resourceName": "//container.googleapis.com/projects/[PROJECT_ID]/zones/us-central1-c/clusters/csm-main/k8s/namespaces/default/services/currencyservice"
          }
        },
       ...
      ]
    }
    

서비스 구조에 대한 자세한 내용은 Service를 참조하세요.

서비스 관리

Service 리소스는 서비스 구성을 위한 루트 요소 역할을 합니다. 예를 들어 SLO와 같은 특정 서비스의 측면은 서비스 이름으로 구성됩니다.

App Engine, Google Kubernetes Engine의 Istio, Cloud Endpoints 서비스가 자동으로 생성됩니다. Anthos Service Mesh 콘솔 또는 Service Monitoring API를 사용하여 이러한 서비스에 SLO 추가 등의 작업을 수행할 수 있습니다.

직접 만든 서비스를 커스텀 서비스라고 합니다. 커스텀 서비스는 Service Monitoring 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}
    

서비스 만들기

서비스가 자동으로 생성되는 환경(즉, App Engine, Google Kubernetes Engine의 Istio, Cloud Endpoints)을 사용하지 않는 경우 services.create 메서드를 사용하여 서비스를 만들 수 있습니다.

서비스를 수동으로 만드는 경우 Service Monitoring API를 사용하여 서비스 구조에 SLO 및 기타 서비스 모니터링 아티팩트를 수동으로 추가해야 합니다. 이러한 구조의 개요는 API의 구조를 참조하세요.

서비스를 만들려면 서비스의 표시 이름과 빈 객체가있는 custom이라는 필드를 지정해야 합니다. 원하는 경우 서비스에 사용할 서비스 ID를 지정할 수 있습니다.

프로토콜

curl를 사용하여 서비스를 만들려면 POST 메시지를 https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services 엔드포인트에 보냅니다.

  1. 서비스 ID를 제공하려면 서비스 ID에 대한 변수를 만듭니다.

    SERVICE_ID=my-test-service
        

    이 값은 URL 쿼리 매개변수 service_id에 제공됩니다.

  2. 서비스를 설명하는 요청 본문을 저장할 변수를 만듭니다.

    CREATE_SERVICE_POST_BODY=$(cat <<EOF
        {
            "displayName": "My Test Service",
            "custom": {}
        }
        EOF
        )
        
  3. 엔드포인트에 요청 본문을 게시하고 서비스 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}
        

서비스 삭제

커스텀 서비스를 삭제하려면 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는 서비스와 연결됩니다. App Engine용 Anthos Service Mesh 콘솔, Google Kubernetes Engine용 Istio, Cloud Endpoints를 사용하거나 Service Monitoring API를 사용하여 SLO를 만들 수 있습니다. 커스텀 서비스의 SLO를 만들려면 Service Monitoring API를 사용해야 합니다.

Service Monitoring API를 사용하여 서비스와 연결된 SLO를 검색하고 서비스에서 SLO를 삭제할 수도 있습니다.

서비스의 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는 서비스 내에 고유한 ID가 있으며 ID는 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 만들기

Service Monitoring API를 사용하여 SLO를 만들려면 ServiceLevelObjective 객체를 만들어 serviceLevelObjectives.create 메서드에 전달해야 합니다.

SLO의 구조에는 serviceLevelIndicator 필드 값에 대한 구조를 포함하여 많은 삽입 구조가 있습니다.

  • App Engine, Google Kubernetes Engine의 Istio, Cloud Endpoints 서비스의 경우 SLI가 사전 정의되어 있습니다. Anthos Service Mesh 콘솔을 사용하여 SLO를 만들 수 있습니다. 실적 목표 및 규정 준수 기간을 지정하기만 하면 됩니다.

    Service Monitoring API를 사용하여 SLO를 정의할 수도 있습니다.

  • 커스텀 서비스의 경우 Service Monitoring API를 사용하여 SLO를 정의해야 합니다. SLO를 지정하려면 serviceLevelIndicator 필드의 값도 만들어야 합니다. 일부 기술의 경우 서비스 수준 지표 만들기를 참조하세요.

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, 실적 목표, 규정 준수 기간에 대한 자세한 내용은 서비스 모니터링 개념을 참조하세요.

App Engine, Google Kubernetes Engine의 Istio, Cloud Endpoints 서비스의 경우 SLI 유형이 기본 SLI입니다.

커스텀 서비스의 경우 요청 기반 SLI 또는 창 기반 SLI를 만들어야 합니다. 일부 기술의 경우 서비스 수준 지표 만들기를 참조하세요.

SLO를 구축한 후에 SLO를 빌드할 수 있습니다. 다음 예에서는 기본 SLI를 사용하는 서비스의 SLO를 정의합니다. 단일 SLI에는 95% 가용성을 위한 SLO와 99% 가용성을 위한 SLO 등 여러 SLO가 있을 수 있습니다. 다음 예는 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 엔드포인트에 전송합니다.

  1. 서비스 ID의 변수를 만듭니다.

    SERVICE_ID=custom:my-test-service
        
  2. 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
        )
        
  3. 요청 본문을 엔드포인트에 게시합니다.

    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 데이터 가져오기를 참조하세요.

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