PromQL 빠르게 시작하기¶

PromQL은 Prometheus 모니터링 시스템의 쿼리 언어로, 문법이 간결하면서도 강력한 기능을 제공합니다. 기존 SQL 언어와 달리 PromQL의 문법 구조는 다소 독특합니다.

이 글에서는 PromQL의 일반적인 쿼리 사용법을 소개합니다.

PromQL로 시계열 선택하기¶

PromQL에서 시계열을 선택하는 것은 매우 간단합니다. 시계열 이름을 직접 쓰면 됩니다. 예를 들어, 다음 쿼리는 이름이 node_network_receive_bytes_total인 모든 시계열을 반환합니다:

node_network_receive_bytes_total

이 이름은 node_exporter metric에 해당하며, 다양한 네트워크 인터페이스가 수신한 바이트 수를 기록합니다. 간단한 쿼리는 예를 들어 eth0, eth1, eth2 네트워크 인터페이스에 대해 다음과 같은 레이블이 있는 시계열을 반환할 수 있습니다:

node_network_receive_bytes_total{device="eth0"}
node_network_receive_bytes_total{device="eth1"}
node_network_receive_bytes_total{device="eth2"}

각 레이블은 중괄호로 묶이며, 예를 들어 {device="eth0"}, {device="eth1"}, {device="eth2"}와 같습니다.

Measurement¶

Guance에서는 모든 메트릭이 Measurement에 속하며, Measurement 단위로 메트릭의 라이프사이클을 관리합니다. 반면 Prometheus에는 Measurement라는 개념이 없습니다. Datakit을 통해 데이터를上报할 때 수동으로 Measurement를 구성하거나 접두사에 따라 자동으로 생성할 수 있습니다.

node_network_receive_bytes_total 메트릭을 예로 들어, Datakit 자동 규칙을 통해 생성한다고 가정하면 이 메트릭은 Measurement와 Field 두 부분으로 나뉘며, 각각 node와 network_receive_bytes_total이 됩니다.

쿼리할 때도 약간 변경됩니다. 다른 네트워크 인터페이스를 예로 계속 들어보겠습니다:

node:network_receive_bytes_total{device="eth0"}
node:network_receive_bytes_total{device="eth1"}
node:network_receive_bytes_total{device="eth2"}

이제 메트릭 이름 필터 형식이 measurement:field로 변경되었으며, 중간에 콜론으로 연결되어 있음을 확인할 수 있습니다.

레이블로 필터링하기¶

단일 메트릭 이름은 위 예제와 같이 서로 다른 레이블 집합을 가진 여러 시계열에 해당할 수 있습니다. {device="eth1"}와만 일치하는 시계열을 선택하려면 어떻게 해야 할까요? 쿼리에 원하는 레이블을 명시하면 됩니다:

node:network_receive_bytes_total{device="eth1"}

eth1을 제외한 모든 장치의 시계열을 선택하려면 쿼리에서 =를 !=로 바꾸면 됩니다:

node:network_receive_bytes_total{device!="eth1"}

eth로 시작하는 장치의 시계열을 선택하려면 어떻게 해야 할까요? 정규 표현식을 사용하면 됩니다:

node:network_receive_bytes_total{device=~"eth.+"}

필터에는 Go와 호환되는 모든 정규 표현식(RE2라고도 함)이 포함될 수 있습니다.

eth로 시작하지 않는 장치의 모든 시계열을 선택하려면 =~를 !~로 바꾸면 됩니다:

node:network_receive_bytes_total{device!~"eth.+"}

여러 레이블로 필터링하기¶

레이블 필터를 조합하여 사용할 수 있습니다. 예를 들어, 다음 쿼리는 eth로 시작하는 장치의 node42:9100 인스턴스에 있는 시계열만 반환합니다:

node:network_receive_bytes_total{instance="node42:9100", device=~"eth.+"}

