연산자

연산자 (Operators)

PromQL에서 데이터를 계산하고 조합하는 모든 연산자를 정리한 문서예요. 단항 연산자, 산술·비교·논리 이항 연산자, 그리고 여러 시계열을 하나로 합치는 집계 연산자가 전부 여기 담겨 있어요. 특히 벡터 매칭(vector matching) 개념은 PromQL을 제대로 쓰려면 반드시 알아야 하는 핵심이에요.

PromQL은 단항(unary), 이항(binary), 집계(aggregation) 연산자를 지원해요. 각 연산자가 어떤 입력을 받고 결과가 어떻게 되는지, 그래프를 그릴 때 흔히 헷갈리는 우선순위까지 함께 살펴볼게요.

출처: 문서

본문

PromQL은 단항, 이항, 집계 연산자를 지원해요.

단항 연산자 (Unary operator)

PromQL의 유일한 단항 연산자는 -(단항 마이너스)예요. 이는 스칼라 또는 인스턴트 벡터에 적용할 수 있어요. 전자의 경우 부호가 반전된 스칼라를 반환하고, 후자의 경우 각 요소의 부호가 반전된 인스턴트 벡터를 반환해요. 히스토그램 샘플의 부호는 모든 버킷 인구와 관측치의 count·sum의 부호를 반전해 반전돼요. 결과 히스토그램 샘플은 항상 gauge 히스토그램으로 간주돼요.

참고: 음수 버킷 인구나 음수 관측치 count를 가진 히스토그램은 중간 결과로만 사용해야 해요. 그런 음수 히스토그램이 기록 규칙의 최종 결과라면 규칙 평가가 실패해요. 음수 히스토그램은 어떤 교환 형식(exposition, remote-write, OTLP)으로도 표현할 수 없어서 어떤 방법으로도 프로메테우스에 수집될 수 없고, PromQL 표현식으로만 생성돼요.

이항 연산자 (Binary operators)

이항 연산자는 기본 논리 및 산술 연산을 다뤄요. 두 인스턴트 벡터 간 연산의 경우 매칭 동작을 수정할 수 있어요.

산술 이항 연산자

PromQL에는 다음 산술 이항 연산자가 존재해요:

  • + (덧셈)
  • - (뺄셈)
  • * (곱셈)
  • / (나눗셈)
  • % (모듈로)
  • ^ (거듭제곱)

산술 이항 연산자는 scalar/scalar, vector/scalar, vector/vector 값 쌍 사이에서 정의돼요. NaN, +Inf, -Inf 같은 특수 값 처리도 포함해 일반적인 IEEE 754 부동 소수점 산술을 따릅니다.

두 스칼라 사이에서는 동작이 명확해요: 두 스칼라 피연산자에 연산자를 적용한 결과인 또 다른 스칼라로 평가돼요.

인스턴트 벡터와 스칼라 사이에서는 연산자가 벡터의 모든 데이터 샘플 값에 적용돼요.

데이터 샘플이 float이면 그 float와 스칼라 사이에서 연산이 수행돼요. 예를 들어 float 샘플의 인스턴트 벡터를 2로 곱하면 결과는 원래 벡터의 모든 샘플 값이 2로 곱해진 float 샘플의 또 다른 벡터예요.

히스토그램 샘플인 벡터 요소의 동작은 다음과 같아요:

  • *의 경우 모든 버킷 인구와 관측치의 count·sum이 스칼라로 곱해져요. 스칼라가 음수면 결과 히스토그램은 gauge 히스토그램으로 간주돼요. 그렇지 않으면 입력 히스토그램 샘플의 counter 대 gauge 성격이 유지돼요
  • /의 경우 히스토그램 샘플이 왼쪽(LHS)에 있어야 하고 스칼라가 오른쪽(RHS)에 따라와요. 그러면 모든 버킷 인구와 관측치의 count·sum이 스칼라로 나눠져요. 0으로 나누면 일반 버킷이 없고 제로 버킷 인구와 관측치의 count·sum이 모두 +Inf, -Inf, NaN 중 하나(입력 히스토그램의 값이 각각 양수, 음수, 0/NaN일 때)로 설정된 히스토그램이 돼요. 스칼라가 음수면 결과 히스토그램은 gauge 히스토그램으로 간주돼요. 그렇지 않으면 입력 히스토그램 샘플의 counter 대 gauge 성격이 유지돼요
  • LHS에 스칼라, RHS에 히스토그램 샘플이 있는 /, 그리고 마찬가지로 스칼라와 히스토그램 샘플의 어떤 조합에 대한 모든 다른 산술 이항 연산자는 결과가 없고 해당 요소는 결과 벡터에서 제거돼요. 그런 제거는 info 레벨 어노테이션으로 표시돼요

