API 사용량 모니터링

이 페이지에서는 API 측정항목을 사용하여 Google API 및 Google Cloud API의 사용량을 추적하고 이해하는 방법을 설명합니다.

Google API에서 생성하는 자세한 사용량 측정항목으로 다음을 수행할 수 있습니다.

Google API 사용량 추적 및 이해
애플리케이션 및 Google API의 성능 모니터링
애플리케이션과 Google API 사이의 문제 발견

문제를 해결하거나 Google의 기술 지원이 필요할 때 해결 시간을 크게 단축할 수 있습니다.

Google API가 생성하는 측정항목은 Google의 사이트 안정성 엔지니어링이 서비스 상태를 평가하는 데 사용하는 표준 신호입니다. 이러한 측정항목에는 요청 수, 오류율, 총 지연 시간, 백엔드 지연 시간, 요청 크기, 응답 크기가 포함됩니다. API 측정항목 정의는 Cloud Monitoring 문서를 참조하세요.

API 측정항목은 API 대시보드와 Cloud Monitoring 두 곳에서 확인할 수 있습니다. 표시되는 측정항목은 프로젝트에 따라 달라지며 전체 서비스 상태를 반영하지 않습니다.

API 대시보드 사용

API 측정항목을 보는 가장 간단한 방법은 Google Cloud Console의 API 대시보드를 사용하는 것입니다. 모든 API 사용량 개요를 보거나 특정 API의 사용량을 상세히 살펴볼 수 있습니다.

API 사용량 개요를 보려면 다음 안내를 따르세요.

Cloud Console의 API 및 서비스 섹션으로 이동합니다. 기본 API 대시보드가 기본적으로 표시됩니다. 이 페이지에서는 현재 프로젝트에 사용 설정되어 있는 모든 API를 비롯해 다음 측정항목에 대한 개요 차트를 표시할 수 있습니다.
- 트래픽: 사용 설정된 API에 대해 프로젝트에서 수행되거나 관련된 초당 요청 수
- 오류: 사용 설정된 API에 대한 요청 중에서 오류가 발생한 요청의 비율(%)
- 지연 시간 중앙값: 사용 설정된 API에 대한 요청의 지연 시간 중앙값(사용 가능한 경우).

특정 API에 대한 사용량 세부정보를 보는 방법:

API의 주요 API 대시보드 목록에서 보려고 하는 API를 선택합니다. 해당 API의 개요 페이지가 나타나면서 응답 코드를 기준으로 분류된 트래픽 차트가 더욱 자세하게 표시됩니다.
이것보다 더욱 자세한 사용량 정보를 원한다면 측정항목 보기를 선택합니다. 사용할 수 있는 차트가 더욱 많지만 기본적으로 다음과 같이 사전 작성된 차트가 표시됩니다.
- 응답 코드별 트래픽
- API 메서드별 오류
- 50번째, 95번째, 99번째 백분위수의 전체 지연 시간
- API 메서드별 지연 시간(중앙값)
차트를 더 추가하려면 그래프 선택 드롭다운 메뉴에서 사전 작성된 차트를 추가로 선택할 수 있습니다.

Cloud Monitoring 사용

Cloud Monitoring을 사용하면 측정항목 탐색기를 통해 사용 가능한 측정항목 데이터를 자세히 살펴보고 API 사용량을 더욱 자세히 파악할 수 있습니다. Cloud Monitoring은 다양한 측정항목을 지원하므로 필터 및 집계를 조합하여 애플리케이션 성능에 대한 새롭고 유용한 정보를 얻을 수 있습니다. 예를 들어 요청 수 측정항목을 HTTP 응답 코드 클래스에 대한 필터와 결합하면 시간 경과에 따른 오류율을 대시보드에 표시하거나, 혹은 Cloud Pub/Sub API 요청에 대한 95번째 백분위수 지연 시간을 볼 수 있습니다.

사용 가능한 측정항목

다음 표에는 사용 가능한 serviceruntime 측정항목이 나와 있습니다. API 사용량 측정항목은 consumed_api가 모니터링 리소스로 포함된 측정항목입니다.

이 표의 '측정항목 유형' 문자열 앞에 serviceruntime.googleapis.com/가 포함된 프리픽스를 붙여야 합니다. 표의 항목에서는 이 프리픽스가 생략되었습니다. 라벨을 쿼리할 때 metric.labels. 프리픽스를 사용합니다(예: metric.labels.LABEL="VALUE").

