Functions

프로메테우스 공식 레퍼런스를 한글로 번역한 문서입니다.

전체 목차는 여기에 있습니다.

일부 함수에는 디폴트 인자가 존재한다. 예를 들면 다음과 같다: year(v=vector(time()) instant-vector). 여기선 instant 벡터인 v라는 인자가 하나 있으며, 인자를 제공하지 않으면 기본적으로 vector(time()) 표현식의 값을 사용한다.

abs()
absent()
absent_over_time()
ceil()
changes()
clamp()
clamp_max()
clamp_min()
day_of_month()
day_of_week()
days_in_month()
delta()
deriv()
exp()
floor()
histogram_quantile()
holt_winters()
hour()
idelta()
increase()
irate()
label_join()
label_replace()
ln()
log2()
log10()
minute()
month()
predict_linear()
rate()
resets()
round()
scalar()
sgn()
sort()
sort_desc()
sqrt()
time()
timestamp()
vector()
year()
<aggregation>_over_time()
Trigonometric Functions

`abs()`

abs(v instant-vector)는 입력 벡터에 있는 모든 샘플 값을 절대값으로 변환해서 반환한다.

`absent()`

absent(v instant-vector)는 전달한 벡터에 요소가 하나라도 있으면 빈 벡터를 반환하고, 요소가 없으면 값이 1인 요소를 하나를 가진 벡터를 반환한다.

이 함수는 지정한 메트릭명과 레이블 조합으로 시계열이 만들어지지 않을 때 알림^alert을 생성할 수 있어 유용하다.

absent(nonexistent{job="myjob"})
# => {job="myjob"}

absent(nonexistent{job="myjob",instance=~".*"})
# => {job="myjob"}

absent(sum(nonexistent{job="myjob"}))
# => {}

위에 두 예시에선 absent()를 잘 활용해서 입력 벡터로부터 요소가 1개인 출력 벡터의 레이블을 이끌어내고 있다.

`absent_over_time()`

absent_over_time(v range-vector)는 전달한 range 벡터에 요소가 하나라도 있으면 빈 벡터를 반환하고, range 벡터에 요소가 없으면 값이 1인 요소를 하나를 가진 벡터를 반환한다.

이 함수는 특정 기간 동안 지정한 메트릭명과 레이블 조합으로 시계열이 만들어지지 않을 때 알림^alert을 생성할 수 있어 유용하다.

absent_over_time(nonexistent{job="myjob"}[1h])
# => {job="myjob"}

absent_over_time(nonexistent{job="myjob",instance=~".*"}[1h])
# => {job="myjob"}

absent_over_time(sum(nonexistent{job="myjob"})[1h:])
# => {}

위에 두 예시에선 absent_over_time()을 잘 활용해서 입력 벡터로부터 요소가 1개인 출력 벡터의 레이블을 이끌어내고 있다.

`ceil()`

ceil(v instant-vector)는 v에 있는 모든 요소들의 샘플 값을 소수점은 버리고 가장 가까운 정수로 올린다.

`changes()`

changes(v range-vector)는 지정한 시간 범위 안에서 각 입력 시계열의 값이 변경된 횟수를 instant 벡터로 반환한다.

`clamp()`

clamp(v Instant-vector, min scalar, max scalar)는 v에 있는 모든 요소들의 샘플 값을 하한은 min으로, 상한은 max로 고정한다.

특이 케이스: min > max인 경우 빈 벡터를 반환하며, min이나 max가 NaN이면 NaN을 반환한다.

`clamp_max()`

clamp_max(v instant-vector, max scalar)는 v에 있는 모든 요소들의 샘플 값의 상한을 max로 고정한다.

`clamp_min()`

clamp_min(v instant-vector, min scalar)는 v에 있는 모든 요소들의 샘플 값의 하한을 min으로 고정한다.

`day_of_month()`

day_of_month(v=vector(time()) instant-vector)는 주어진 각 UTC 시간의 날짜를 반환한다. 반환 값은 1에서 31 사이다.

`day_of_week()`

day_of_week(v=vector(time()) instant-vector)는 주어진 각 UTC 시간의 요일을 반환한다. 반환 값은 0에서 6 사이이며, 여기서 0은 일요일을 의미한다.

`days_in_month()`

days_in_month(v=vector(time()) instant-vector)는 주어진 각 UTC 시간의 월에 포함된 일 수를 반환한다. 반환 값은 28에서 31 사이다.

`delta()`