두 인스턴트 벡터 사이에서는 산술 이항 연산자가 LHS 벡터의 각 항목과 RHS 벡터의 일치 요소에 적용돼요. 결과는 그룹화 레이블이 출력 레이블 세트가 되어 결과 벡터로 전파돼요. 기본적으로 반대 벡터에서 일치 항목을 찾을 수 없는 시리즈는 결과에 포함되지 않아요. 이 동작은 fill 수정자로 조정할 수 있어요.

두 float 샘플이 일치하면 두 입력 값에 산술 연산자가 적용돼요.

float 샘플이 히스토그램 샘플과 일치하면 동작은 스칼라와 히스토그램 샘플 사이와 같은 논리를 따릅니다(위 참조), 즉 *와 /(후자는 히스토그램 샘플이 LHS일 때)는 유효한 연산이고, 다른 모든 것은 결과 벡터에서 해당 요소의 제거로 이어져요.

두 히스토그램 샘플이 일치하면 +와 -만 유효한 연산이며, 각각 모든 일치하는 버킷 인구와 관측치의 count·sum을 더하거나 빼요. 다른 모든 연산은 info 레벨 어노테이션으로 표시되어 해당 요소가 출력 벡터에서 제거돼요. +와 - 연산은 일반적으로 gauge 히스토그램에만 적용해야 하지만, PromQL은 정렬되지 않은 counter 리셋 문제를 피하려면 특별한 주의가 필요한 특정 사용 사례를 다루기 위해 counter 히스토그램에도 허용해요. (counter 리셋의 특정 비호환성은 PromQL이 감지할 수 있고 warn 레벨 어노테이션으로 표시돼요.) 두 counter 히스토그램을 더하면 counter 히스토그램이 돼요. 다른 모든 피연산자 조합과 모든 뺄셈은 gauge 히스토그램이 돼요.