측정항목 유형 ^{시작 단계} 표시 이름
종류, 유형, 단위 모니터링 리소스	설명 라벨
`api/request_count` ^{정식 버전} 요청 수
`DELTA`, `INT64`, `1` api consumed_api produced_api	완료된 요청 수입니다. 1,800초마다 샘플링됩니다. 샘플링되면 데이터는 최대 1,800초 동안 표시되지 않습니다. `protocol`: 요청 프로토콜입니다(예: 'http', 'grpc'). `response_code`: HTTP 요청의 HTTP 응답 코드 또는 gRPC 요청의 HTTP 상응 코드입니다. https://github.com/googleapis/googleapis/blob/master/google/rpc/code.proto에서 코드 매핑을 참조하세요. `response_code_class`: HTTP 요청의 응답 코드 클래스 또는 gRPC 요청의 HTTP 상응 클래스입니다(예: '2xx', '4xx'). `grpc_status_code`: gRPC 요청의 숫자 gRPC 응답 코드 또는 HTTP 요청의 gRPC 상응 코드입니다. https://github.com/googleapis/googleapis/blob/master/google/rpc/code.proto에서 코드 매핑을 참조하세요.
`api/request_latencies` ^{정식 버전} 요청 지연 시간
`DELTA`, `DISTRIBUTION`, `s` api consumed_api produced_api	비스트리밍 요청의 지연 시간 분포(초 단위)입니다. 1,800초마다 샘플링됩니다. 샘플링되면 데이터는 최대 1,800초 동안 표시되지 않습니다.
`api/request_latencies_backend` ^{정식 버전} 요청 백엔드 지연 시간
`DELTA`, `DISTRIBUTION`, `s` api produced_api	비스트리밍 요청의 백엔드 지연 시간 분포(초 단위)입니다. 1,800초마다 샘플링됩니다. 샘플링되면 데이터는 최대 1,800초 동안 표시되지 않습니다.
`api/request_latencies_overhead` ^{정식 버전} 요청 오버헤드 지연 시간
`DELTA`, `DISTRIBUTION`, `s` api produced_api	백엔드를 제외한 비스트리밍 요청의 요청 지연 시간 분포(초 단위)입니다. 1,800초마다 샘플링됩니다. 샘플링되면 데이터는 최대 1,800초 동안 표시되지 않습니다.
`api/request_sizes` ^{정식 버전} 요청 크기
`DELTA`, `DISTRIBUTION`, `By` api consumed_api produced_api	요청 완료 시 기록된 요청 크기 분포(바이트 단위)입니다. 1,800초마다 샘플링됩니다. 샘플링되면 데이터는 최대 1,800초 동안 표시되지 않습니다.
`api/response_sizes` ^{정식 버전} 응답 크기
`DELTA`, `DISTRIBUTION`, `By` api consumed_api produced_api	요청 완료 시 기록된 응답 크기 분포(바이트 단위)입니다. 1,800초마다 샘플링됩니다. 샘플링되면 데이터는 최대 1,800초 동안 표시되지 않습니다.
`quota/allocation/usage` ^{정식 버전} 배정 할당량 사용
`GAUGE`, `INT64`, `1` consumer_quota producer_quota	사용한 총 배정 할당량입니다. 분당 1회를 초과하여 보고된 값은 삭제됩니다. 변경사항이 할당량 사용에 수신되지 않으면 마지막 값이 최소 24시간 간격으로 반복됩니다. 60초마다 샘플링됩니다. `quota_metric`: 할당량 측정항목이나 할당량 그룹의 이름입니다.
`quota/concurrent/exceeded` ^알파 동시 할당량 초과
`DELTA`, `INT64`, `1` consumer_quota	동시 할당량을 초과하는 횟수를 시도했습니다. 86,400초마다 샘플링됩니다. 샘플링되면 데이터는 최대 180초 동안 표시되지 않습니다. `limit_name`: 할당량 한도 이름입니다(예: '일일 요청' 또는 '사용 중인 IP 주소'). `quota_metric`: 할당량 측정항목이나 할당량 그룹의 이름입니다. `time_window`: 동시 작업 한도의 기간 크기입니다.
`quota/concurrent/limit` ^알파 동시 할당량 한도
`GAUGE`, `INT64`, `1` consumer_quota producer_quota	할당량의 동시 한도입니다. 86,400초마다 샘플링됩니다. 샘플링되면 데이터는 최대 180초 동안 표시되지 않습니다. `limit_name`: 할당량 한도 이름입니다(예: '일일 요청' 또는 '사용 중인 IP 주소'). `quota_metric`: 할당량 측정항목이나 할당량 그룹의 이름입니다. `time_window`: 동시 작업 한도의 기간 크기입니다.
`quota/concurrent/usage` ^알파 동시 할당량 사용량
`GAUGE`, `INT64`, `1` consumer_quota producer_quota	할당량의 동시 사용량입니다. 60초마다 샘플링됩니다. 샘플링되면 데이터는 최대 180초 동안 표시되지 않습니다. `limit_name`: 할당량 한도 이름입니다(예: '일일 요청' 또는 '사용 중인 IP 주소'). `quota_metric`: 할당량 측정항목이나 할당량 그룹의 이름입니다. `time_window`: 동시 작업 한도의 기간 크기입니다.
`quota/exceeded` ^{정식 버전} 할당량 초과 오류
`GAUGE`, `BOOL`, `1` consumer_quota	할당량 한도가 초과되어 오류가 발생했습니다. 60초마다 샘플링됩니다. `limit_name`: 할당량 한도 이름입니다(예: '일일 요청' 또는 '사용 중인 IP 주소'). `quota_metric`: 할당량 측정항목이나 할당량 그룹의 이름입니다.
`quota/limit` ^{정식 버전} 할당량 한도
`GAUGE`, `INT64`, `1` consumer_quota producer_quota	할당량 한도입니다. 86,400초마다 샘플링됩니다. `limit_name`: 할당량 한도 이름입니다(예: '일일 요청' 또는 '사용 중인 IP 주소'). `quota_metric`: 할당량 측정항목이나 할당량 그룹의 이름입니다.
`quota/rate/net_usage` ^{정식 버전} 비율 할당량 사용
`DELTA`, `INT64`, `1` consumer_quota producer_quota	총 소비 비율 할당량입니다. 60초마다 샘플링됩니다. 샘플링되면 데이터는 최대 240초 동안 표시되지 않습니다. `method`: API 메서드 이름입니다(예: 'disks.list'). `quota_metric`: 할당량 측정항목이나 할당량 그룹의 이름입니다.
`reserved/metric1` ^EARLY_ACCESS 지원 중단됨
`DELTA`, `INT64`, `1` deprecated_resource	지원 중단되었습니다. 60초마다 샘플링됩니다. 샘플링되면 데이터는 최대 180초 동안 표시되지 않습니다. `quota_name`: 지원 중단되었습니다. `credential_id`: 지원 중단되었습니다. `quota_location`: 지원 중단되었습니다.