delta(v range-vector)는 range 벡터 v에 있는 시계열 요소마다 첫 번째 값과 마지막 값의 차이를 계산하고, 계산한 델타 값을 레이블과 함께 가지고 있는 instant 벡터를 반환한다. range 벡터 셀렉터에 지정한 전체 시간 범위를 커버할 수 있도록 어립잡아 델타를 계산하기 때문에, 샘플 값이 모두 정수더라도 결과는 정수가 아닐 수 있다.

아래 예제 표현식은 현재와 2시간 전의 CPU 온도 차를 반환한다:

delta(cpu_temp_celsius{host="zeus"}[2h])

delta에선 게이지^gauge만 사용해야 한다.

`deriv()`

deriv(v range-vector)는 단순 선형 회귀^{simple linear regression}를 사용해서 range 벡터 v에 있는 시계열의 초 단위 도함수^derivative를 계산한다.

deriv에선 게이지^gauge만 사용해야 한다.

`exp()`

exp(v Instant-vector)는 v에 있는 모든 요소들에 대한 지수 함수를 계산한다. 특이 케이스는:

Exp(+Inf) = +Inf
Exp(NaN) = NaN

`floor()`

floor(v instant-vector)는 v에 있는 모든 요소들의 샘플 값을, 소수점은 버리고 가장 가까운 정수로 내린다.

`histogram_quantile()`

histogram_quantile(φ scalar, b instant-vector)는 히스토그램의 버킷 b에서 φ-quantile (0 ≤ φ ≤ 1)을 계산한다. (φ-quantile과 히스토그램 메트릭 타입 사용법에 대한 전반적인 내용은 histograms and summaries를 참고해라.) b에 들어있는 샘플들은 각 버킷의 관찰 횟수를 나타낸다. 각 샘플은 반드시 버킷의 상한(inclusive)을 가지고 있는 레이블 le가 첨부돼있어야 한다. (이 레이블이 없는 샘플은 별다른 오류 없이 그냥 무시한다.) 히스토그램 메트릭 타입을 사용하면 _bucket suffix를 가진 시계열을 적절한 레이블과 함께 자동으로 생성할 수 있다.

분위수^quantile를 계산할 때 사용할 time 윈도우는 rate() 함수로 지정한다.

예를 들어 http_request_duration_seconds라는 히스토그램 메트릭이 있다고 해보자. 지난 10분 동안 수집한 요청 지속 시간에서 90번째 백분위수^percentile를 계산하려면 아래 표현식을 사용하면 된다:

histogram_quantile(0.9, rate(http_request_duration_seconds_bucket[10m]))

이땐 http_request_duration_seconds의 레이블 조합마다 분위수^quantile를 따로따로 계산한다. 원하는 레이블 단위로 집계하고 싶으면 rate() 함수를 sum() aggregator로 감싸주면 된다. histogram_quantile()에선 le 레이블이 필요하므로 by 절에 le도 포함돼있어야 한다. 다음 표현식은 job을 기준으로 90번째 분위수^quantile를 집계한다:

histogram_quantile(0.9, sum by (job, le) (rate(http_request_duration_seconds_bucket[10m])))

전부 하나로 집계하고 싶다면 le 레이블만 지정하면 된다:

histogram_quantile(0.9, sum by (le) (rate(http_request_duration_seconds_bucket[10m])))

histogram_quantile() 함수는 버킷 내에 데이터가 선형으로 분포돼있다고 가정하고 분위수^quantile 값을 채운다. 가장 높은 버킷은 상한 값을 +Inf로 가지고 있어야 한다. (그렇지 않으면 NaN을 반환한다.) 분위수^quantile가 가장 높은 버킷에 속하면 두 번째로 높은 버킷의 상한을 반환한다. 가장 낮은 버킷에선 상한이 0보다 클 땐 하한을 0으로 가정한다. 이 경우엔 해당 버킷 안에 일반적인 선형 보간법^{linear interpolation}을 적용한다. 그 외 가장 낮은 버킷에 속한 분위수^quantile에선 가장 낮은 버킷의 상한을 반환한다.

b에 관측 결과가 0개 들어있을 땐 NaN을 반환한다. b에 들어있는 버킷이 2개 미만일 때도 NaN을 반환한다. φ < 0인 경우 -Inf를, φ > 1인 경우 +Inf를 반환한다.

`holt_winters()`

holt_winters(v range-vector, sf scalar, tf scalar)는 v의 범위를 기반으로 시계열의 값을 매끄럽게^smoothed 만들어준다. 평활 계수^{smoothing factor} sf가 낮을수록 오래된 데이터에 더 무게를 둔다. 추세 계수^{trend factor} tf가 높을수록 데이터의 추세를 좀 더 고려한다. sf와 tf 모두 0과 1 사이여야 한다.

