API를 사용하여 측정항목 범위 구성

이 문서에서는 Google Cloud CLI 또는 Cloud Monitoring API를 사용하여 Google Cloud 프로젝트의 측정항목 범위를 구성하는 방법을 설명합니다. 이 페이지는 개발자 및 시스템 관리자를 대상으로 합니다.

이 페이지의 명령어는 항상 Google Cloud 프로젝트인 리소스 컨테이너를 참조합니다.

시작하기 전에

측정항목 범위 및 범위 지정 프로젝트라는 용어에 익숙하지 않다면 측정항목 범위를 참조하세요.
범위 지정 프로젝트 및 모니터링되는 프로젝트로 추가하려는 각 프로젝트에서 Identity and Access Management(IAM) 역할에 Monitoring 관리자(roles/monitoring.admin) 역할의 모든 권한이 포함되어 있는지 확인합니다. 자세한 내용은 측정항목 범위 구성을 참조하세요.
정보를 검색하는 Cloud Monitoring API의 측정항목 범위 메서드는 동기식입니다. 하지만 상태를 변경하는 API는 비동기식입니다. Google Cloud CLI 명령어는 비동기 작업이 완료될 때까지 차단됩니다. 비동기 API 메서드가 완료되는 시간을 확인하고 해당 상태를 확인하는 방법은 비동기 API 메서드를 참조하세요.
curl을 사용하여 Cloud Monitoring API를 호출하거나 이 페이지의 샘플을 사용하려면 curl 명령어 설정 단계를 완료합니다.

프로젝트를 포함하는 모든 측정항목 범위 나열

gcloud

Google Cloud 프로젝트와 같은 리소스 컨테이너의 측정항목을 볼 수 있는 측정항목 범위 목록을 가져오려면 gcloud beta monitoring metrics-scopes list 명령어를 실행합니다.

gcloud beta monitoring metrics-scopes list MONITORED_RESOURCE_CONTAINER_NAME

명령어를 실행하기 전 리소스 컨테이너의 식별자를 MONITORED_RESOURCE_CONTAINER_NAME 변수에 입력합니다. 리소스 컨테이너가 Google Cloud 프로젝트이면 projects/PROJECT_ID_OR_NUMBER를 입력합니다.

예를 들어 my-project 프로젝트가 포함된 측정항목 범위를 나열하려면 다음 명령어를 실행합니다.

gcloud beta monitoring metrics-scopes list projects/my-project

다음 응답은 my-project 프로젝트가 2개의 측정항목 범위에 포함되어 있음을 나타냅니다.

metricsScopes:
- createTime: '2018-08-06T17:13:42Z'
  name: locations/global/metricsScopes/012345012345
  updateTime: '2018-08-18T16:20:37.032928Z'
- createTime: '2021-04-13T15:37:26.869Z'
  name: locations/global/metricsScopes/9876543210
  updateTime: '2021-04-13T15:37:27.284239Z'

측정항목 범위에 대한 자세한 정보를 보려면 gcloud beta monitoring metrics-scopes describe 명령어를 실행합니다.

curl

프로젝트의 측정항목을 볼 수 있는 측정항목 범위 목록을 가져오려면 locations.global.metricsScopes.listMetricsScopesByMonitoredProject 엔드포인트에 GET 요청을 보내고 프로젝트를 지정하는 쿼리 매개변수를 포함시킵니다.

curl -H "Authorization: Bearer ${TOKEN}" \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes:listMetricsScopesByMonitoredProject?monitored_resource_container=projects/${PROJECT_ID_OR_NUMBER}

성공하면 응답이 MetricsScope 객체의 배열입니다.

이 메서드를 사용하면 범위 지정 프로젝트의 감사 로그에 항목이 작성되지 않습니다. 이러한 작업을 감사 로그에 기록하려면 Cloud Resource Manager API에 데이터 읽기를 사용 설정합니다. 자세한 내용은 데이터 액세스 감사 로그 구성을 참조하세요.

측정항목 범위의 세부정보 가져오기

gcloud

