이 페이지는 Apigee 및 Apigee Hybrid에 적용됩니다.
Apigee Edge 문서 보기
Apigee는 API 전반에 걸쳐 있는 다양한 운영 및 비즈니스 데이터를 기록합니다. 이 데이터에서 파생된 측정항목은 운영 모니터링 및 비즈니스 모니터링에 유용합니다. 예를 들어 Apigee 애널리틱스를 사용하면 성능이 높거나 낮은 API, 가장 가치가 높은 트래픽을 유입시키는 개발자, 백엔드 서비스에서 가장 많은 문제를 일으키는 앱을 확인할 수 있습니다.
이 측정항목 데이터에 손쉽게 액세스하려면 자동화 클라이언트 또는 스크립트를 사용하여 주기적으로 측정항목을 검색하는 등 특정 분석 함수를 자동화해야 할 때 측정항목 API를 사용합니다. API를 사용하여 포털 또는 커스텀 앱에 삽입할 수 있는 커스텀 위젯 형식으로 자체 시각화를 빌드할 수도 있습니다.
Apigee UI에서 애널리틱스를 사용하는 방법은 Apigee 애널리틱스 개요를 참조하세요.
Metrics API 정보
Metrics API를 사용하는 방법에는 두 가지가 있습니다.
- 시간, 일, 주 등 특정 기간 동안 조직 및 환경의 측정항목을 가져옵니다.
이 메서드는 전체 조직 및 환경에 대한 원시 측정항목을 반환합니다.
예를 들어 지난주에 대해 다음 정보를 얻을 수 있습니다.
- 정책 오류 수
- 평균 응답 시간
- 총 트래픽
일정 기간의 조직 및 환경에 대한 측정기준별로 구성된 측정항목을 가져옵니다.
예를 들어 측정기준을 사용하여 API 제품, API 프록시, 개발자 이메일(AppGroup ID일 수도 있음)별로 지난주의 측정항목을 그룹화할 수 있습니다.
- API 제품당 정책 오류 수
- API 프록시당 평균 응답 시간
- 개발자 이메일당 총 트래픽
반환되는 결과를 관리하기 위해 Metrics API는 다음 기능을 지원합니다.
자세한 내용은 Metrics API 참조를 참조하세요.
Metrics API 사용 시작하기
Metrics API의 요청 URL은 다음과 같습니다.
https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats[dimension]
예를 들어 API 프록시별로 그룹화된 측정항목을 가져오려면 다음 URL을 사용하여 Apigee API를 호출합니다.
https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/apiproxy?timeRange=07/21/2018+00:00:00~08/23/2018+00:00:00
지정된 기간 동안 전체 조직 및 환경의 원시 측정항목을 반환하는 측정기준을 생략합니다.
https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats?timeRange=07/21/2019+00:00:00~08/23/2018+00:00:00
반환할 측정항목 지정
select쿼리 매개변수를 사용하여 검색할 측정항목과 선택적인 집계 함수를 다음 형식으로 지정합니다.?select=metric
또는
?select=aggFunction(metric)
각 항목의 의미는 다음과 같습니다.
- metric은 반환할 데이터를 지정합니다. 예를 들어 API 요청, 캐시 적중 또는 정책 오류 수입니다.
select쿼리 매개변수에 사용할 측정항목 이름을 지정하는 표는 측정항목을 참조하세요. aggFunction은 측정항목에 대해 실행되는 선택적 집계 함수를 지정합니다. 예를 들어 다음과 같은 집계 함수를 처리 지연 시간 측정항목과 함께 사용할 수 있습니다.
avg: 평균 처리 지연 시간을 반환합니다.min: 최소 처리 지연 시간을 반환합니다.max: 최대 처리 지연 시간을 반환합니다.-
sum: 모든 처리 지연 시간의 합계를 반환합니다. -
p50:percentile(latency_metric,50)&aggTable=agg_percentile을 사용하여 계산된 처리 지연 시간의 50번째 백분위수를 반환합니다. -
p95:percentile(latency_metric,95)&aggTable=agg_percentile을 사용하여 계산된 처리 지연 시간의 95번째 백분위수를 반환합니다. -
p99:percentile(latency_metric,99)&aggTable=agg_percentile을 사용하여 계산된 처리 지연 시간의 99번째 백분위수를 반환합니다.
latency_metric은 다음 중 하나일 수 있습니다.total_response_timetarget_response_timeresponse_processing_latencyrequest_processing_latency
일부 측정항목은 모든 집계 함수를 지원하지 않습니다. 측정항목 문서에는 측정항목 이름 및 측정항목에서 지원하는 함수(
sum,avg,min,max)를 지정하는 테이블이 포함되어 있습니다.
예를 들어 API 프록시 요청인 초당 평균 트랜잭션 수를 반환하려면 다음과 같이 하세요.
?select=tps
이 예시에는 집계 함수가 필요하지 않습니다. 다음 예시에서는 집계 함수를 사용하여 캐시 적중 합계를 반환합니다.
?select=sum(cache_hit)
단일 API 호출에 여러 측정항목을 반환할 수 있습니다. 정책 오류 합계 및 평균 요청 크기의 측정항목을 가져오려면 쉼표로 구분된 측정항목 목록을 사용하여
select쿼리 매개변수를 설정합니다.?select=sum(policy_error),avg(request_size)
기간 지정
측정항목 API는 지정된 기간 동안의 데이터를 반환합니다.
timeRange(최대 6개월) 쿼리 매개변수를 사용하여 기간을 다음 형식으로 지정합니다.?timeRange=MM/DD/YYYY%20HH:MM~MM/DD/YYYY%20HH:MM
HH:MM전에%20을 확인하세요.MM/DD/YYYY+HH:MM~MM/DD/YYYY+HH:MM와 같이timeRange매개변수에는 URL 인코딩 공백 문자가HH:MM또는+문자 앞에 있어야 합니다.예를 들면 다음과 같습니다.
?timeRange=03/01/2018%2000:00~03/30/2018%2023:59
24:00는 00:00으로 반올림되므로 사용하지 마세요. 대신 23:59를 사용하세요.
Metrics API 호출 예시
이 섹션에서는 Metrics API를 사용하는 예시를 제공합니다. 추가 예시는 Metrics API 예시를 참조하세요.
API에 대한 한 달간의 총 호출 수를 반환합니다.
조직 및 환경에서 모든 API에 대한 한 달간의 총 호출 수를 반환하려면 다음과 비슷한 호출을 사용합니다.
curl -v "https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/?select=sum(message_count)&timeRange=03/01/2018%2000:00~03/31/2018%2023:59" \ -H "Authorization: Bearer $TOKEN"
$TOKEN를 OAuth 2.0 액세스 토큰 가져오기에 설명된 대로 OAuth 2.0 액세스 토큰으로 설정합니다. 이 예시에서 사용된curl옵션에 대한 자세한 내용은 curl 사용을 참조하세요. 사용할 수 있는 환경 변수에 대한 설명은 Apigee API 요청에 대한 환경 변수 설정을 참고하세요.다음은 응답의 예시입니다.
{ "environments": [ { "metrics": [ { "name": "sum(message_count)", "values": [ "7.44944088E8" ] } ], "name": "prod" } ], ... }2일간의 API 프록시당 총 메시지 수를 반환합니다.
이 예시에서는 2일 동안 모든 API 프록시에서 수신한 요청 수의 측정항목을 반환합니다.
select쿼리 매개변수는 측정기준apiproxy의 측정항목message_count에 대한 집계 함수sum을 정의합니다. 이 보고서는 2018년 6월 20일부터 2018년 6월 21일 사이에 수신된 트래픽의 모든 API에 대한 요청 메시지 처리량을 반환합니다.curl https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/apiproxy?"select=sum(message_count)&timeRange=06/20/2018%2000:00~06/21/2018%2023:59" \ -H "Authorization: Bearer $TOKEN"
$TOKEN를 OAuth 2.0 액세스 토큰 가져오기에 설명된 대로 OAuth 2.0 액세스 토큰으로 설정합니다. 이 예시에서 사용된curl옵션에 대한 자세한 내용은 curl 사용을 참조하세요. 사용할 수 있는 환경 변수에 대한 설명은 Apigee API 요청에 대한 환경 변수 설정을 참고하세요.다음은 응답의 예시입니다.
{ "environments" : [ { "dimensions" : [ { "metrics" : [ { "name" : "sum(message_count)", "values" : [ { "timestamp" : 1498003200000, "value" : "1100.0" } ] } ], "name" : "target-reroute" } ], "name" : "test" } ]... }이 응답은 2018년 6월 20일부터 2018년 6월 21일 사이의 테스트 환경에서 실행 중인 'target-reroute'라는 1개의 API 프록시에서 1,100개의 메시지를 수신했음을 나타냅니다.
다른 측정기준에 대한 측정항목을 가져오려면 다른 측정기준을 URI 매개변수로 지정하세요. 예를 들어
developer_app측정기준을 지정하여 개발자 앱의 측정항목을 검색할 수 있습니다. 다음 API 호출은 지정된 시간 간격 동안 모든 앱에서 발생한 총 처리량(수신된 메시지)을 반환합니다.curl https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/developer_app?"select=sum(message_count)&timeRange=06/20/2018%2000:00~06/21/2018%2023:59&timeUnit=day" \ -H "Authorization: Bearer $TOKEN"
다음은 응답의 예시입니다.
{ "environments": [ { "dimensions": [ { "metrics": [ { "name": "sum(message_count)", "values": [ { "timestamp": 1498003200000, "value": "886.0" } ] } ], "name": "Test-App" }, { "metrics": [ { "name": "sum(message_count)", "values": [ { "timestamp": 1498003200000, "value": "6645.0" } ] } ], "name": "johndoe_app" }, { "metrics": [ { "name": "sum(message_count)", "values": [ { "timestamp": 1498003200000, "value": "1109.0" } ] } ], "name": "marys_app" } ]... }상대적 순위로 결과 정렬
측정항목을 가져오는 대부분의 경우 전체 데이터 세트의 하위 집합 결과만 가져오려고 할 것입니다. 일반적으로 '상위 10개'(예: '가장 느린 API 상위 10개', '활성 앱 상위 10개')에 대한 결과를 가져와야 합니다. 이렇게 하려면 요청의 일부로
topk쿼리 매개변수를 사용하면 됩니다.예를 들어 처리량을 기준으로 측정한 최고의 개발자는 누구인지 또는 지연 시간별 최하 성능(예시: '가장 느린')의 대상 API는 무엇인지 알고 싶을 수 있습니다.
topk('상위 k' 항목)를 사용하면 특정 측정항목의 가장 높은 값과 관련된 항목을 보고할 수 있습니다. 이렇게 하면 특정 조건의 예시를 보여주는 항목 목록에 대한 측정항목을 필터링할 수 있습니다.예를 들어 지난 주에 가장 많은 오류가 발생한 대상 URL을 찾으려면
topk매개변수를 요청에 추가하고1값을 사용합니다.curl https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/target_url?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&sortby=sum(is_error)&topk=1" \ -H "Authorization: Bearer $TOKEN"
$TOKEN를 OAuth 2.0 액세스 토큰 가져오기에 설명된 대로 OAuth 2.0 액세스 토큰으로 설정합니다. 이 예시에서 사용된curl옵션에 대한 자세한 내용은 curl 사용을 참조하세요. 사용할 수 있는 환경 변수에 대한 설명은 Apigee API 요청에 대한 환경 변수 설정을 참고하세요.다음은 응답의 예시입니다.
{ "environments": [ { "dimensions": [ { "metrics": [ { "name": "sum(is_error)", "values": [ { "timestamp": 1494201600000, "value": "12077.0" } ] } ], "name": "http://api.company.com" } ]... }이 요청의 결과는 가장 버그가 많은 대상 URL이
http://api.company.com임을 나타내는 측정항목 집합입니다.또한
topk매개변수를 사용하여 처리량이 가장 높은 API를 정렬할 수도 있습니다. 다음 예시에서는 지난 1주간 가장 높은 처리량에 따라 정의된 최고 순위 API를 기준으로 측정항목을 검색합니다.curl https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV}/stats/apiproxy?"select=sum(message_count)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=day&sortby=sum(message_count)&sort=DESC&topk=1" \ -H "Authorization: Bearer $TOKEN"
다음은 응답의 예시입니다.
{ "environments": [ { "dimensions": [ { "metrics": [ { "name": "sum(message_count)", "values": [ { "timestamp": 1494720000000, "value": "5750.0" }, { "timestamp": 1494633600000, "value": "5752.0" }, { "timestamp": 1494547200000, "value": "5747.0" }, { "timestamp": 1494460800000, "value": "5751.0" }, { "timestamp": 1494374400000, "value": "5753.0" }, { "timestamp": 1494288000000, "value": "5751.0" }, { "timestamp": 1494201600000, "value": "5752.0" } ] } ], "name": "testCache" } ], "name": "test" } ]... }결과 필터링
더 세분화된 결과를 확인하려면 반환되는 데이터를 제한하도록 결과를 필터링할 수 있습니다. 필터를 사용하는 경우 측정기준을 필터 속성으로 사용해야 합니다.
예를 들어 요청의 HTTP 동사로 필터링된 백엔드 서비스에서 오류 수를 검색해야 한다고 가정해 보겠습니다. 목표는 POST 및 PUT 요청이 백엔드 서비스당 생성하는 오류 수를 확인하는 것입니다. 이렇게 하려면 측정기준
request_verb와 함께target_url측정기준을 사용합니다.curl https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/target_url?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&filter=(request_verb%20in%20'POST','PUT')" \ -H "Authorization: Bearer $TOKEN"
$TOKEN를 OAuth 2.0 액세스 토큰 가져오기에 설명된 대로 OAuth 2.0 액세스 토큰으로 설정합니다. 이 예시에서 사용된curl옵션에 대한 자세한 내용은 curl 사용을 참조하세요. 사용할 수 있는 환경 변수에 대한 설명은 Apigee API 요청에 대한 환경 변수 설정을 참고하세요.다음은 응답의 예시입니다.
{ "environments" : [ { "dimensions" : [ { "metrics" : [ { "name" : "sum(is_error)", "values" : [ { "timestamp" : 1519516800000, "value" : "1.0" } ] } ], "name" : "testCache" } ], "name" : "test" } ]... }결과를 페이지로 나누기
프로덕션 환경에서 Apigee 애널리틱스 API에 대한 일부 요청은 대용량 데이터 세트를 반환합니다. API는 UI 기반 애플리케이션의 컨텍스트에서 대용량 데이터 세트를 쉽게 표시할 수 있도록 기본적으로 페이지로 나누기를 지원합니다.
결과를 페이지로 나누려면 항목의 일관된 정렬 순서를 보장하기 위해
sortby정렬 매개변수와 함께offset및limit쿼리 매개변수를 사용합니다.예를 들어 다음 요청은 지난 주에 제품 환경의 모든 API에 대한 모든 오류에 대한 측정항목을 검색하기 때문에 대규모 데이터 세트를 반환할 가능성이 높습니다.
curl https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/apiproxy?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&sortby=sum(is_error)" \ -H "Authorization: Bearer $TOKEN"
$TOKEN를 OAuth 2.0 액세스 토큰 가져오기에 설명된 대로 OAuth 2.0 액세스 토큰으로 설정합니다. 이 예시에서 사용된curl옵션에 대한 자세한 내용은 curl 사용을 참조하세요. 사용할 수 있는 환경 변수에 대한 설명은 Apigee API 요청에 대한 환경 변수 설정을 참고하세요.UI 기반 애플리케이션이 페이지당 50개의 결과를 합당하게 표시할 수 있는 경우 한도를 50으로 설정할 수 있습니다. 0이 첫 번째 항목으로 집계되므로 다음 호출은 항목을 0에서 49번까지 내림차순으로 반환합니다(기본값은
sort=DESC).curl https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/apiproxy?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&sortby=sum(is_error)&limit=50&offset=0" \ -H "Authorization: Bearer $TOKEN"
결과의 두 번째 '페이지'의 경우 다음과 같이 오프셋 쿼리 매개변수를 사용합니다. 한도와 오프셋은 동일합니다. 이는 0이 첫 번째 항목으로 집계되기 때문입니다. 한도가 50이고 오프셋이 0인 경우 0~49의 항목이 반환됩니다. 오프셋이 50인 경우 50~99의 항목이 반환됩니다.
curl https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/apiproxy?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&sortby=sum(is_error)&limit=50&offset=50" \ -H "Authorization: Bearer $TOKEN"