Metrics API – NGINX Management Suite에서 사용하기
해당 포스트는 NGINX Management Suite Metrics API 쿼리 파라미터를 사용하여 데이터를 세분화하기 위한 팁을 가이드합니다.
목차
1. 개요
2. Metrics API 사용법
3. Metrics API 인증
3-1. Response 이해
3-2. 측정 항목 Metrics API 쿼리
3-2-1. Names
3-2-2. Time Window
3-2-3. Metrics API 집계
3-2-4. Resolution
3-2-5. Metrics API Filter
3-2-6. GroupBy
3-2-7. Dimension
1. 개요
Metrics API 모듈을 사용하여 NGINX 인스턴스를 모니터링하고 애플리케이션의 성능을 평가할 수 있습니다. Metrics API 쿼리 파라미터를 사용하면 Tim Window, 집계함수, Resolution, Filter 등과 같은 파라미터를 기반으로 시스템 데이터를 세밀하게 조정할 수 있습니다.
이러한 쿼리 파라미터의 다양한 조합을 사용하여 다음과 같은 정보를 수집할 수 있습니다.
- 시스템 상태 확인: CPU, 메모리와 같은 다양한 시스템 메트릭을 쿼리하여 시스템의 현재 상태를 확인할 수 있습니다.
- 트래픽 동작 파악: 인스턴스에서 처리하는 HTTP/스트림 요청을 쿼리하여 트래픽 동작을 파악할 수 있습니다.
- 애플리케이션 성능 모니터링: HTTP 응답 코드를 필터링하여 성공적인 또는 실패한 요청의 수를 추적할 수 있습니다.
이러한 쿼리 파라미터의 다양한 조합을 사용하여 Metrics API를 활용하면 원하는 정보를 수집할 수 있습니다.
2. Metrics API 사용법
Metrics API를 사용하여 원하는 메트릭 이름을 쿼리하고 다음과 같은 파라미터를 기반으로 반환된 데이터를 세밀하게 조정할 수 있습니다:
- Time Window (startTime 및 endTime)
- Filter
- Dimension
- Resolution
- 그룹화 (GroupBy)
3. Metrics API 인증
Instance Manager REST API에 액세스하기 위해 기본 인증 또는 JWT 인증을 사용할 수 있습니다. 이에 대한 자세한 내용은 NGINX Management Suite FQDN 실행 패드 메뉴의 Instance Manager API Documentation에서 설명되어 있습니다.
이 가이드의 예제에서는 Metrics API 인증을 위해 “bearer” 토큰을 사용합니다. 토큰은 “Authorization” 요청 헤더 필드와 “Bearer” 스키마를 사용하여 전송됩니다.
3-1. Response 이해
Metrics API 응답은 쿼리 메타데이터와 Metrics 배열로 구성됩니다. 각 쿼리된 Metrics에 대해 하나의 배열 요소가 있습니다.
- 메트릭 개체에는 쿼리된 메트릭 이름과 메트릭과 관련된 데이터 시리즈 배열이 포함됩니다.
- 시리즈 개체는 dimension 값에 따라 메트릭 데이터를 그룹화합니다. 시리즈는 dimension (key-value map), 타임스탬프 및 타임스탬프의 메트릭 값으로 구성됩니다.
{
"metrics":[
{
"name":"http.request.count",
"series":[
{
"dimensions":{
"instance":"instance-name-1",
"nginx_id":"nginx-id-1",
},
"timestamps":[
"2020-12-10T12:00:00Z"
],
"values":[
1000
]
},
{
"dimensions":{
"instance":"instance-name-2",
"nginx_id":"nginx-id-2",
},
"timestamps":[
"2020-07-01T12:00:00Z"
],
"values":[
2000
]
}
]
}
]
}앞의 예제에서는 쿼리된 메트릭에 대해 두 개의 데이터 시리즈가 있습니다. 두 시리즈를 구분하는 요소는 “nginx_id” 값입니다. 이 값은 NGINX 메트릭을 인스턴스 중심으로 만드는 요소입니다. 인스턴스, NGINX ID 또는 시스템 ID와 같은 dimension 값에 따라 메트릭을 쉽게 구분할 수 있습니다.
지원되는 메트릭 및 dimension의 전체 목록과 자세한 설명은 Catalog API를 쿼리하여 확인할 수 있습니다.
curl -X GET --url "/api/platform/v1/analytics/catalogs/metrics" -H "Authorization: Bearer xxxxx.yyyyy.zzzzz"마찬가지로, Catalogs API를 쿼리하여 사용 가능한 dimension의 전체 목록을 얻을 수 있습니다.
curl -X GET --url "<NMS_FQDN>/api/platform/v1/analytics/catalogs/dimensions" -H "Authorization: Bearer xxxxx.yyyyy.zzzzz"여기서 `<NMS_FQDN>`은 NGINX Management Suite의 완전한 도메인 이름(FQDN)으로 대체되어야 합니다. 또한 `Authorization` 헤더에는 유효한 Bearer 토큰이 포함되어야 합니다.
3-2. 측정 항목 Metrics API 쿼리
이 목차에서는 각 쿼리 파라미터에 대한 개요와 데이터를 세분화하기 위해 파라미터를 함께 사용하는 예제를 제공합니다.
예제는 기본 사용법부터 고급 Metrics API 쿼리까지 진행됩니다.
3-2-1. Names
Names 파라미터는 Metrics API에서 유일하게 필수인 파라미터입니다.
다음 예제 쿼리는 nginx.http.request.count라는 메트릭에 대한 마지막 기록된 값을 반환합니다.
curl -X GET --url "<NMS_FQDN>/api/platform/v1/analytics/metrics?names=nginx.http.request.count" -H "Authorization: Bearer xxxxx.yyyyy.zzzzz"Dimension 값이 다른 경우 응답의 series 배열에는 여러 항목이 포함됩니다.
여러 메트릭을 동시에 쿼리할 수도 있습니다. 이를 위해 다음과 같이 메트릭 이름을 쉼표로 구분된 목록으로 제공하세요.
curl -X GET --url "<NMS_FQDN>/api/platform/v1/analytics/metrics?names=nginx.http.request.count,nginx.http.conn.accepted" -H "Authorization: Bearer xxxxx.yyyyy.zzzzz"3-2-2. Time Window
쿼리된 메트릭의 마지막 기록된 값 이상을 가져오려면 다음과 같은 Timewindow 파라미터를 사용하세요.
startTime: 메트릭을 포함할 시간 창의 시작 시간 (포함)endTime: 메트릭을 포함할 시간 창의 종료 시간 (비포함)
Timewindow 파라미터를 사용할 때 다음 규칙을 기억하세요.
endTime을 제공하는 경우 startTime도 제공해야 합니다.endTime은startTime보다 커야 합니다.startTime을 지정하고endTime을 지정하지 않으면endTime은 현재 시간으로 기본 설정됩니다.
시간은 ISO 8601 형식으로 정의하거나 offset으로 정의할 수 있습니다 (예: 2020-07-14T13:07:11Z). 오프셋은 + 또는 -로 시작하는 문자열로, 숫자와 시간 단위 (y, M, w, d, h, m, s)가 이어집니다. 현재 Timestamp를 나타내기 위해 now를 사용할 수도 있습니다.
다음 예제 요청은 지난 12시간 동안 기록된 모든 메트릭 값을 반환합니다.
curl -X GET --url "<NMS_FQDN>/api/platform/v1/analytics/metrics?names=nginx.http.request.count&startTime=now-12h" -H "Authorization: Bearer xxxxx.yyyyy.zzzzz"
다음 예제 쿼리는 완전히 정의된 Timewindow를 포함합니다.
curl -X GET --url "/api/platform/v1/analytics/metrics?names=nginx.http.request.count&startTime=now-5h&endTime=2020-07-01T09:00:00Z" -H "Authorization: Bearer xxxxx.yyyyy.zzzzz"이 경우, 응답에는 2020년 7월 1일 05:00:00부터 09:00:00까지의 메트릭이 포함됩니다.
3-2-3. Metrics API 집계
이름과 시간 창 파라미터만 사용하면 메트릭 값의 원시 데이터 포인트를 얻을 수 있습니다.
더 구조화된 응답을 얻으려면 각 쿼리된 메트릭에 대해 AVG, SUM, COUNT, MAX, MIN 또는 RATE와 같은 집계 함수를 제공할 수 있습니다.
참고:
다음 정의에서 시간 기간은 해상도(제공된 경우) 또는endTime과startTime의 차이(Resolution이 제공되지 않은 경우)를 의미합니다.
AVG: 기간 동안 메트릭 데이터 샘플의 평균 값을 계산합니다.SUM: 기간 동안 메트릭 데이터 샘플의 총합을 계산합니다.COUNT: 기간 동안 수집된 메트릭 데이터 샘플의 수를 반환합니다.MIN/MAX: 주어진 기간에서 메트릭의 최소/최대 데이터 샘플을 반환합니다.RATE: 주어진 기간의 데이터를 기반으로 초당 평균 메트릭 값을 반환합니다(해상도에 관계없이 항상 초당 기준으로 계산됩니다).
Note:
집계 함수를 사용할 때는 “startTime”를 정의해야 합니다.
예를 들어, 다음 쿼리는 마지막 12시간 동안의 지표 값들의 합계를 반환합니다. 올바른 값을 얻기 위해서는 endTime이 startTime보다 큰지 확인해야 합니다.
curl -X GET --url "/api/platform/v1/analytics/metrics?names=SUM(nginx.http.request.count)&startTime=now-12h" -H "Authorization: Bearer xxxxx.yyyyy.zzzzz"하나의 쿼리에서 집계된 지표(metric) 및 비집계된(non-aggregated) 지표를 함께 사용하는 것이 가능합니다. 이 쿼리에서 Metrics API는 각 dimension 세트마다 하나의 값만 반환합니다. 해당 값은 지난 12시간 동안 해당 지표의 모든 값의 합계입니다.
curl -X GET --url "<NMS_FQDN>/api/platform/v1/analytics/metrics?names=SUM(nginx.http.request.count),nginx.http.conn.accepted&startTime=now-12h" -H "Authorization: Bearer xxxxx.yyyyy.zzzzz"3-2-4. Resolution
만약 반환되는 데이터의 세분성을 변경하고 싶다면, resolution 파라미터를 사용할 수 있습니다. 이 파라미터는 집계 함수와 Timewindow(최소한 startTime이 제공되어야 함)와 함께 사용되어야 합니다.
resolution 파라미터는 유효한 기간이어야 합니다. 기간은 숫자로 시작하고, 그 뒤에 시간 단위인 y, M, w, d, h, m, 또는 s가 오는 문자열입니다.
다음 예시 쿼리는 세 개의 집계된 지표 값을 반환합니다. 여기서는 마지막 12시간 동안의 데이터를 1시간 단위로 요청하고 있습니다.
curl -X GET --url "/api/platform/v1/analytics/metrics?names=SUM(nginx.http.request.count)&startTime=now-12h&resolution=1h" -H "Authorization: Bearer xxxxx.yyyyy.zzzzz"3-2-5. Metrics API Filter
이 파라미터는 이름에서 알 수 있듯이, dimensions 값에 따라 결과를 필터링합니다. dimenstions 값으로 필터링하는 것은 반환되는 데이터를 더 구체적인 집합으로 세분화하는 데 도움이 됩니다.
필터 쿼리는 <dimension><operator><dimension value> 형식의 하나 이상의 조건으로 구성됩니다.
<dimension>은 dimension의 이름입니다.<operator>는 지원되는 연산자(=,!=,<,<=,>=,>,in,not) 중 하나입니다.<dimension value>는 필터링하려는 dimension의 값입니다.
예를 들어, 다음 쿼리는 앱 이름을 간단히 필터링하는 예시입니다. 이 쿼리는 마지막 12시간 동안 app1이라는 애플리케이션의 데이터를 반환합니다.
curl -X GET --url "/api/platform/v1/analytics/metrics?names=nginx.http.request.count&filter=nginx_id='nginx_id1'&startTime=now-12h" -H "Authorization: Bearer xxxxx.yyyyy.zzzzz"Tip:
조건들은 OR, AND, 그리고 ( )를 사용하여 논리식으로 결합할 수 있습니다.
값을 매칭하기 위해 와일드카드 (*) 사용이 지원됩니다.
전체 쿼리 문자열이 올바르게 처리되도록 하기 위해 조건들을 작은 따옴표로 감싸는 것을 권장합니다.
다음 예시 요청은 논리식을 사용하여 Metrics API 필터를 적용합니다.
curl -X GET --url "/api/platform/v1/analytics/metrics?names=nginx.http.request.count&filter=nginx_id='nginx_id1*' and server_zone='zone1'&startTime=now-12h" -H "Authorization: Bearer xxxxx.yyyyy.zzzzz"3-2-6. GroupBy
필터와 집계 함수만 사용해서는 특정 애플리케이션이나 환경에 대한 종합적인 정보를 얻는데 충분하지 않을 수 있습니다.
groupBy 파라미터는 지정된 dimension(들)에 따라 결과를 모으는 데 도움을 줍니다. 여러 dimension 이름을 쉼표로 구분된 목록으로 제공할 수 있습니다.
Note:
groupBy를 사용할 때는 집계 함수와 Time window(startTime은 반드시 정의해야 하며, endTime은 선택 사항입니다)을 사용해야 합니다.
요청이 집계된 메트릭과 집계되지 않은 메트릭을 포함하는 경우, groupBy 파라미터는 집계된 메트릭에만 적용됩니다.
예를 들어, 다음 쿼리는 지난 12시간 동안의 데이터를 nginx_id별로 그룹화하여 반환합니다.
curl -X GET --url "/api/platform/v1/analytics/metrics?names=SUM(nginx.http.request.count)&groupBy=nginx_id&startTime=now-12h" -H "Authorization: Bearer xxxxx.yyyyy.zzzzz"이 쿼리에 대한 API 응답은 다음과 유사합니다.
{
"metrics":[
{
"aggr": "SUM",
"name":"nginx.http.request.count",
"series":[
{
"dimensions":{
"nginx_id":"nginx-id-1",
},
"timestamps":[
"2020-12-13T12:00:00Z"
],
"values":[
1000
]
},
{
"dimensions":{
"nginx_id":"nginx-id-2",
},
"timestamps":[
"2020-12-13T12:00:00Z"
],
"values":[
2000
]
}
]
}
]
}API는 지난 12시간 동안의 데이터를 nginx_id dimension 별로 그룹화하여 반환합니다. 다른 쿼리와는 달리, API는 groupBy에서 선택한 dimension만 반환합니다. 그러나, 다른 dimension 값은 여전히 구별됩니다.
3-2-7. Dimension
각 메트릭 시리즈의 응답에 포함될 dimension을 지정하기 위해 dimensions 쿼리 파라미터를 사용할 수 있습니다.
쿼리 파라미터에 지정되지 않은 dimension은 응답에 포함되지 않습니다. 이로 인해 일부 시리즈는 같은 dimension 세트를 가지고 있지만 별도의 목록 항목으로 반환될 수 있습니다.
다음 예는 지정된 메트릭에 대한 결과를 반환하며, dimensions=nginx_id로 설정되어 있습니다.
curl -X GET --url "<NMS_FQDN>/api/platform/v1/analytics/metrics?names=SUM(nginx.http.request.count)&dimensions=nginx_id&startTime=now-12h -H "Authorization: Bearer xxxxx.yyyyy.zzzzz"{
"metrics":[
{
"aggr": "SUM",
"name":"nginx.http.request.count",
"series":[
{
"dimensions":{
"nginx_id":"nginx-id-1"
},
"timestamps":[
"2020-12-13T12:00:00Z"
],
"values":[
1000
]
},
{
"dimensions":{
"nginx_id":"nginx-id-2"
},
"timestamps":[
"2020-12-13T12:00:00Z"
],
"values":[
2000
]
}
]
}
]
}dimensions와 groupBy 파라미터를 모두 사용하는 경우, 제공된 dimensions의 목록은 groupBy에 제공된 목록의 하위 집합이어야 합니다.
다음 예는 dimensions와 groupBy를 함께 사용합니다.
curl -X GET --url "<NMS_FQDN>/api/platform/v1/analytics/metrics?names=SUM(nginx.http.request.count)&groupBy=nginx_id&dimensions=system_id&startTime=now-12h&resolution=5m" -H "Authorization: Bearer xxxxx.yyyyy.zzzzz"dimensions 파라미터를 사용하면 응답에서 dimension을 완전히 생략할 수도 있습니다. 이를 위해 dimensions를 빈 목록으로 정의하면 됩니다 (dimensions=).
이렇게 하면 http.request.count 메트릭에 대한 여러 데이터 시리즈가 생성되지만 dimension이 표시되지 않습니다. 이 자체로는 유용하지 않지만, 빈 dimensions 파라미터를 메트릭 집계와 결합하면 집계된 값이 있는 단일 시리즈를 받게 됩니다.
예를 들어, 다음 예 쿼리는 지난 3시간 동안의 http.request.count 메트릭의 모든 시리즈에서 모든 값을 합산하며, 기본 resolution를 사용합니다.
curl -X GET --url "/api/platform/v1/analytics/metrics?names=SUM(nginx.http.request.count)&startTime=now-12h&dimensions=" -H "Authorization: Bearer xxxxx.yyyyy.zzzzz"Metrics API 파라미터에 대해 자세히 알아보고 싶으신가요? NGINX STORE에 문의하여 답변을 받아보세요.
아래 뉴스레터를 구독하고 NGINX와 NGINX STORE의 최신 정보들을 빠르게 전달 받아보세요.