holt_winters에선 게이지^gauge만 사용해야 한다.

`hour()`

hour(v=vector(time()) instant-vector)는 주어진 각 UTC 시간의 시간대를 반환한다. 반환 값은 0에서 23 사이다.

`idelta()`

idelta(v range-vector)는 range 벡터 v에 있는 마지막 두 샘플의 차이를 계산하고, 계산한 델타 값을 레이블과 함께 가지고 있는 instant 벡터를 반환한다.

idelta에선 게이지^gauge만 사용해야 한다.

`increase()`

increase(v range-vector)는 range 벡터 안에 있는 시계열의 증분을 계산한다. 단조성^monotonicity이 깨졌을 땐 (타겟 재시작으로 인한 카운터 리셋 등) 자동으로 보정된다. range 벡터 셀렉터에 지정한 전체 시간 범위를 커버할 수 있도록 어립잡아 증분을 계산하기 때문에, 카운터 값이 정수 단위로만 증가하더라도 결과는 정수가 아닐 수 있다.

다음 예제 표현식은 range 벡터에 있는 시계열마다 지난 5분 동안 측정한 HTTP 요청 수를 반환한다:

increase(http_requests_total{job="api-server"}[5m])

increase는 카운터에만 사용해야 한다. increase는 단순히 rate(v) 함수에 한 숟가락 더 얹어서 지정한 time range 윈도우를 초로 환산한 값을 곱한 함수이며, 주로 가독성이 요구될 때만 사용하는 게 좋다. recording rule에는 증분을 지속적으로 초 단위로 추적할 수 있도록 rate를 사용해라.

`irate()`

irate(v range-vector)는 range 벡터 안에 있는 시계열의 초당 순간 변화율을 계산한다. 변화율은 마지막 데이터 포인트 두 개를 가지고 계산한다. 단조성^monotonicity이 깨졌을 땐 (타겟 재시작으로 인한 카운터 리셋 등) 자동으로 보정된다.

다음 예제 표현식은 range 벡터에 있는 시계열마다 최대 5분 전까지 조회해서 가장 최근 데이터 포인트를 2개 찾고, 초당 HTTP 요청 비율을 반환한다:

irate(http_requests_total{job="api-server"}[5m])

irate는 변덕스럽고 빠르게 변화하는 카운터를 그래프로 표현할 때만 사용하는 게 좋다. alert나 느리게 변화하는 카운터에는 rate를 사용해라. irate에선 비율이 잠깐 동안 변경됐을 때도 FOR 절을 리셋할 수 있고, 그래프 전체를 드문드문 스파이크로 구성해버리면 알아보기 어렵기 때문이다.

참고로, irate()를 집계 연산자(ex. sum())나 시간에 따라 집계하는 함수(_over_time으로 끝나는 모든 함수)와 결합할 땐 항상 irate()를 먼저 취한 다음 집계한다. 이렇게 하지 않으면 타겟이 재시작했을 때 irate()에서 카운터 리셋을 감지할 수 없다.

`label_join()`

label_join(v instant-vector, dst_label string, separator string, src_label_1 string, src_label_2 string, ...)은 v에 있는 시계열마다 separator를 사용해 src_labels의 값들을 전부 연결해서, 조인 값을 dst_label 레이블로 가지고 있는 시계열을 반환한다. 이 함수에는 src_labels를 원하는 만큼 추가할 수 있다.

다음 예시는 시계열마다 foo 레이블에 a,b,c를 추가한 벡터를 반환한다:

label_join(up{job="api-server",src1="a",src2="b",src3="c"}, "foo", ",", "src1", "src2", "src3")

`label_replace()`

label_replace(v instant-vector, dst_label string, replacement string, src_label string, regex string)은 v에 있는 시계열마다 레이블 src_label의 값을 정규식 regex에 매칭시킨다. 매칭됐을 때 반환하는 시계열의 dst_label 레이블엔, 입력에 있는 기존 레이블에 replacement를 적용한 값이 담겨있다. 정규 표현식의 capturing group은 $1, $2 등으로 참조할 수 있다. 정규 표현식이 매칭되지 않으면 시계열을 변경하지 않고 반환한다.

다음 예시는 service 레이블엔 a:c, foo 레이블엔 a가 담겨있는 시계열을 반환한다:

label_replace(up{job="api-server",service="a:c"}, "foo", "$1", "service", "(.*):.*")

`ln()`