2024년 4월 11일 19:12:46(UTC)에 생성된 표입니다.

측정항목 탐색기에서 API 측정항목을 보려면 사용된 API를 리소스 유형으로 선택한 후 serviceruntime 측정항목 중 하나를 선택합니다. 그런 다음 필터 옵션과 집계 옵션을 사용하여 데이터를 상세검색합니다. 원하는 API 사용 정보를 찾았다면 Cloud Monitoring을 사용하여 애플리케이션을 지속적으로 모니터링하고 견고하게 유지하는 데 도움이 되는 커스텀 대시보드 및 알림을 만들 수 있습니다. 수행 방법은 다음 페이지를 참조하세요.

자세한 내용은 측정항목 탐색기를 참조하세요.

API 측정항목을 사용한 문제 해결

API 측정항목은 특히 문제가 발생하여 Google에게 연락해야 할 경우에 유용하며, 지원을 요청할 필요가 전혀 없다는 것을 나타내기도 합니다. 예를 들면 다음과 같습니다.

다른 이유가 아닌 사용자 인증 정보 ID 하나로 인해 서비스 호출이 전혀 안 될 경우에는 계정에 문제가 있을 가능성이 높기 때문에 티켓을 열지 않고 직접 손쉽게 해결할 수 있습니다.
앱에 대한 문제를 해결하려고 할 때는 애플리케이션의 성능 저하와 중요한 GCP 서비스의 50번째 백분위수 지연 시간 증가의 상관관계를 찾아내야 합니다. 이때는 Google에게 연락하여 최대한 빠르게 문제를 해결할 있도록 관련 데이터를 알려야 합니다.
GCP 서비스 보고서에는 지연 시간이 양호하고 이전과 다르지 않다고 나오지만 인앱 측정항목 보고서에는 서비스 호출에 대한 지연 시간이 비정상적으로 높다고 나옵니다. 이는 네트워크에 문제가 있다는 것을 의미합니다. 이때는 네트워크 제공업체(일부 경우 Google)에게 연락하여 디버깅 프로세스를 시작하세요.