측정항목 범위에 대한 자세한 정보를 가져오려면 gcloud beta monitoring metrics-scopes describe 명령어를 실행합니다.

gcloud beta monitoring metrics-scopes describe METRICS_SCOPE_ID

명령어를 실행하기 전 측정항목 범위의 정규화된 이름 이름을 METRICS_SCOPE_ID 변수에 입력합니다. 다음은 정규화된 이름의 예시입니다.

locations/global/metricsScopes/012345012345

다음은 응답의 예시입니다. 이 예시에서 측정항목 범위에는 프로젝트가 하나 있으며 측정항목 범위와 프로젝트의 ID는 동일합니다.

createTime: '2018-08-06T17:13:42Z'
monitoredProjects:
- createTime: '2018-08-06T17:13:42Z'
  name: locations/global/metricsScopes/012345012345/projects/012345012345
name: locations/global/metricsScopes/012345012345
updateTime: '2018-08-18T16:20:37.032928Z'

ID에서 Google Cloud 프로젝트를 식별하려면 gcloud projects list 명령어를 실행하고 프로젝트 ID로 필터링합니다. 예를 들어 012345012345 프로젝트 이름을 가져오려면 다음 명령어를 실행합니다.

gcloud projects list --filter="012345012345" -format="value(NAME)"

curl

측정항목 범위에 대한 정보를 가져오려면 locations.global.metricsScopes.get 엔드포인트에 GET 요청을 전송합니다.

curl -H "Authorization: Bearer ${TOKEN}" \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes/${SCOPING_PROJECT_ID_OR_NUMBER}

성공하면 응답이 MetricsScope 객체입니다.

측정항목 범위에 프로젝트 추가

gcloud

Google Cloud 프로젝트와 같은 리소스 컨테이너를 측정항목 범위에 추가하려면 gcloud beta monitoring metrics-scopes create 명령어를 실행합니다.

gcloud beta monitoring metrics-scopes create MONITORED_RESOURCE_CONTAINER_NAME --project=SCOPING_PROJECT_ID_OR_NUMBER

위 명령어를 실행하기 전에 다음을 수행합니다.

측정항목 범위를 수정할 Google Cloud 프로젝트의 이름 또는 ID를 SCOPING_PROJECT_ID_OR_NUMBER 변수에 입력합니다.
리소스 컨테이너의 식별자를 MONITORED_RESOURCE_CONTAINER_NAME 변수에 입력합니다. 리소스 컨테이너가 Google Cloud 프로젝트이면 projects/PROJECT_ID_OR_NUMBER를 입력합니다.

예를 들어 다음 명령어는 my-monitored-project 프로젝트를 my-staging-projects라는 프로젝트의 측정항목 범위에 추가합니다.

gcloud beta monitoring metrics-scopes create projects/my-monitored-project --project=my-staging-projects

이전 명령어에 대한 응답은 명령어가 성공적으로 완료되었음을 확인합니다.

Created monitored project [locations/global/metricsScopes/my-staging-projects/projects/my-monitored-project].

curl

측정항목 범위에 Google Cloud 프로젝트를 추가하려면 locations.global.metricsScopes.projects.create 엔드포인트로 POST 요청을 전송합니다. 다음 예시에서는 MONITORED_PROJECT_ID_OR_NUMBER 환경 변수로 식별된 프로젝트가 모니터링되는 프로젝트로 추가됩니다.

curl -H "Authorization: Bearer ${TOKEN}" \
-H "Content-Type: application/json" -X POST \
-d "{'name': 'locations/global/metricsScopes/${SCOPING_PROJECT_ID_OR_NUMBER}/projects/${MONITORED_PROJECT_ID_OR_NUMBER}'}" \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes/${SCOPING_PROJECT_ID_OR_NUMBER}/projects

이 비동기 메서드의 응답은 Operation 객체입니다.

이 메서드를 호출하는 애플리케이션은 Operation.done 필드 값이 true가 될 때까지 operation.get 엔드포인트를 폴링해야 합니다. Operation.done 필드가 false로 설정되면 작업이 진행 중임을 나타냅니다. 자세한 내용은 비동기 API 명령어를 참조하세요.