레이블 필터는 and 연산자로 조합됩니다. 즉, "이 필터와 일치하고 저 필터와도 일치하는 시계열을 반환"합니다. or 연산자는 어떻게 구현할까요? 현재 PromQL은 레이블 필터 조합을 위한 or 연산자가 부족하지만, 대부분의 경우 정규 표현식으로 대체할 수 있습니다. 예를 들어, 다음 쿼리는 eth1 또는 lo 장치의 시계열을 반환합니다:

node:network_receive_bytes_total{device=~"eth1|lo"}

정규 표현식으로 메트릭 또는 Measurement 이름 필터링하기¶

Measurement와 메트릭 이름은 사실 특별한 이름을 가진 일반 레이블입니다: __measurement__와 __field__입니다. 따라서 이러한 레이블에 정규 표현식을 적용하여 원하는 데이터를 필터링할 수 있습니다.

예를 들어, node Measurement에서 network_receive_bytes_total 또는 network_transmit_bytes_total 메트릭 이름을 가진 모든 시계열을 쿼리합니다:

{__measurement__="node", __field__=~"network_(receive|transmit)_bytes_total"}

또는 node1과 node2 두 Measurement에 분산된 network_receive_bytes_total 또는 network_transmit_bytes_total 메트릭 이름의 시계열을 쿼리합니다:

{__measurement__=~"node1|node2", __field__=~"network_(receive|transmit)_bytes_total"}

현재 데이터와 과거 데이터 비교하기¶

PromQL은 과거 데이터를 쿼리하여 현재 데이터와 조합하거나 비교할 수 있습니다. 쿼리에 offset을 추가하면 됩니다. 예를 들어, 다음 쿼리는 node:network_receive_bytes_total 이름의 모든 시계열에 대해 일주일 전 데이터를 반환합니다:

node:network_receive_bytes_total offset 7d

다음 쿼리는 현재 GC 오버헤드가 1시간 전 GC 오버헤드의 1.5배를 초과하는 지점을 반환합니다:

go:memstats_gc_cpu_fraction > 1.5 * (go:memstats_gc_cpu_fraction offset 1h)

속도 계산¶

위의 모든 쿼리에 대한 차트가 계속 증가하는 선을 그리는 것을 확인할 수 있습니다:

이러한 그래프는 설명하기 어려운 계속 증가하는 카운터 값을 표시하므로 유용성이 거의 없습니다. 네트워크 대역폭 그래프가 필요합니다. PromQL에는 rate 함수가 있어 일치하는 모든 시계열에 대해 초당 속도를 계산할 수 있습니다:

rate(node:network_receive_bytes_total[5m])

이제 이러한 그래프를 이해할 수 있습니다:

쿼리에서 [5m]은 무엇을 의미할까요? 이것은 시간 지속 시간(d)입니다.

이 경우 5분이며, 각 그래프 포인트의 초당 속도를 계산할 때 뒤로 돌아봅니다. 각 포인트의 단순화된 속도 계산은 다음과 같습니다: (Vcurr - Vprev) / (Tcurr - Tprev). 여기서 Vcurr는 현재 포인트의 값 -Tcurr이고, Vprev는 시간 Tprev = Tcurr - d의 값입니다.

너무 복잡하게 느껴진다면, 더 높은 d가 그래프를 부드럽게 하고 더 낮은 d가 그래프에 더 많은 노이즈를 추가한다는 점만 기억하세요.

Guance은 PromQL 확장 문법 MetricsQL을 사용합니다 (VictoriaMetrics 오픈 소스에 감사!). 이 경우 [d]는 생략할 수 있습니다. 이 경우 그래프에서 두 연속 포인트 사이의 지속 시간("스텝"이라고도 함)과 같습니다:

rate(node:network_receive_bytes_total)

따라서 rate 뒤의 지속 시간을 어떻게 채워야 할지 모를 때는 안심하고 생략하세요.

rate 사용 시 주의사항¶