ln(v instant-vector)는 v에 있는 모든 요소의 자연 로그^{natural logarithm}를 계산한다. 특이 케이스는:

ln(+Inf) = +Inf
ln(0) = -Inf
ln(x < 0) = NaN
ln(NaN) = NaN

`log2()`

log2(v instant-vector)는 v에 있는 모든 요소의 이진 로그^{binary logarithm}를 계산한다. 특이 케이스는 ln에서 보여준 것과 동일하다.

`log10()`

log10(v instant-vector)는 v에 있는 모든 요소의 상용 로그^{decimal logarithm}를 계산한다. 특이 케이스는 ln에서 보여준 것과 동일하다.

`minute()`

minute(v=vector(time()) instant-vector)는 주어진 각 UTC 시간의 분을 반환한다. 반환 값은 0에서 59 사이다.

`month()`

month(v=vector(time()) instant-vector)는 주어진 각 UTC 시간의 월을 반환한다. 반환 값은 1에서 12 사이이며, 여기서 1은 1월을 의미한다.

`predict_linear()`

predict_linear(v range-vector, t scalar)는 단순 선형 회귀^{simple linear regression}를 사용해서 range 벡터 v를 기반으로 지금으로부터 t초 뒤의 시계열 값을 예측한다.

predict_linear에선 게이지^gauge만 사용해야 한다.

`rate()`

rate(v range-vector)는 range 벡터 안에 있는 시계열의 초당 평균 변화율을 계산한다. 단조성^monotonicity이 깨졌을 땐 (타겟 재시작으로 인한 카운터 리셋 등) 자동으로 보정된다. 또한 시간 범위의 양끝은 어림잡아 계산하기 때문에, 스크랩 일부가 누락됐더라도 문제 없으며, range의 기간과 스크랩 주기가 정확히 일렬로 정렬되지 않아도 괜찮다.

다음 예제 표현식은 range 벡터에 있는 시계열마다 지난 5분 동안 측정한 초당 HTTP 요청 비율을 반환한다:

rate(http_requests_total{job="api-server"}[5m])

rate는 카운터에만 사용해야 한다. alert를 정의할 때나, 느리게 변화하는 카운터를 그래프로 표현할 땐 rate가 가장 적합하다.

참고로, rate()를 집계 연산자(ex. sum())나 시간에 따라 집계하는 함수(_over_time으로 끝나는 모든 함수)와 결합할 땐 항상 rate()를 먼저 취한 다음 집계한다. 이렇게 하지 않으면 타겟이 재시작했을 때 rate()에서 카운터 리셋을 감지할 수 없다.

`resets()`

resets(v range-vector)는 입력 시계열마다 지정한 시간 범위 내에서 카운터를 리셋한 횟수를 instant 벡터로 반환한다. 연속한 두 개의 샘플 값을 비교해서 값이 감소했다면 카운터 리셋으로 해석한다.

resets는 카운터에만 사용해야 한다.

`round()`

round(v instant-vector, to_nearest=1 scalar)는 v에 있는 모든 요소들의 샘플 값을 가장 가까운 정수로 반올림한다. 가운데 걸쳐있는 값은 올림으로 처리한다. to_nearest 인자는 생략할 수 있는데, 샘플 값을 반올림할 가장 가까운 배수를 지정할 수 있다 (어느 자리에서 반올림할지). 이때 배수엔 분수도 사용할 수 있다.

`scalar()`

scalar(v instant-vector)는 단일 요소를 가지고 있는 입력 벡터를 넘기면 해당 요소의 샘플 값을 스칼라로 반환한다. 입력 벡터에 요소가 정확히 하나가 아니라면 scalar는 NaN을 반환한다.

`sgn()`

sgn(v instant-vector)는 모든 샘플 값을 부호로 변환한 벡터를 반환한다. 부호는 v가 양수면 1, 음수면 -1, 0이면 0으로 정의한다.

`sort()`

sort(v instant-vector)는 벡터 요소들을 샘플 값 기준으로 오름차순으로 정렬해서 반환한다.

`sort_desc()`

sort와 동일하되, 이번에는 내림차순으로 정렬한다.

`sqrt()`

sqrt(v Instant-vector)는 v에 있는 모든 요소의 제곱근^{square root}을 계산한다.

`time()`

time()은 1970년 1월 1일 UTC 이후 경과한 시간을 초 단위로 환산해서 반환한다. 실제로 현재 시간을 반환하는 게 아니라, 표현식을 평가할 시간을 반환한다는 점에 주의해라.

`timestamp()`