다음은 모니터링되는 프로젝트 추가가 성공할 때의 응답 예시입니다.

{
  "name": "operations/6915efde-1915-400a-ad49-7b62041d9bd2",
  "metadata": {
    "@type": "type.googleapis.com/google.monitoring.metricsscope.v1.OperationMetadata",
    "state": "DONE",
    ...
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.monitoring.metricsscope.v1.MonitoredProject",
    "name": "locations/global/metricsScopes/012012012012/projects/678678678678",
    "provider": "GCP",
    "providerAccountId": "...",
    ...
  }
}

이전 응답에서는 Operation.done 필드가 true로 설정되었습니다. 이 값은 명령어가 완료되었음을 나타냅니다. 명령어가 성공적으로 완료되었으므로 Operation.response 필드가 설정되고 해당 값이 MonitoredProject 객체입니다. response.name 필드에는 범위 지정 프로젝트 및 모니터링되는 프로젝트의 식별자가 포함됩니다. providerAccountId 필드에는 모니터링되는 프로젝트의 이름이 나열됩니다.

이 메서드를 호출하면 범위 지정 프로젝트의 감사 로그에 있는 항목이 표시됩니다. Google Cloud Console은 이 API 메서드를 호출하지 않습니다. 따라서 Google Cloud Console을 사용할 때 측정항목 범위에 적용된 수정 사항이 감사 로그에 기록되지 않습니다.

측정항목 범위에서 프로젝트 삭제

gcloud

측정항목 범위에서 Google Cloud 프로젝트와 같은 리소스 컨테이너를 삭제하려면 gcloud beta monitoring metrics-scopes delete 명령어를 실행합니다.

gcloud beta monitoring metrics-scopes delete MONITORED_RESOURCE_CONTAINER_NAME --project=SCOPING_PROJECT_ID_OR_NUMBER

위 명령어를 실행하기 전에 다음을 수행합니다.

측정항목 범위를 수정할 Google Cloud 프로젝트의 이름 또는 ID를 SCOPING_PROJECT_ID_OR_NUMBER 변수에 입력합니다.
리소스 컨테이너의 식별자를 MONITORED_RESOURCE_CONTAINER_NAME 변수에 입력합니다. 리소스 컨테이너가 Google Cloud 프로젝트이면 projects/PROJECT_ID_OR_NUMBER를 입력합니다.

예를 들어 다음 명령어는 my-staging-projects라는 프로젝트의 측정항목 범위에서 my-monitored-project 프로젝트를 삭제합니다.

gcloud beta monitoring metrics-scopes delete projects/my-monitored-project --project=my-staging-projects

이전 명령어에 대한 응답은 명령어가 성공적으로 완료되었음을 확인합니다.

Deleted monitored project [locations/global/metricsScopes/my-staging-projects/projects/my-monitored-project].

범위 지정 프로젝트가 MONITORED_RESOURCE_CONTAINER_NAME 변수로 지정된 프로젝트를 모니터링하지 못할 때 다음 오류가 보고됩니다.

NOT_FOUND: Requested entity was not found.

curl

측정항목 범위에서 Google Cloud 프로젝트를 삭제하려면 locations.global.metricsScopes.projects.delete 엔드포인트에 DELETE 요청을 보냅니다.

curl -H "Authorization: Bearer ${TOKEN}" -X DELETE \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes/${SCOPING_PROJECT_ID_OR_NUMBER}/projects/${MONITORED_PROJECT_ID_OR_NUMBER}

이 비동기 메서드에 대한 응답은 Operation 객체입니다.

다음은 모니터링 프로젝트의 삭제에 성공한 응답의 예시입니다.

{
  "name": "operations/4367ff34-0ff0-4767-b8d3-0638e30f077c",
  "metadata": {
    "@type": "type.googleapis.com/google.monitoring.metricsscope.v1.OperationMetadata",
    "state": "DONE",
    ...
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.protobuf.Empty"
  }
}

