알림 템플릿 언어

알림 템플릿 언어 (Alerting template language)

알림 템플릿(notification templates)과 알림 규칙 템플릿(alert rule templates, 예: annotations, labels)은 모두 Go 템플릿 언어인 text/template을 사용해요. range, if, and, index, eq 등 같은 키워드·함수·비교 연산자를 공유해요.

출처: 문서

본문

알림 템플릿과 알림 규칙 템플릿(annotations, labels 등)은 모두 Go 템플릿 언어 text/template을 사용해요.

두 템플릿 유형 모두 Go 템플릿 언어의 같은 키워드, 함수, 비교 연산자(range, if, and, index, eq 등)를 사용할 수 있어요.

다만 알림(notifications)과 알림 규칙(alert rules)이 별개의 컨텍스트에서 동작하기 때문에 일부 추가 변수와 함수는 알림 템플릿이나 알림 규칙 템플릿 중 하나에서만 사용할 수 있다는 점을 기억해야 해요. 다음을 참고하세요:

이 문서는 알림 템플릿과 알림 규칙 템플릿 모두에서 사용할 수 있는 Go 템플릿 언어의 함수와 연산자 개요를 제공해요.

출력 (Print)

무언가의 값을 출력하려면 {{와 }}를 사용해요. 변수의 값, 변수의 필드, 함수의 결과, 또는 dot의 값을 출력할 수 있어요.

{{ $values }}
{{ $values.A.Value }}
{{ humanize 1000.0 }}
{{ .Alerts }}

Dot

text/template에는 점(.)으로 쓰는 특별한 커서인 dot이 있어요. 이 커서를 템플릿에서 사용된 위치에 따라 값이 변하는 변수로 생각할 수 있어요.

알림 템플릿의 시작에서 dot(.)은 Notification Data를 가리켜요.

{{ .Alerts }}

annotation 및 label 템플릿에서 dot(.)은 모든 알림 데이터로 초기화돼요. 알림 라벨과 쿼리 값에 직접 접근하려면 $labels와 $values 변수를 사용하는 것을 권장해요.

Note

dot(.)은 range, with에서 사용하거나 다른 템플릿에서 사용하는 템플릿을 작성할 때 다른 것을 가리킬 수 있어요.

If

템플릿에서 if 문을 사용할 수 있어요. 예를 들어 변수가 비어 있을 때 Variable empty를 출력할 수 있어요:

{{ if $element }}
Element value: {{$element}}
{{ else }}
Element is empty
{{ end }}

With

with는 if 문과 비슷하지만, if와 달리 with 안의 표현식 값을 가리키도록 dot(.)을 업데이트해요:

{{ with $array }}
There are {{ len . }} item(s)
{{ else }}
There are no alerts
{{ end }}

Range

range는 배열 또는 맵을 순회하며, dot(.)이 배열의 현재 요소로 설정돼요:

{{ range $array }}
{{ .itemPropertyName }}
{{ end }}

선택적으로 else로 빈 객체를 처리할 수 있어요:

{{ range $array }}
  {{ .itemPropertyName }}
{{ else }}
  Empty array
{{ end }}

range 시작 부분에서 인덱스와 값 변수를 정의해 각 항목의 인덱스를 얻을 수도 있어요:

{{ $num_items := len $array }}
{{ range $index, $item := $array }}
This is item {{ $index }} out of {{ $num_items }}
{{ end }}

추가로 {{break}}로 남은 반복을 중지하거나, {{continue}}로 현재 반복을 중지하고 다음으로 계속할 수 있어요.

함수 (Functions)

text/template에서 사용 가능한 전역 함수는:

함수	설명
`and`	첫 번째 빈 인자 또는 마지막 인자를 반환해 인자의 boolean AND를 반환
`call`	함수여야 하는 첫 번째 인자를 나머지 인자를 파라미터로 호출한 결과 반환
`html`	인자의 텍스트 표현에 해당하는 이스케이프된 HTML 반환
`index`	첫 번째 인자를 다음 인자들로 인덱싱한 결과 반환. 예: `{{ index $labels "instance" }}`는 `$labels` 맵 변수의 `instance` 키를 반환
`slice`	첫 번째 인자를 나머지 인자로 슬라이싱한 결과 반환
`js`	인자의 텍스트 표현에 해당하는 이스케이프된 JavaScript 반환
`len`	인자의 정수 길이 반환. 예: `{{ len $array }}`
`not`	단일 인자의 boolean 부정 반환
`or`	첫 번째 비어 있지 않은 인자 또는 마지막 인자를 반환해 인자의 boolean OR 반환
`print`	fmt.Sprint의 별칭
`printf`	fmt.Sprintf의 별칭
`println`	fmt.Sprintln의 별칭
`urlquery`	URL 쿼리에 포함하기에 적합한 형태로 인자의 텍스트 표현의 이스케이프 값 반환

자세한 내용은 text/template의 함수 공식 문서를 참고해요.

비교 연산자 (Comparison operators)

text/template에서는 boolean 비교 연산자도 사용할 수 있어요:

