템플릿 참고

템플릿 참고 (Template reference)

Prometheus의 알림 어노테이션·라벨과 콘솔 페이지에서 템플릿을 쓸 수 있어요. 템플릿은 로컬 데이터베이스에 쿼리를 실행하고, 데이터를 순회하며, 조건을 쓰고, 데이터를 포맷할 수 있어요. 템플릿 언어는 Go 템플릿 시스템을 기반으로 해요. 이 문서는 템플릿에서 쓸 수 있는 데이터 구조와 모든 함수를 정리한 참고 페이지예요.

함수 이름과 시그니처는 그대로 두고, 각 함수가 무엇을 하는지 한국어로 풀어드릴게요. 템플릿을 직접 작성할 때 이 페이지를 옆에 두고 참고하면 좋아요.

출처: 문서

본문

Prometheus는 알림의 어노테이션과 라벨, 그리고 서빙되는 콘솔 페이지에서 템플릿을 지원해요. 템플릿은 로컬 데이터베이스에 대해 쿼리를 실행하고, 데이터를 순회하며, 조건을 사용하고, 데이터를 포맷하는 등의 능력을 가져요. Prometheus 템플릿 언어는 Go 템플릿 시스템을 기반으로 해요.

데이터 구조 (Data Structures)

타임시리즈 데이터를 다루는 기본 데이터 구조는 샘플(sample)이며, 다음과 같이 정의돼요:

type sample struct {
  Labels map[string]string
  Value  interface{}
}

샘플의 메트릭 이름은 Labels 맵의 특수 __name__ 라벨에 인코딩돼요.

[]sample은 샘플의 목록을 의미해요.

Go의 interface{}는 C의 void 포인터와 비슷해요.

함수 (Functions)

Go 템플릿이 제공하는 기본 함수 외에, Prometheus는 템플릿에서 쿼리 결과를 더 쉽게 처리하기 위한 함수를 제공해요.

함수가 파이프라인에서 사용되면 파이프라인 값이 마지막 인자로 전달돼요.

쿼리 (Queries)

이름 인자 반환 참고
query query string []sample 데이터베이스를 쿼리. 범위 벡터 반환은 지원하지 않음.
first []sample sample index a 0과 동등
label label, sample string index sample.Labels label과 동등
value sample interface{} sample.Value와 동등
sortByLabel label, []sample []sample 주어진 라벨로 샘플을 정렬. 안정적(stable)임.

first, label, value는 파이프라인에서 쿼리 결과를 쉽게 사용할 수 있게 하기 위한 것이에요.

숫자 (Numbers)

이름 인자 반환 참고
humanize number 또는 string string 메트릭 접두사를 사용해 숫자를 더 읽기 쉬운 형식으로 변환.
humanize1024 number 또는 string string humanize와 같지만 1000 대신 1024를 밑으로 사용.
humanizeDuration number 또는 string string 초 단위 지속시간을 더 읽기 쉬운 형식으로 변환.
humanizePercentage number 또는 string string 비율 값을 100 분율로 변환.
humanizeTimestamp number 또는 string string 초 단위 Unix 타임스탬프를 더 읽기 쉬운 형식으로 변환.
toTime number 또는 string *time.Time 초 단위 Unix 타임스탬프를 time.Time으로 변환.
toDuration number 또는 string *time.Duration 초 단위 지속시간을 time.Duration으로 변환.
now 없음 float64 템플릿 평가 시점의 초 단위 Unix 타임스탬프를 반환.

humanize 계열 함수는 사람이 소비하기에 합리적인 출력을 만들기 위한 것이며, Prometheus 버전 사이에 같은 결과를 반환한다는 보장은 없어요.

문자열 (Strings)

이름 인자 반환 참고
title string string cases.Title, 각 단어의 첫 문자를 대문자로.
toUpper string string strings.ToUpper, 모든 문자를 대문자로 변환.
toLower string string strings.ToLower, 모든 문자를 소문자로 변환.
stripPort string string net.SplitHostPort, 문자열을 호스트와 포트로 분리한 뒤 호스트만 반환.
match pattern, text boolean regexp.MatchString, 고정되지 않은(unanchored) 정규식 일치 테스트.
reReplaceAll pattern, replacement, text string Regexp.ReplaceAllString, 고정되지 않은 정규식 치환.
graphLink expr string 표현식에 대한 표현식 브라우저의 그래프 뷰 경로를 반환.
tableLink expr string 표현식에 대한 표현식 브라우저의 표("Table") 뷰 경로를 반환.
parseDuration string float "1h" 같은 지속시간 문자열을 그것이 나타내는 초 수로 파싱.
stripDomain string string FQDN의 도메인 부분을 제거. 포트는 그대로 둠.
urlQueryEscape string string url.QueryEscape, URL 쿼리 안에 안전하게 넣을 수 있도록 문자열을 이스케이프.

기타 (Others)

이름 인자 반환 참고
args []interface{} map[string]interface{} 객체 목록을 arg0, arg1 등의 키를 가진 맵으로 변환. 템플릿에 여러 인자를 전달하도록 의도됨.
tmpl string, []interface{} 없음 내장 template과 같지만 템플릿 이름으로 리터럴이 아닌 값을 허용. 결과가 안전하다고 간주되어 자동 이스케이프되지 않음. 콘솔에서만 사용 가능.
safeHtml string string 자동 이스케이프가 필요 없는 HTML로 문자열을 표시.
externalURL 없음 string Prometheus가 외부에서 도달할 수 있는 외부 URL.
pathPrefix 없음 string 콘솔 템플릿에서 사용할 외부 URL 경로.

템플릿 타입 차이 (Template type differences)

각 템플릿 타입은 템플릿을 파라미터화하는 데 사용할 수 있는 서로 다른 정보를 제공하며, 몇 가지 다른 차이도 있어요.

알림 필드 템플릿 (Alert field templates)

.Value, .Labels, .ExternalLabels, .ExternalURL은 각각 알림 값, 알림 라벨, 전역적으로 구성된 외부 라벨, 외부 URL(--web.external-url로 구성)을 담아요. 이것들은 편의를 위해 $value, $labels, $externalLabels, $externalURL 변수로도 노출돼요.

콘솔 템플릿 (Console templates)

콘솔은 /consoles/에 노출되며, -web.console.templates 플래그가 가리키는 디렉터리에서 가져와요.

콘솔 템플릿은 자동 이스케이프를 제공하는 html/template으로 렌더링돼요. 자동 이스케이프를 우회하려면 safe* 함수를 사용하세요.

URL 파라미터는 .Params의 맵으로 사용할 수 있어요. 같은 이름의 여러 URL 파라미터에 접근하려면 .RawParams가 각 파라미터의 목록 값 맵이에요. URL 경로는 /consoles/ 접두사를 제외하고 .Path로 사용할 수 있어요. 전역적으로 구성된 외부 라벨은 .ExternalLabels로 사용할 수 있어요. 네 가지 모두에 대한 편의 변수($rawParams, $params, $path, $externalLabels)도 있어요.

콘솔은 또한 -web.console.libraries 플래그가 가리키는 디렉터리의 *.lib 파일에서 {{define "templateName"}}...{{end}}로 정의된 모든 템플릿에 접근할 수 있어요. 이것은 공유 네임스페이스이므로 다른 사용자와의 충돌을 피하도록 주의하세요. prom, _prom, __로 시작하는 템플릿 이름과 위에 나열된 함수는 Prometheus가 사용하도록 예약돼 있어요.

더 알아보기 (Learn more)