이전 응답에서는 Operation.done 필드가 true로 설정되었습니다. 이 값은 명령어가 완료되었음을 나타냅니다. 명령어가 성공적으로 완료되었으므로 Operation.response 필드가 설정되고 @type 필드가 포함됩니다.

비동기 API 메서드

모니터링되는 프로젝트를 측정항목 범위에 추가하는 명령어와 같이 시스템 상태를 변경하는 Cloud Monitoring API의 모든 측정항목 범위 메서드는 비동기식입니다. 이러한 명령어의 경우 명령어 응답이 Operation 객체입니다.

비동기 API 메서드를 호출하는 애플리케이션은 Operation.done 필드의 값이 true일 때까지 operation.get 엔드포인트를 폴링해야 합니다.

done이 false이면 작업이 진행 중인 것입니다.

상태 정보를 새로고침하려면 GET 요청을 operation.get 엔드포인트에 보냅니다.
```
curl -H "Authorization: Bearer ${TOKEN}" \
https://monitoring.googleapis.com/v1/${OPERATION_NAME}
```
이전 명령어에서 OPERATION_NAME은 Operation.name 필드의 값을 저장하는 환경 변수입니다.
done이 true이면 작업이 완료되고 error 또는 response 필드가 설정됩니다.
- error: 설정된 경우 비동기 작업이 실패합니다. 이 필드의 값은 gRPC 오류 코드 및 오류 메시지를 포함하는 Status 객체입니다.
- response: 설정된 경우 비동기 작업이 성공적으로 완료되고 값에 결과가 반영됩니다.

`curl` 명령어 설정

이 섹션에서는 이 문서에서 curl 명령어를 만들기 위해 사용되는 단계를 설명합니다. 이 페이지의 각 curl 명령어에는 인수 집합과 API 리소스의 URL이 포함됩니다.

curl -H "Authorization: Bearer ${TOKEN}" <other_args> \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes/<resource>

curl 명령어 만들기를 단순화하려면 이러한 환경 변수를 설정합니다.

범위 지정 프로젝트 ID 또는 번호를 저장하도록 환경 변수를 만듭니다.
```
SCOPING_PROJECT_ID_OR_NUMBER=SCOPING_PROJECT_ID_OR_NUMBER
```
선택사항입니다. 모니터링되는 프로젝트를 추가하거나 삭제하려면 모니터링되는 프로젝트 ID 또는 번호로 환경 변수를 구성합니다.
```
MONITORED_PROJECT_ID_OR_NUMBER=MONITORED_PROJECT_ID_OR_NUMBER
```
Google Cloud CLI에 인증합니다.
```
gcloud auth login
```
선택사항입니다. 각 gcloud 명령어로 프로젝트 ID를 지정하지 않으려면 gcloud CLI를 사용하여 프로젝트 ID를 기본값으로 설정합니다.
```
gcloud config set project ${SCOPING_PROJECT_ID_OR_NUMBER}
```
승인 토큰을 만들고 환경 변수에 저장합니다.
```
TOKEN=`gcloud auth print-access-token`
```
토큰은 제한 시간 동안 유효합니다. 작업한 명령어에서 사용자가 인증되지 않았다고 갑자기 보고하면 이 명령어를 다시 실행합니다.
액세스 토큰을 받았는지 확인하려면 TOKEN 변수를 출력합니다.
```
echo ${TOKEN}
ya29.GluiBj8o....
```

HTTP 요청의 유형을 지정하기 위해 다른 인수를 지정해야 할 수도 있습니다(예: -X DELETE). 기본 요청은 GET이므로 예시에서는 이를 지정하지 않습니다.

다음 단계

Terraform과 함께 Google Cloud를 사용하는 방법은 다음 리소스를 참조하세요.

API를 사용하여 측정항목 범위 구성

시작하기 전에

프로젝트를 포함하는 모든 측정항목 범위 나열

gcloud

curl

측정항목 범위의 세부정보 가져오기

gcloud

curl

측정항목 범위에 프로젝트 추가

gcloud

curl

측정항목 범위에서 프로젝트 삭제

gcloud

curl

비동기 API 메서드

curl 명령어 설정

다음 단계

`curl` 명령어 설정