rate는 메트릭 이름을 제거하지만 내부 시계열의 모든 레이블은 유지합니다.

rate를 위아래로 변동할 수 있는 시계열에 적용하지 마세요. 이러한 시계열을 게이지라고 합니다. rate는 카운터에만 적용해야 합니다. 카운터는 항상 증가하지만 (예: 서비스 재시작 시) 0으로 재설정될 수 있습니다.

rate 대신 irate를 사용하지 마세요. irate는 피크를 캡처하지 못하며 rate보다 훨씬 빠르지 않습니다.

산술 연산자¶

PromQL은 모든 기본 산술 연산을 지원합니다:

• 더하기 (+)
• 빼기 (-)
• 곱하기 (*)
• 나누기 (/)
• 모듈로 (%)
• 지수 (^)

이를 통해 다양한 변환을 수행할 수 있습니다. 예를 들어, 바이트/초를 비트/초로 변환:

rate(node:network_receive_bytes_total[5m]) * 8

또한, 이를 통해 시계열 간 계산을 수행할 수 있습니다. 예를 들어, Flux 쿼리는 다음 PromQL 쿼리로 단순화할 수 있습니다:

co2 * (((temp_c + 273.15) * 1013.25) / (pressure * 298.15))

산술 연산자를 사용하여 여러 시계열을 조합할 때는 일치 규칙을 이해해야 합니다. 그렇지 않으면 쿼리가 오류를 발생시키거나 잘못된 결과를 초래할 수 있습니다. 일치 규칙의 기본은 간단합니다:

• PromQL 엔진은 왼쪽과 오른쪽의 모든 시계열에서 메트릭 이름을 제거하지만 레이블은 유지합니다.
• 왼쪽의 각 시계열에 대해 PromQL 엔진은 오른쪽에서 동일한 레이블 집합을 가진 해당 시계열을 검색하고 각 데이터 포인트에 연산을 적용한 후 동일한 레이블 집합을 가진 결과 시계열을 반환합니다. 일치하는 항목이 없으면 결과에서 해당 시계열이 제거됩니다.

일치 규칙은 ignoring, on, group_left, group_right 수정자로 보강할 수 있습니다. 이러한 수정자의 사용은 다소 복잡하지만 대부분의 경우 사용할 필요가 없습니다.

PromQL 비교 연산자¶

PromQL은 다음 비교 연산자를 지원합니다:

• 같음 (==)
• 같지 않음 (!=)
• 큼 (>)
• 크거나 같음 (>=)
• 작음 (<)
• 작거나 같음 (<=)

이러한 연산자는 산술 연산자와 마찬가지로 임의의 PromQL 표현식에 적용할 수 있습니다. 비교 연산의 결과는 일치하는 데이터 포인트의 시계열입니다. 예를 들어, 다음 쿼리는 대역폭이 2300바이트/초 미만인 시계열만 반환합니다:

rate(node:network_receive_bytes_total[5m]) < 2300

이렇게 하면 대역폭이 2300바이트/초를 초과하는 부분에 간격이 있는 그래프가 생성됩니다:

rate(node:network_receive_bytes_total[5m]) < 2300

비교 연산자의 결과는 bool 수정자로 보강할 수 있습니다:

rate(node:network_receive_bytes_total[5m]) < bool 2300

이 경우 결과에는 true 비교에 대해 1, false 비교에 대해 0이 포함됩니다:

rate(node:network_receive_bytes_total[5m]) < bool 2300

집계 및 그룹화 함수¶

PromQL은 시계열 집계 및 그룹화를 허용합니다. 시계열은 주어진 레이블 집합으로 그룹화된 다음 각 그룹에 주어진 집계 함수가 적용됩니다. 예를 들어, 다음 쿼리는 node_exporter가 설치된 모든 노드에서 인스턴스별로 그룹화된 수신 트래픽 합계를 반환합니다:

sum(rate(node:network_receive_bytes_total[5m])) by (instance)