timestamp(v instant-vector)는 주어진 벡터에 있는 각 샘플의 타임스탬프를 1970년 1월 1일 UTC 이후 경과한 초 단위 시간으로 환산해서 반환한다.

이 함수는 프로메테우스 2.0에서 추가됐다

`vector()`

vector(s scalar)는 스칼라 s를 레이블이 없는 벡터로 반환한다.

`year()`

year(v=vector(time()) instant-vector)는 주어진 각 UTC 시간의 연도를 반환한다.

`<aggregation>_over_time()`

아래 있는 함수들을 사용하면 주어진 range 벡터에 있는 시계열마다 시간에 따른 값을 집계할 수 있다. 반환하는 instant 벡터는 시계열 단위로 집계한 결과를 가지고 있다:

avg_over_time(range-vector): 지정한 기간에 있는 모든 포인트들의 평균 값.
min_over_time(range-vector): 지정한 기간에 있는 모든 포인트들의 최소 값.
max_over_time(range-vector): 지정한 기간에 있는 모든 포인트들의 최대 값.
sum_over_time(range-vector): 지정한 기간에 있는 모든 값들의 합계.
count_over_time(range-vector): 지정한 기간에 있는 모든 값들의 갯수.
quantile_over_time(scalar, range-vector): 지정한 기간에 있는 값들의 φ-quantile (0 ≤ φ ≤ 1).
stddev_over_time(range-vector): 지정한 기간에 있는 값들의 모표준편차.
stdvar_over_time(range-vector): 지정한 기간에 있는 값들의 모분산.
last_over_time(range-vector): 지정한 기간 중 가장 최근 포인트 값.
present_over_time(range-vector): 지정한 기간에 있는 모든 시계열은 값이 1이다.

지정한 기간에 있는 모든 값들은, 해당 기간 동안 값이 균등하게 분포돼있지 않더라도 집계할 땐 동일한 가중치를 가진다.

Trigonometric Functions

아래 있는 삼각 함수들은 라디안으로 동작한다:

acos(v instant-vector): v에 있는 모든 요소의 아크코사인^arccosine을 계산한다 (특이 케이스).
acosh(v instant-vector): v에 있는 모든 요소의 역쌍곡코사인^{inverse hyperbolic cosine}을 계산한다 (특이 케이스).
asin(v instant-vector): v에 있는 모든 요소의 아크사인^arcsine을 계산한다 (특이 케이스).
asinh(v instant-vector): v에 있는 모든 요소의 영쌍곡사인^{inverse hyperbolic sine}을 계산한다 (특이 케이스).
atan(v instant-vector): v에 있는 모든 요소의 아크탄젠트^arctangent를 계산한다 (특이 케이스).
atanh(v instant-vector): v에 있는 모든 요소의 역쌍곡탄젠트^{inverse hyperbolic tangent}를 계산한다 (특이 케이스).
cos(v instant-vector): v에 있는 모든 요소의 코사인^cosine을 계산한다 (특이 케이스).
cosh(v instant-vector): v에 있는 모든 요소의 쌍곡코사인^{hyperbolic cosine}을 계산한다 (특이 케이스).
sin(v instant-vector): v에 있는 모든 요소의 사인^sine을 계산한다 (특이 케이스).
sinh(v instant-vector): v에 있는 모든 요소의 쌍곡사인^{hyperbolic sine}을 계산한다 (특이 케이스).
tan(v instant-vector): v에 있는 모든 요소의 탄젠트^tangent를 계산한다 (특이 케이스).
tanh(v instant-vector): v에 있는 모든 요소의 쌍곡탄젠트^{hyperbolic tangent}를 계산한다 (특이 케이스).

각도와 라디안을 변환할 땐 아래 있는 함수를 활용하면 된다:

deg(v instant-vector): v에 있는 모든 요소에서 라디안을 각도로 변환한다.
pi(): 파이를 반환한다.
rad(v Instant-vector): v에 있는 모든 요소에서 각도를 라디안으로 변환한다.

Next :

Query Examples
PromQL 예제

전체 목차는 여기에 있습니다.

Prometheus

Functions

목차

abs()

absent()

absent_over_time()

ceil()

changes()

clamp()

clamp_max()

clamp_min()

day_of_month()

day_of_week()

days_in_month()

delta()

deriv()

exp()

floor()

histogram_quantile()

holt_winters()

hour()

idelta()

increase()

irate()

label_join()

label_replace()

ln()

log2()

log10()

minute()

month()

predict_linear()

rate()

resets()

round()

scalar()

sgn()

sort()

sort_desc()

sqrt()

time()

timestamp()

vector()

year()

<aggregation>_over_time()