권장사항

API 측정항목이 매우 유용한 도구인 것은 사실이지만 특히 측정항목 값을 기준으로 알림을 설정할 때는 유용한 정보를 얻기 위해 반드시 고려해야 할 문제들이 있습니다. 다음은 API 측정항목 데이터를 최대한 활용하는 데 도움이 될 수 있는 권장사항입니다.

지연 시간으로 인한 문제 발생

일부 서비스는 지연 시간에 매우 민감하지만 확장이나 안정성이 더욱 중요한 서비스들도 있습니다. 예를 들어 일부 API, Cloud Storage 또는 BigQuery에서는 고객이 알아차리지 못하지만 지연 시간이 수 초로 높게 나올 수 있습니다. 이때 API 측정항목의 데이터를 사용하면 서비스에서 사용자에게 무엇이 필요한지 알 수 있습니다.

표준에서 벗어나는 변경사항 찾기

특정 측정항목 값에 대한 알림 생성을 결정하려면 먼저 실제로 비정상적인 동작이라고 간주할 수 있는 분포에 대해 생각해야 합니다. API 측정항목을 보면 대부분 서비스의 지연 시간 결과가 정규 분포에서 벗어나지 않는지 알 수 있습니다. 여기에서 정규 분포란 가운데 커다란 혹 모양을 말하며, 양쪽 측면에는 이상점이 분포합니다. 측정항목은 정규 분포를 이해하는 데 유용하기 때문에 앱이 분포 곡선 내에서 효과적으로 실행되도록 설계할 수 있습니다. 또한 분포 변화와 앱이 정상적으로 실행되지 않는 횟수의 연관성을 분석함으로써 문제의 근본 원인을 찾아내는 데도 효과적입니다. 99번째 백분위수는 중앙값과 큰 차이를 보일 수 있지만 이러한 백분위수들은 시간이 지나면서 크게 바뀌지는 않습니다.

그 밖에도 일부 요청은 다른 요청에 비해 시간이 오래 걸릴 수도 있습니다. Google 포토에 업로드되는 사진의 중앙값 크기는 4MB이지만 평소에 업로드하는 RAW 파일의 크기가 20MB라면 사진 20개를 업로드하는 평균 시간은 대부분 사용자들의 평균 시간보다 훨씬 더 오래 걸릴 수 있습니다. 하지만 자신에게는 이러한 시간이 정상적입니다.

이 모든 것을 종합해보면 RPC 또는 5xx HTTP 호출이 처음 감지되었을 때 알림을 생성하는 것은 좋지 않습니다. 대신에 애플리케이션 문제의 잠재적 원인으로 Google 서비스를 조사할 때는 반환 코드와 시간 경과에 따른 지연 시간 비율을 서로 비교한 후 애플리케이션에서 발견된 문제와 연관이 있는 동시에 지속적으로 표준에서 벗어나는 변경사항을 찾아내세요.

트래픽 속도

API 측정항목은 대용량 트래픽을 API로 전송할 때 가장 유용합니다. 서비스를 간헐적으로만 호출한다면 API 측정항목이 통계적으로 유효하지 못해 유의적인 분류 정보를 얻지 못합니다.

예를 들어 임의 서비스에 대해 99.5번째 백분위수 지연 시간을 추적하면서 시간당 호출 수가 오직 100회라면 2시간 동안 측정 결과를 지켜보더라도 99.5번째 백분위수를 나타내는 데이터 포인트는 단 하나뿐이기 때문에 API 또는 애플리케이션의 정상적인 동작 여부에 대해서 자세히 알지 못합니다. 따라서 트래픽 속도와 추적할 백분위수, 그리고 원하는 시간에서 해당하는 데이터 포인트가 충분히 생성되도록 하세요. 그렇지 않으면 모니터링 데이터가 도움이 되지 않습니다.

지원되는 API

Cloud Endpoints 및 API 게이트웨이 위에 구축된 API 외에도 모든 Google API, Google Cloud API는 API 측정항목을 지원합니다. API 사용자의 경우 API 대시보드에서 사용된 API 측정항목을 볼 수 있습니다. API 생성자는 Endpoints 대시보드에서 생성된 API 측정항목을 볼 수 있습니다.