벡터를 포함하는 산술 이항 연산에서는 메트릭 이름이 삭제돼요. 이것은 __name__이 on에 명시적으로 언급되어도 발생해요(자세한 논의는 https://github.com/prometheus/prometheus/issues/16631 참조).

음수 히스토그램이 될 수 있는 산술 이항 연산에는 위의 관련 주의 사항을 고려하세요.

삼각 이항 연산자

프로메테우스에는 라디안 단위로 동작하는 다음 삼각 이항 연산자가 존재해요:

삼각 연산자는 일반 함수로는 할 수 없는 벡터 매칭을 사용해 두 벡터에 삼각 함수를 실행할 수 있게 해줘요. 산술 연산자와 같은 방식으로 동작해요. float 샘플에서만 동작해요. 히스토그램 샘플을 포함하는 연산은 info 레벨 어노테이션으로 표시되어 해당 벡터 요소가 출력 벡터에서 제거돼요.

히스토그램 트림 연산자

프로메테우스에는 다음 이항 히스토그램 트림 연산자가 존재해요:

  • / (lower 트림): 임계값 아래의 모든 관측치를 제거

히스토그램 트림 연산자는 vector/scalar와 vector/vector 값 쌍 사이에서 정의되며, 왼쪽은 네이티브 히스토그램(지수 또는 NHCB)이고 오른쪽은 float 임계값이에요.

임계값이 히스토그램의 버킷 경계 중 하나와 정렬되지 않은 경우, 임계값을 포함하는 버킷에 남는 관측치의 추정 개수를 계산하기 위해 선형(NHCB와 지수 히스토그램의 제로 버킷) 또는 지수(지수 히스토그램의 0이 아닌 버킷) 보간이 적용돼요.

일부 관측치가 트림되면 관측치 값의 새 합이 (대략적으로) 남은 관측치를 기반으로 다시 계산돼요.

비교 이항 연산자

프로메테우스에는 다음 비교 이항 연산자가 존재해요:

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

비교 연산자는 scalar/scalar, vector/scalar, vector/vector 값 쌍 사이에서 정의돼요. 기본적으로 필터링해요. 연산자 뒤에 bool을 제공하면 동작이 수정되어 값이 필터링 대신 0 또는 1로 반환돼요.

두 스칼라 사이에서는 bool 수정자를 제공해야 하며, 이 연산자들은 비교 결과에 따라 0(false) 또는 1(true)인 또 다른 스칼라가 돼요.

인스턴트 벡터와 스칼라 사이에서는 이 연산자들이 벡터의 모든 데이터 샘플 값에 적용되고, 비교 결과가 false인 벡터 요소는 결과 벡터에서 빠져요. 이 연산들은 벡터의 float 샘플에서만 동작해요. 히스토그램 샘플의 경우 info 레벨 어노테이션으로 표시되어 해당 요소가 결과 벡터에서 제거돼요.

두 인스턴트 벡터 사이에서는 이 연산자들이 기본적으로 필터로 동작하며 일치하는 항목에 적용돼요. 표현식이 참이 아니거나 표현식 반대편에서 일치를 찾지 못한 벡터 요소는 결과에서 빠지고, 나머지는 그룹화 레이블이 출력 레이블 세트가 되어 결과 벡터로 전파돼요.

두 float 샘플 간의 일치는 평소처럼 동작해요.

float 샘플과 히스토그램 샘플 간의 일치는 유효하지 않으며, info 레벨 어노테이션으로 표시되어 해당 요소가 결과 벡터에서 제거돼요.

두 히스토그램 샘플 사이에서는 ==와 !=가 예상대로 동작하지만, 다른 모든 비교 이항 연산은 역시 유효하지 않아요.

벡터를 포함하는 비교 이항 연산에서 bool 수정자를 제공하면 동작이 다음 방식으로 변경돼요:

  • 표현식 반대편에서 일치를 찾지만 표현식이 false인 벡터 요소는 대신 값 0을 가지고, 일치를 찾고 표현식이 참인 벡터 요소는 값 1을 가져요. (일치가 없거나 히스토그램 샘플을 포함하는 유효하지 않은 연산의 요소는 값 0 대신 여전히 결과를 반환하지 않는다는 점에 유의하세요)
  • 메트릭 이름이 삭제돼요

bool 수정자를 제공하지 않으면 몇 가지 예외를 제외하고 왼쪽의 메트릭 이름이 유지돼요:

  • on을 사용하면 메트릭 이름이 삭제돼요
  • group_right를 사용하면 충돌을 피하기 위해 오른쪽의 메트릭 이름이 유지돼요

논리/집합 이항 연산자

이 논리/집합 이항 연산자는 인스턴트 벡터 사이에서만 정의돼요:

  • and (교집합)
  • or (합집합)
  • unless (여집합)

vector1 and vector2는 정확히 일치하는 레이블 세트를 가진 요소가 vector2에 있는 vector1의 요소로 구성된 벡터를 만들어요. 다른 요소는 삭제돼요. 메트릭 이름과 값은 왼쪽 벡터에서 가져와요.

vector1 or vector2는 vector1의 모든 원래 요소(레이블 세트 + 값)와 추가로 vector1에 일치하는 레이블 세트가 없는 vector2의 모든 요소를 포함하는 벡터를 만들어요.

vector1 unless vector2는 정확히 일치하는 레이블 세트를 가진 요소가 vector2에 없는 vector1의 요소로 구성된 벡터를 만들어요. 두 벡터의 모든 일치하는 요소는 삭제돼요.

이 논리/집합 이항 연산자는 샘플 값과 상호작용하지 않으므로 float 샘플과 히스토그램 샘플에 같은 방식으로 동작해요.

벡터 매칭 (Vector matching)

벡터 간 연산은 왼쪽의 각 항목에 대해 오른쪽 벡터에서 일치하는 요소를 찾으려고 해요. 매칭 동작에는 일대일(one-to-one)과 다대일/일대다(many-to-one/one-to-many)의 두 가지 기본 유형이 있어요.

벡터 매칭 키워드

이 벡터 매칭 키워드는 서로 다른 레이블 세트를 가진 시리즈 간 매칭을 허용해요:

  • on(): 제공된 레이블에 대해서만 매칭
  • ignoring(): 매칭 시 제공된 레이블 무시

매칭 키워드에 제공된 레이블 목록은 벡터가 어떻게 결합될지 결정해요. 예시는 일대일 벡터 매칭과 다대일 및 일대다 벡터 매칭에서 찾을 수 있어요.

그룹 수정자 (Group modifiers)

이 그룹 수정자는 다대일/일대다 벡터 매칭을 활성화해요:

  • group_left: 왼쪽 벡터가 더 높은 카디널리티를 가진 다대일 매칭 허용
  • group_right: 오른쪽 벡터가 더 높은 카디널리티를 가진 일대다 매칭 허용

그룹 수정자에는 "one" 쪽의 레이블을 포함하는 레이블 목록을 제공할 수 있으며, 이는 결과 메트릭에 포함돼요.

다대일과 일대다 매칭은 신중히 고려해야 하는 고급 사용 사례예요. 종종 ignoring()을 적절히 사용하면 원하는 결과를 얻을 수 있어요.

그룹핑 수정자는 비교, 산술, 삼각 연산자에만 사용할 수 있어요. 집합 연산자는 기본적으로 양쪽의 모든 가능한 항목과 매칭해요.

일대일 벡터 매칭

일대일은 연산의 각 쪽에서 고유한 항목 쌍을 찾아요. 기본 경우는 vector1 <operator> vector2 형식을 따르는 연산이에요. 두 항목은 정확히 동일한 레이블 세트와 해당 값을 가지면 일치해요. ignoring 키워드는 매칭 시 특정 레이블을 무시할 수 있게 하고, on 키워드는 고려되는 레이블 세트를 제공된 목록으로 줄일 수 있게 해요:

<vector expr> <bin-op> ignoring(<label list>) <vector expr>
<vector expr> <bin-op> on(<label list>) <vector expr>

예시 입력:

method_code:http_errors:rate5m{method="get", code="500"}  24
method_code:http_errors:rate5m{method="get", code="404"}  30
method_code:http_errors:rate5m{method="put", code="501"}  3
method_code:http_errors:rate5m{method="post", code="500"} 6
method_code:http_errors:rate5m{method="post", code="404"} 21

method:http_requests:rate5m{method="get"}  600
method:http_requests:rate5m{method="del"}  34
method:http_requests:rate5m{method="post"} 120

예시 쿼리:

method_code:http_errors:rate5m{code="500"} / ignoring(code) method:http_requests:rate5m

이것은 지난 5분 동안 측정된 각 메서드의 상태 코드 500인 HTTP 요청의 비율을 포함하는 결과 벡터를 반환해요. ignoring(code)가 없으면 메트릭이 동일한 레이블 세트를 공유하지 않으므로 일치가 없었을 거예요. put과 del 메서드의 항목은 일치가 없으며 결과에 나타나지 않아요:

{method="get"}  0.04            //  24 / 600
{method="post"} 0.05            //   6 / 120

다대일 및 일대다 벡터 매칭

다대일과 일대다 매칭은 "one" 쪽의 각 벡터 요소가 "many" 쪽의 여러 요소와 일치할 수 있는 경우를 말해요. 이는 group_left 또는 group_right 수정자로 명시적으로 요청해야 하며, left/right는 어느 벡터가 더 높은 카디널리티를 가지는지 결정해요.

<vector expr> <bin-op> ignoring(<label list>) group_left(<label list>) <vector expr>
<vector expr> <bin-op> ignoring(<label list>) group_right(<label list>) <vector expr>
<vector expr> <bin-op> on(<label list>) group_left(<label list>) <vector expr>
<vector expr> <bin-op> on(<label list>) group_right(<label list>) <vector expr>

그룹 수정자와 함께 제공된 레이블 목록은 결과 메트릭에 포함될 "one" 쪽의 추가 레이블을 포함해요. on의 경우 레이블은 목록 중 하나에만 나타날 수 있어요. 결과 벡터의 모든 시계열은 고유하게 식별 가능해야 해요.

예시 쿼리:

method_code:http_errors:rate5m / ignoring(code) group_left method:http_requests:rate5m

이 경우 왼쪽 벡터는 method 레이블 값당 하나 이상의 항목을 포함해요. 그래서 우리는 group_left를 사용해 이를 나타내요. 오른쪽의 요소는 이제 왼쪽의 같은 method 레이블을 가진 여러 요소와 일치해요:

{method="get", code="500"}  0.04            //  24 / 600
{method="get", code="404"}  0.05            //  30 / 600
{method="post", code="500"} 0.05            //   6 / 120
{method="post", code="404"} 0.175           //  21 / 120

누락된 일치 채우기

Fill 수정자는 실험적이며 --enable-feature=promql-binop-fill-modifiers로 활성화해야 해요.

기본적으로 이항 연산의 반대편에서 일치를 찾지 못한 벡터 요소는 결과 벡터에 포함되지 않아요. Fill 수정자는 이항 연산의 양쪽에서 누락된 시리즈를 제공된 기본 샘플 값으로 채워 이 동작을 재정의할 수 있게 해요:

  • fill(<value>): 양쪽의 누락된 일치를 value로 채움
  • fill_left(<value>): 왼쪽의 누락된 일치를 value로 채움
  • fill_right(<value>): 오른쪽의 누락된 일치를 value로 채움

value는 float 샘플을 나타내는 숫자 리터럴이어야 해요. 히스토그램 샘플은 지원되지 않아요.

이 수정자들은 연산 한쪽에서 누락된 시리즈만 채울 수 있다는 점에 유의하세요. 시리즈가 양쪽 모두에 없으면 이 수정자들로 생성할 수 없어요.

Fill 수정자는 다음 조합으로 사용할 수 있어요:

  • fill(<value>)
  • fill_left(<value>)
  • fill_right(<value>)
  • fill_left(<value>) fill_right(<value>)
  • fill_right(<value>) fill_left(<value>)

bool, on, ignoring, group_left, group_right 같은 다른 이항 연산자 수정자를 사용하면 fill 수정자를 마지막에 제공해야 해요.

Fill 수정자를 group_left나 group_right와 함께 사용하면 다음과 같이 동작해요:

  • fill 수정자를 일치의 "many" 쪽에 사용하면 각 일치 그룹의 "many" 쪽에 단일 시리즈만 채우며, 그룹의 일치하는 레이블을 시리즈 정체성으로 사용해요
  • fill 수정자를 일치의 "one" 쪽에 사용하고 그룹핑 수정자가 "one" 쪽에서 포함할 레이블 이름을 지정하면(예: left_vector * on(instance, job) group_left(info_label) fill_right(1) right_vector), 값의 원천이 없으므로 그 레이블은 누락된 시리즈에 채워지지 않아요

Fill 수정자는 집합 연산자(and, or, unless)에는 지원되지 않아요. 그 연산자의 목적이 다른 벡터에서의 존재 여부에 따라 시리즈를 필터링하는 것이기 때문이에요.

양쪽의 누락된 시리즈를 0으로 채우는 예시 쿼리:

method_code:http_errors:rate5m{status="500"} / ignoring(code) fill(0) method:http_requests:rate5m

이것은 지난 5분 동안 측정된 각 메서드의 상태 코드 500인 HTTP 요청의 비율을 포함하는 결과 벡터를 반환해요. put과 del 메서드의 항목은 각각 반대쪽에 일치하는 시리즈가 없었으므로 이제 기본 샘플 값 0으로 채워져 결과에 포함돼요:

{method="get"}  0.04            #  24 / 600
{method="put"}  +Inf            #   3 /   0 (missing right side filled in)
{method="del"}  0               #   0 /  34 (missing left side filled in)
{method="post"} 0.05            #   6 / 120

집계 연산자 (Aggregation operators)

프로메테우스는 단일 인스턴트 벡터의 요소를 집계해 더 적은 요소를 가진 새 벡터를 만드는 데 사용할 수 있는 다음 내장 집계 연산자를 지원해요:

  • sum(v) (차원에 걸쳐 합 계산)
  • avg(v) (차원에 걸쳐 산술 평균 계산)
  • min(v) (차원에 걸쳐 최소 선택)
  • max(v) (차원에 걸쳐 최대 선택)
  • bottomk(k, v) (샘플 값으로 가장 작은 k 요소)
  • topk(k, v) (샘플 값으로 가장 큰 k 요소)
  • limitk(k, v) (k 요소 샘플링, 실험적이며 --enable-feature=promql-experimental-functions로 활성화해야 함)
  • limit_ratio(r, v) (요소의 의사 난수 비율 r 샘플링, 실험적이며 --enable-feature=promql-experimental-functions로 활성화해야 함)
  • group(v) (결과 벡터의 모든 값은 1)
  • count(v) (벡터의 요소 수 계산)
  • count_values(l, v) (같은 값을 가진 요소 수 계산)
  • stddev(v) (차원에 걸쳐 모표준편차 계산)
  • stdvar(v) (차원에 걸쳐 모분산 계산)
  • quantile(φ, v) (차원에 걸쳐 φ-분위수(0 ≤ φ ≤ 1) 계산)

이 연산자들은 모든 레이블 차원에 걸쳐 집계하거나, without 또는 by 절을 포함해 서로 다른 차원을 보존할 수 있어요. 이 절들은 표현식 앞이나 뒤에 사용할 수 있어요.

<aggr-op> [without|by (<label list>)] ([parameter,] <vector expression>)

또는

<aggr-op>([parameter,] <vector expression>) [without|by (<label list>)]

label list는 끝에 쉼표를 포함할 수 있는 따옴표 없는 레이블 목록이에요. 즉 (label1, label2)와 (label1, label2,) 둘 다 유효한 구문이에요.

without는 결과 벡터에서 나열된 레이블을 제거하고 다른 모든 레이블은 출력에 보존해요. by는 반대로, 벡터의 모든 요소 사이에서 레이블 값이 동일하더라도 by 절에 나열되지 않은 레이블을 삭제해요.

상세 설명

sum

sum(v)는 + 이항 연산자가 두 값 사이에서 하는 것과 같은 방식으로 v의 샘플 값을 합산해요.

단일 결과 벡터 요소로 집계되는 모든 샘플 값은 모두 float 샘플이거나 모두 histogram 샘플이어야 해요. 둘 다 섞인 집계는 유효하지 않으며, warn 레벨 어노테이션으로 표시되어 해당 벡터 요소가 출력 벡터에서 제거돼요.

예시

메트릭 memory_consumption_bytes가 application, instance, group 레이블로 팬아웃되는 시계열을 가지고 있다면, 모든 인스턴스에 걸친 애플리케이션·그룹별 총 메모리 소비를 다음과 같이 계산할 수 있어요:

sum without (instance) (memory_consumption_bytes)

이는 다음과 동일해요:

sum by (application, group) (memory_consumption_bytes)

모든 애플리케이션의 총 메모리 소비에만 관심이 있다면 다음과 같이 간단히 쓸 수 있어요:

sum(memory_consumption_bytes)
avg

avg(v)는 v의 합을 / 이항 연산자와 같은 방식으로 집계된 샘플 수로 나눠요.

단일 결과 벡터 요소로 집계되는 모든 샘플 값은 모두 float 샘플이거나 모두 histogram 샘플이어야 해요. 둘 다 섞인 집계는 유효하지 않으며, warn 레벨 어노테이션으로 표시되어 해당 벡터 요소가 출력 벡터에서 제거돼요.

min 과 max

min(v)와 max(v)는 각각 v의 최소 또는 최대 값을 반환해요.

IEEE 754 부동 소수점 산술을 따르는 float 샘플에서만 동작해요. 특히 이는 NaN이 모든 집계 값이 NaN인 경우에만 최소나 최대로 간주된다는 것을 의미해요. 입력 벡터의 히스토그램 샘플은 info 레벨 어노테이션으로 표시되어 무시돼요.

topk 과 bottomk

topk(k, v)와 bottomk(k, v)는 다른 집계자와 달리 원래 레이블을 포함한 입력 샘플의 k 값 부분집합이 결과 벡터에 반환돼요.

by와 without는 입력 벡터를 버킷화하는 데만 사용돼요.

min과 max와 비슷하게 float 샘플에서만 동작하며, NaN 값을 각각 top 또는 bottom에서 가장 먼 것으로 간주해요. 입력 벡터의 히스토그램 샘플은 info 레벨 어노테이션으로 표시되어 무시돼요.

인스턴트 쿼리에서 사용하면 topk와 bottomk는 각각 값으로 내림차순 또는 오름차순 정렬된 시리즈를 반환해요. by나 without와 함께 사용하면 각 버킷 내의 시리즈는 값으로 정렬되고, 같은 버킷의 시리즈는 연속적으로 반환되지만 버킷 자체가 특정 순서로 반환된다는 보장은 없어요.

범위 쿼리에는 정렬이 적용되지 않아요.

예시

모든 인스턴스 중에서 메모리 소비가 가장 높은 5개 인스턴스를 얻으려면 다음과 같이 쓸 수 있어요:

topk(5, memory_consumption_bytes)
limitk

limitk(k, v)는 원래 레이블을 포함한 k 입력 샘플의 부분집합을 결과 벡터에 반환해요.

부분집합은 결정적이며 의사 난수 방식으로 선택돼요. 이는 샘플 타입과 무관하게 발생해요. 따라서 float 샘플과 histogram 샘플 모두에 동작해요.

예시

10개의 시계열을 샘플링하려면 다음과 같이 쓸 수 있어요:

limitk(10, memory_consumption_bytes)
limit_ratio

limit_ratio(r, v)는 원래 레이블을 포함한 입력 샘플의 부분집합을 결과 벡터에 반환해요.

부분집합은 결정적이며 의사 난수 방식으로 선택돼요. 이는 샘플 타입과 무관하게 발생해요. 따라서 float 샘플과 histogram 샘플 모두에 동작해요.

r은 +1과 -1 사이일 수 있어요. r의 절대값이 선택 비율로 사용되지만, 음수 r에 대해서는 선택 순서가 반전되어 여집합을 선택하는 데 사용할 수 있어요. 예를 들어 limit_ratio(0.1, ...)은 입력 샘플의 대략 10%의 결정적 세트를 반환하고, limit_ratio(-0.9, ...)은 limit_ratio(0.1, ...)이 반환하지 않은 나머지 대략 90%를 정확히 반환해요.

group

group(v)는 그 타임스탬프에서 어떤 값이라도 포함하는 각 그룹에 대해 1을 반환해요.

값은 float 또는 histogram 샘플일 수 있어요.

count

count(v)는 그 타임스탬프에서 값의 수를 반환하고, 그 타임스탬프에 값이 없으면 값이 전혀 없어요.

값은 float 또는 histogram 샘플일 수 있어요.

count_values

count_values(l, v)는 v의 고유 샘플 값마다 하나의 시계열을 출력해요. 각 시리즈는 l로 주어지는 추가 레이블을 가지며, 레이블 값이 고유 샘플 값이에요. 각 시계열의 값은 그 샘플 값이 나타난 횟수예요.

count_values는 float 샘플과 histogram 샘플 모두에 동작해요. 후자의 경우 히스토그램 샘플 값의 간결한 문자열 표현이 레이블 값으로 사용돼요.

예시

각 빌드 버전을 실행하는 바이너리 수를 세려면 다음과 같이 쓸 수 있어요:

count_values("version", build_version)
stddev

stddev(v)는 v의 표준편차를 반환해요.

stddev는 IEEE 754 부동 소수점 산술을 따르는 float 샘플에서만 동작해요. 입력 벡터의 히스토그램 샘플은 info 레벨 어노테이션으로 표시되어 무시돼요.

stdvar

stdvar(v)는 v의 분산을 반환해요.

stdvar는 IEEE 754 부동 소수점 산술을 따르는 float 샘플에서만 동작해요. 입력 벡터의 히스토그램 샘플은 info 레벨 어노테이션으로 표시되어 무시돼요.

quantile

quantile(φ, v)는 집계되는 차원의 N 메트릭 값 중에서 φ*N 번째 순위를 차지하는 값인 φ-분위수를 계산해요.

quantile은 float 샘플에서만 동작해요. 입력 벡터의 히스토그램 샘플은 info 레벨 어노테이션으로 표시되어 무시돼요.

NaN은 가능한 가장 작은 값으로 간주돼요.

예를 들어 quantile(0.5, ...)은 중앙값을, quantile(0.95, ...)은 95번째 백분위수를 계산해요.

특수한 경우:

  • φ = NaN이면 NaN이 반환돼요
  • φ < 0이면 -Inf가 반환돼요
  • φ > 1이면 +Inf가 반환돼요

이항 연산자 우선순위

다음 목록은 프로메테우스의 이항 연산자 우선순위를 높은 것부터 낮은 것 순으로 보여줘요.

  • ^
  • *, /, %, atan2
  • +, -
  • ==, !=, >=, <=
  • >, <
  • and, unless
  • or

같은 우선순위 수준의 연산자는 왼쪽 결합적이에요. 예를 들어 2 * 3 % 2는 (2 * 3) % 2와 동일해요. 하지만 ^는 오른쪽 결합적이라 2 ^ 3 ^ 2는 2 ^ (3 ^ 2)와 동일해요.

더 알아보기 (Learn more)