함수	설명
`eq`	arg1 == arg2의 boolean 진리값 반환
`ne`	arg1 != arg2의 boolean 진리값 반환
`lt`	arg1 < arg2의 boolean 진리값 반환
`le`	arg1 <= arg2의 boolean 진리값 반환
`gt`	arg1 > arg2의 boolean 진리값 반환
`ge`	arg1 >= arg2의 boolean 진리값 반환

변수 (Variables)

text/template의 변수는 템플릿 내에서 생성해야 해요. 예를 들어 dot(.)의 현재 값으로 변수를 만들고 문자열이나 다른 객체를 변수에 할당할 수 있어요:

{{ $variable := . }}
{{ $variable := "This is a test" }}
{{ $variable }}

이 템플릿은 다음을 출력해요:

This is a test

템플릿 (Templates)

다른 템플릿에서 또는 같은 템플릿 안에서 실행할 수 있는 재사용 가능한 템플릿을 만들 수 있어요.

define과 큰따옴표 안의 템플릿 이름으로 템플릿을 정의해요:

{{ define "print_labels" }}
{{ end }}

__subject, __text_values_list, __text_alert_list, default.title, default.message 같은 기본 템플릿을 포함해 다른 템플릿과 같은 이름으로 템플릿을 정의해서는 안 돼요. 기본 템플릿이나 다른 알림 템플릿의 템플릿과 같은 이름으로 템플릿을 만들면 Grafana가 둘 중 아무거나 사용할 수 있어요. Grafana는 같은 이름의 템플릿이 두 개 이상 있어도 막지 않고 오류 메시지도 표시하지 않아요.

템플릿 실행 (Execute templates)

정의된 템플릿은 template, 큰따옴표 안의 템플릿 이름, 그리고 템플릿에 전달할 커서를 사용해 실행할 수 있어요:

{{ template "print_labels" . }}

템플릿 안에서 dot는 템플릿에 전달된 값을 가리켜요.

예를 들어 템플릿에 절정(firing) 알림 목록이 전달되면 dot는 그 절정 알림 목록을 가리켜요:

{{ template "print_alerts" .Alerts }}

템플릿에 알림의 정렬된 라벨이 전달되면 dot는 정렬된 라벨 목록을 가리켜요:

{{ template "print_labels" .SortedLabels }}

이것은 재사용 가능한 템플릿을 작성할 때 유용해요. 예를 들어 모든 알림을 출력하려면 다음을 작성해요:

{{ template "print_alerts" .Alerts }}

그런 다음 절정 알림만 출력하려면 이렇게 쓸 수 있어요:

{{ template "print_alerts" .Alerts.Firing }}

.Alerts와 .Alerts.Firing이 모두 알림 목록이기 때문에 이 작업이 작동해요.

{{ define "print_alerts" }}
{{ range . }}
{{ template "print_labels" .SortedLabels }}
{{ end }}
{{ end }}

Note

알림 템플릿처럼 라벨과 annotations에 대한 독립적이고 재사용 가능한 템플릿을 만들 수는 없어요. 알림 규칙 템플릿에서는 각 템플릿을 라벨 또는 annotation 필드 안에 인라인으로 작성해야 해요.

주석 (Comments)

{{/*와 */}}로 주석을 추가할 수 있어요:

{{/* This is a comment */}}

줄 바꿈을 피하려면 다음을 사용해요:

{{- /* This is a comment with no leading or trailing line breaks */ -}}

들여쓰기 (Indentation)

템플릿을 더 읽기 쉽게 만들기 위해 탭과 공백, 줄 바꿈을 사용한 들여쓰기를 사용할 수 있어요:

{{ range .Alerts }}
  {{ range .Labels.SortedPairs }}
    {{ .Name }} = {{ .Value }}
  {{ end }}
{{ end }}

하지만 템플릿의 들여쓰기는 텍스트에도 나타나요.

공백과 줄 바꿈 제거 (Remove spaces and line breaks)

text/template에서 {{-와 -}}를 사용해 시작·끝 공백과 줄 바꿈을 제거해요.

예를 들어 템플릿을 더 읽기 쉽게 만들기 위해 들여쓰기와 줄 바꿈을 사용할 때:

{{ range .Alerts }}
  {{ range .Labels.SortedPairs }}
    {{ .Name }} = {{ .Value }}
  {{ end }}
{{ end }}

들여쓰기와 줄 바꿈은 텍스트에도 나타나요:

    alertname = "Test"

    grafana_folder = "Test alerts"

각 range 시작 부분에서 }}를 -}}로 바꿔 텍스트에서 들여쓰기와 줄 바꿈을 제거할 수 있어요:

{{ range .Alerts -}}
  {{ range .Labels.SortedPairs -}}
    {{ .Name }} = {{ .Value }}
  {{ end }}
{{ end }}

템플릿의 들여쓰기와 줄 바꿈이 이제 텍스트에 없어요:

alertname = "Test"
grafana_folder = "Test alerts"

알림 템플릿 언어