기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# 레이블 및 주석 템플릿 지정
****
이 설명서 주제는 **Grafana 버전 9.x**를 지원하는 Grafana 워크스페이스를 위해 설계되었습니다.
Grafana 버전 12.x를 지원하는 Grafana 워크스페이스는 섹션을 참조하세요[Grafana 버전 12에서 작업](using-grafana-v12.md).
Grafana 버전 10.x를 지원하는 Grafana 워크스페이스의 경우 [Grafana 버전 10에서 작업](using-grafana-v10.md) 섹션을 참조하세요.
Grafana 버전 8.x를 지원하는 Grafana 워크스페이스의 경우 [Grafana 버전 8에서 작업](using-grafana-v8.md) 섹션을 참조하세요.
Grafana에서는 Prometheus에서와 마찬가지로 레이블 및 주석을 템플릿으로 지정합니다. 이전에 Prometheus를 사용한 적이 있는 경우 알림의 레이블 및 값을 포함하는 `$labels` 및 `$value` 변수에 익숙할 것입니다. 알림이 Prometheus 데이터 소스를 사용하지 않더라도 Grafana에서 동일한 변수를 사용할 수 있습니다. 이전에 Prometheus를 사용한 적이 없는 경우에도 걱정하지 마세요. 이러한 각 변수와 이를 템플릿으로 지정하는 방법은 이 페이지의 나머지 부분에서 설명합니다.
## Go의 템플릿 지정 언어
레이블 및 주석의 템플릿은 Go의 템플릿 지정 언어인 [text/template](https://pkg.go.dev/text/template)으로 작성됩니다.
**여는 태그 및 닫는 태그**
text/template에서 템플릿은 템플릿이 변수를 인쇄하는지 여부와 if 문과 같이 제어 구조를 실행하는지 여부에 관계없이 `{{`로 시작하고 `}}`로 끝납니다. Jinja(변수를 인쇄할 때 `{{` 및 `}}`를 사용하고 제어 구조에서 `{%` 및 `%}`를 사용함)와 같은 다른 템플릿 지정 언어와는 다릅니다.
**인쇄**
무언가의 값을 인쇄하려면 `{{` 및 `}}`를 사용합니다. 함수의 결과 또는 변수 값을 인쇄할 수 있습니다. 예를 들어 `$labels` 변수를 인쇄하려면 다음을 작성합니다.
```
{{ $labels }}
```
**레이블에 대해 반복**
`$labels`에서 각 레이블을 반복하기 위해 `range`를 사용할 수 있습니다. 여기서 `$k`는 이름, `$v`는 현재 레이블의 값을 나타냅니다. 예를 들어 쿼리에서 `instance=test` 레이블을 반환하는 경우 `$k`는 `instance`이고 `$v`는 `test`입니다.
```
{{ range $k, $v := $labels }}
{{ $k }}={{ $v }}
{{ end }}
```
## 레이블, 값 및 값 변수
**레이블 변수**
`$labels` 변수에는 쿼리의 레이블이 포함됩니다. 예를 들어 인스턴스가 중단되었는지 확인하는 쿼리에서 중단된 인스턴스의 이름이 포함된 인스턴스 레이블을 반환할 수 있습니다. 예를 들어 인스턴스 중 하나가 5분 넘게 중단되었을 때 실행되는 알림 규칙이 있다고 가정합니다. 어떤 인스턴스가 중단되었는지 알려주는 요약을 알림에 추가하려고 합니다. `$labels` 변수를 사용하여 요약에서 인스턴스 레이블을 인쇄하는 요약을 생성할 수 있습니다.
```
Instance {{ $labels.instance }} has been down for more than 5 minutes
```
**점을 포함하는 레이블**
인쇄하려는 레이블이 해당 이름에서 점(마침표)을 포함하는 경우 템플릿에서 동일한 점을 사용하는 방식은 작동하지 않습니다.
```
Instance {{ $labels.instance.name }} has been down for more than 5 minutes
```
이는 템플릿이 `$labels.instance`에서 `name`이라고 하는 기존 이외 필드를 사용하려고 하기 때문입니다. 대신 `index` 함수를 사용해야 합니다. 이 함수에서는 `$labels` 변수에서 `instance.name` 레이블을 인쇄합니다.
```
Instance {{ index $labels "instance.name" }} has been down for more than 5 minutes
```
**변수 값**
`$value` 변수는 Prometheus와 다르게 작동합니다. Prometheus에서 `$value`는 표현식의 값을 포함하는 부동 소수점 숫자이지만 Grafana에서는 이 알림 규칙의 모든 임계치, 축소 및 수학 표현식, 클래식 조건의 레이블 및 값을 포함하는 문자열입니다. 쿼리 결과는 포함되지 않습니다. 10s\~10,000s의 행 또는 지표를 반환할 수 있기 때문입니다.
알림 요약에서 `$value` 변수를 사용하는 경우:
```
{{ $labels.service }} has over 5% of responses with 5xx errors: {{ $value }})
```
요약은 다음과 같을 수 있습니다.
```
api has an over 5% of responses with 5xx errors: [ var='B' labels={service=api} value=6.789 ]
```
여기에서 `var='B'`는 RefID B를 사용하는 표현식을 참조합니다. Grafana에서 모든 쿼리 및 표현식은 알림 규칙의 각 쿼리 및 표현식을 식별하는 RefID로 식별됩니다. 마찬가지로 `labels={service=api}`는 레이블을 참조하고 `value=6.789`는 값을 참조합니다.
이 경우 RefID A가 없습니다. 대부분의 알림 규칙에서 RefID A는 쿼리를 참조하고 쿼리는 `$value`에 포함되지 않은 많은 행 또는 시계열을 반환할 수 있기 때문입니다.
**변수 값**
`$value` 변수에 필요한 것보다 많은 정보가 포함된 경우 대신 `$values`를 사용하여 개별 표현식의 레이블 및 값을 인쇄할 수 있습니다. `$value`와 달리 `$values` 변수는 각 표현식의 레이블 및 부동 소수점 값을 포함하는 객체 테이블이며 해당 RefID로 인덱싱됩니다.
알림 요약에서 `B` RefID와 함께 표현식 값을 인쇄하는 경우:
```
{{ $labels.service }} has over 5% of responses with 5xx errors: {{ $values.B }}%
```
요약에는 값만 포함됩니다.
```
api has an over 5% of responses with 5xx errors: 6.789%
```
`{{ $values.B }}`는 숫자 6.789를 인쇄합니다. 하지만 실제로 B의 부동 소수점 값이 아니라 RefID B의 레이블 및 값을 모두 포함하는 객체를 인쇄할 때 이는 문자열입니다. RefID B의 부동 소수점 값을 사용하려면 `$values.B`에서 `Value` 필드를 사용해야 합니다. 알림 요약에서 부동 소수점 값을 가독 가능한 값으로 변환한 경우:
```
{{ $labels.service }} has over 5% of responses with 5xx errors: {{ humanize $values.B.Value }}%
```
**데이터 없음, 런타임 오류 및 제한 시간 초과**
알림 규칙의 쿼리에서 데이터 없음을 반환하거나 데이터 소스 오류 또는 제한 시간으로 인해 실패하는 경우 해당 쿼리를 사용하는 모든 임계치, 축소 또는 수학 표현식에서도 데이터 없음 또는 오류를 반환합니다. 이 경우 `$values`에 이러한 표현식이 없습니다. RefID를 사용하기 전에 존재 여부를 확인하는 것이 좋습니다. 그렇지 않으면 쿼리에서 데이터 없음 또는 오류를 반환하는 경우 템플릿이 중단됩니다. if 문을 사용하여 이 작업을 수행할 수 있습니다.
```
{{ if $values.B }}{{ $labels.service }} has over 5% of responses with 5xx errors: {{ humanizePercentage $values.B.Value }}{{ end }}
```
## 클래식 조건
규칙이 임계치, 축소 및 수학 표현식 대신 클래식 조건을 사용하는 경우 `$values` 변수는 클래식 조건에서 조건의 참조 ID 및 위치에 의해 인덱싱됩니다. 예를 들어 두 조건을 포함하는 RefID B를 사용하는 클래식 조건이 있는 경우 `$values`에는 두 조건(`B0` 및 `B1`)이 포함됩니다.
```
The first condition is {{ $values.B0 }}, and the second condition is {{ $values.B1 }}
```
## 함수
다음 함수는 레이블 및 주석을 확장히는 경우에도 사용할 수 있습니다.
**args**
`args` 함수는 객체 목록을 arg0, arg1 등의 키가 포함된 맵으로 변환합니다. 이는 여러 인수를 템플릿으로 전달할 수 있도록 제공됩니다.
**예제**
```
{{define "x"}}{{.arg0}} {{.arg1}}{{end}}{{template "x" (args 1 "2")}}
```
```
1 2
```
**externalURL**
이 `externalURL` 함수에서는 하나 이상의 ini 파일에 구성된 대로, Grafana 서버의 외부 URL을 반환합니다.
**예제**
```
{{ externalURL }}
```
```
https://example.com/grafana
```
**graphLink**
`graphLink` 함수는 지정된 표현식 및 데이터 소스에서 [Grafana 버전 9에서의 탐색](v9-explore.md)의 그래픽 보기 경로를 반환합니다.
**예제**
```
{{ graphLink "{\"expr\": \"up\", \"datasource\": \"gdev-prometheus\"}" }}
```
```
/explore?left=["now-1h","now","gdev-prometheus",{"datasource":"gdev-prometheus","expr":"up","instant":false,"range":true}]
```
**humanize**
`humanize` 함수는 십진수를 가독 가능한 값으로 변환합니다.
**예제**
```
{{ humanize 1000.0 }}
```
```
1k
```
**humanize1024**
`humanize1024`는 `humanize`와 비슷하게 작동하지만 1000이 아닌 1024를 밑으로 사용합니다.
**예제**
```
{{ humanize1024 1024.0 }}
```
```
1ki
```
**humanizeDuration**
`humanizeDuration` 함수는 초 단위로 기간을 가독 가능한 값으로 변환합니다.
**예제**
```
{{ humanizeDuration 60.0 }}
```
```
1m 0s
```
**humanizePercentage**
`humanizePercentage` 함수는 비율 값을 백분율로 표시하여 가독 가능한 값으로 변환합니다.
**예제**
```
{{ humanizePercentage 0.2 }}
```
```
20%
```
**humanizeTimestamp**
`humanizeTimestamp` 함수는 Unix 타임스탬프를 가독 가능한 값으로 변환합니다.
**예제**
```
{{ humanizeTimestamp 1577836800.0 }}
```
```
2020-01-01 00:00:00 +0000 UTC
```
**match**
`match` 함수는 정규식 패턴을 기준으로 텍스트를 일치시킵니다.
**예제**
```
{{ match "a.*" "abc" }}
```
```
true
```
**pathPrefix**
이 `pathPrefix` 함수에서는 하나 이상의 ini 파일에 구성된 대로, Grafana 서버의 경로를 반환합니다.
**예제**
```
{{ pathPrefix }}
```
```
/grafana
```
**tableLink**
`tableLink` 함수는 지정된 표현식 및 데이터 소스에서 [Grafana 버전 9에서의 탐색](v9-explore.md)의 테이블 보기 경로를 반환합니다.
**예제**
```
{{ tableLink "{\"expr\": \"up\", \"datasource\": \"gdev-prometheus\"}" }}
```
```
/explore?left=["now-1h","now","gdev-prometheus",{"datasource":"gdev-prometheus","expr":"up","instant":true,"range":false}]
```
**제목**
`title` 함수에서는 각 단어의 첫 번째 문자를 대문자로 표시합니다.
**예제**
```
{{ title "hello, world!" }}
```
```
Hello, World!
```
**toLower**
`toLower` 함수는 모든 텍스트를 소문자로 반환합니다.
**예제**
```
{{ toLower "Hello, world!" }}
```
```
hello, world!
```
**toUpper**
`toUpper` 함수는 모든 텍스트를 대문자로 반환합니다.
**예제**
```
{{ toUpper "Hello, world!" }}
```
```
HELLO, WORLD!
```
**reReplaceAll**
`reReplaceAll` 함수는 정규식과 일치하는 텍스트를 대체합니다.
**예제**
```
{{ reReplaceAll "localhost:(.*)" "example.com:$1" "localhost:8080" }}
```
```
example.com:8080
```