게이지 사용하기¶

게이지는 메모리 사용량, 온도 또는 압력과 같이 언제든지 위아래로 변동할 수 있는 시계열입니다. 대시보드에 그래프를 그릴 때는 일반적으로 각 포인트의 최소값, 최대값, 평균값 및/또는 분위수 값을 표시해야 합니다. PromQL은 이러한 요구를 충족하기 위해 다음 함수를 제공합니다:

예를 들어, 다음 쿼리는 그래프의 각 포인트에 대해 여유 메모리의 최소값을 그립니다:

min_over_time(node:memory_MemFree_bytes[5m])

MetricsQL은 PromQL에 rollup_* 함수를 추가하여 게이지에 적용할 때 자동으로 min, max, avg 값을 반환합니다. 예:

rollup(node:memory_MemFree_bytes)

레이블 조작¶

PromQL은 레이블의 수정, 미화, 삭제 또는 생성을 위한 두 가지 함수를 제공합니다:

이러한 함수의 사용은 다소 복잡하지만 선택한 시계열의 레이블을 강력하게 동적으로 조작할 수 있습니다. MetricsQL은 더 편리한 레이블 조작 함수로 이러한 기능을 확장합니다:

• label_set: 시계열에 추가 레이블 설정
• label_del: 시계열에서 주어진 레이블 삭제
• label_keep: 주어진 레이블을 제외한 모든 레이블을 시계열에서 삭제
• label_copy: 레이블 값을 다른 레이블로 복사
• label_move: 레이블 이름 변경
• label_transform: 주어진 정규 표현식과 일치하는 모든 하위 문자열을 템플릿 대체로 교체
• label_values: 주어진 레이블에서 숫자 값 반환

단일 쿼리에서 여러 결과 반환하기¶

때로는 단일 PromQL 쿼리에서 여러 결과를 반환해야 할 때가 있습니다. 이는 or 연산자를 사용하여 구현할 수 있습니다. 예를 들어, 다음 쿼리는 이름이 metric1, metric2, metric3인 모든 시계열을 반환합니다:

metric1 or metric2 or metric3

MetricsQL은 단순화하여 () 안에 나열하기만 하면 여러 결과를 반환할 수 있습니다:

(metric1, metric2, metric3)

임의의 PromQL 표현식도 메트릭 이름뿐만 아니라 거기에 넣을 수 있습니다.

표현식 결과를 조합할 때 일반적인 함정이 있습니다: 중복된 레이블 집합이 있는 결과는 건너뜁니다. 예를 들어, 다음 쿼리는 sum(a)와 sum(b)가 모두 동일한 레이블 집합을 가지고 있기 때문에 sum(b)를 건너뜁니다. 즉, 레이블이 전혀 없습니다:

sum(a) or sum(b)

결론¶

PromQL은 사용하기 쉽지만 강력한 시계열 데이터베이스 쿼리 언어입니다. SQL, InfluxQL 또는 Flux와 비교할 때 일반적인 TSDB 쿼리를 간결하고 명확한 방식으로 작성할 수 있습니다.

이 튜토리얼은 PromQL의 모든 기능을 다루지는 않습니다. 일부 기능은 자주 사용되지 않기 때문입니다:

• 많은 함수와 논리 연산자를 언급하지 않았습니다.
• 공통 표현식(CTE 또는 WITH 템플릿)을 다루지 않습니다.
• MetricsQL이 지원하는 많은 유용한 기능을 다루지 않습니다.

PromQL 치트 시트를 사용하여 PromQL을 계속 학습할 수 있습니다.

이 글의 주요 내용은 PromQL tutorial for beginners and humans에서 번역되었으며, Guance은 VictoriaMetrics에서 오픈소스로 제공하는 MetricsQL 엔진 구현을 사용하고 있습니다. VictoriaMetrics에 다시 한번 감사드립니다!

더 읽어보기¶