Graphite 템플릿 변수

Graphite 템플릿 변수 (Graphite template variables)

메트릭 쿼리에서 서버·애플리케이션·센서 이름 같은 상세 값을 하드코딩하지 않고 변수를 사용할 수 있어요. Grafana는 변수를 대시보드 상단의 드롭다운 선택 박스에 나열해 표시 데이터를 바꾸기 쉽게 해 주는데, 이를 템플릿 변수라고 해요. Graphite 데이터 소스에서는 쿼리 변수만 만들 수 있고, 태그 기반 변수와 중첩 변수도 지원해요.

출처: 문서

본문

템플릿과 템플릿 변수 소개는 Templating과 변수 추가·관리 문서를 참고하세요. 예제 대시보드는 Graphite Templated Nested dashboard를 참고해요.

쿼리 변수 사용하기

Graphite 데이터 소스에서는 쿼리 변수만 만들 수 있어요. Grafana는 Graphite 기반 변수에 세 가지 쿼리 유형을 지원합니다.

쿼리 유형	설명	예시
Default query	Graphite 함수를 사용해 메트릭·노드·태그 값을 동적으로 나열	`tag_values(apps.*.requests.count, app)`
Value query	메트릭과 함수를 포함한 쿼리의 모든 값을 반환	`tag_values(apps..status., status)`
Metric name query	메트릭과 함수를 포함한 쿼리의 모든 이름을 반환	`apps.*.requests.count`

변수 문법 선택

Graphite 데이터 소스는 Query 필드에서 두 가지 변수 문법을 지원해요.

문법	예시
`$varname`	`apps.frontend.$server.requests.count`
`${varname}`	`apps.frontend.${server}.requests.count`

축약 문법($varname): 간단한 경로에 편리하지만 변수가 다른 문자와 인접하면(cpu$coreLoad) 동작하지 않아요.
전체 문법(${varname}): 더 유연하며 단어 안에 포함되는 등 문자열 어디서나 동작해요.

Graphite 메트릭 경로 구조에 맞는 형식을 선택하세요.

태그 변수 사용하기

Grafana는 Graphite에 태그 기반 변수를 지원해 메트릭 시리즈의 태그 키·값을 기반으로 드롭다운을 동적으로 채울 수 있어요. 변수 쿼리에서 Graphite 함수 tags()와 tag_values()를 사용하세요.

쿼리	설명
`tags()`	Graphite 데이터베이스의 모든 태그 키 목록 반환
`tags(server=~backend\*)`	제공된 필터 표현식과 일치하는 시리즈의 태그 키만 반환
`tag_values(server)`	지정된 태그 키의 모든 값 반환
`tag_values(server, server=~backend\*)`	일치하는 시리즈에 나타나는 값으로 필터링된 태그 값 반환

여러 필터 표현식을 사용할 수 있고, 다른 Grafana 변수를 포함할 수도 있어요.

tag_values(server, server=~backend\*, app=~${apps:regex})

이 쿼리는 server 태그가 backend*와 일치하고 app 태그가 다른 변수 ${apps}의 regex 필터 값과 일치하는 시리즈의 모든 server 태그 값을 반환해요. 자세한 내용은 Graphite tags 자동완성 API 문서를 참고하세요.

정규 표현식 포맷과 등가 물결 연산자(=~) 사용:

server=~${servers:regex}

이 쿼리는 servers 변수의 선택 값을 정규 표현식으로 포맷해요(두 서버 선택 시 (server1|server2)처럼). 자세한 내용은 고급 변수 포맷 옵션을 참고하세요.

여러 표현식으로 필터링

태그 쿼리에서 다중 값 변수를 사용할 때 변수 이름에 ${var:regex}를 붙여 regex 포맷을 적용하세요.

tag_values(server, app=~${apps:regex})

이 쿼리는 app 태그가 ${apps} 선택 값(regex로 포맷)과 일치하는 시리즈만 반환해요. =~는 정규 표현식 연산자입니다. 태그가 아닌 쿼리는 다중 값 변수에 기본 glob 포맷을 사용해요.

다른 쿼리 변수 사용하기

쿼리를 작성할 때 metric find 쿼리 유형으로 동적 값을 가져오세요. 예를 들어 쿼리 prod.servers.*는 와일드카드 위치(*)에 존재하는 모든 값으로 변수를 채워요. 결과에는 쿼리 경로의 마지막 레벨에서 찾은 값만 포함된다는 점에 주의하세요. 전체 메트릭 경로를 반환하려면 expand() 함수를 사용하세요.

expand(*.servers.*).

확장/비확장 메트릭 검색 결과 비교

확장 쿼리(expand() 함수): 쿼리와 일치하는 전체 메트릭 경로를 반환
비확장 쿼리: 각 일치 메트릭 경로의 마지막 세그먼트만 반환 → 메트릭 이름의 더 깊은 부분을 추출·필터링하는 데 제약

예: 데이터베이스에 prod.servers.001.cpu, prod.servers.002.cpu, test.servers.001.cpu가 있을 때:

비확장 쿼리	결과	확장 쿼리	확장 결과
`*`	`prod`, `test`	`expand(*)`	`prod`, `test`
`*.servers`	`servers`	`expand(*.servers)`	`prod.servers`, `test.servers`
`test.servers`	`servers`	`expand(test.servers)`	`test.servers`
`.servers.`	`001`, `002`	`expand(.servers.)`	`prod.servers.001`, `prod.servers.002`, `test.servers.001`
`test.servers.*`	`001`	`expand(test.servers.*)`	`test.servers.001`
`.servers..cpu`	`cpu`	`expand(.servers..cpu)`	`prod.servers.001.cpu`, `prod.servers.002.cpu`, `test.servers.001.cpu`

참고: 비확장 쿼리는 확장 쿼리처럼 동작하지만 각 일치 메트릭의 마지막 세그먼트만 반환해요.

Grafana는 쿼리에서 다른 변수를 참조할 수 있는 중첩 변수도 지원해요. 예:

apps.$app.servers.*

이 쿼리는 $app 변수의 선택 값을 사용해 메트릭 경로를 동적으로 필터링합니다.

__searchFilter로 쿼리 변수 결과 필터링

Grafana는 변수 __searchFilter를 제공해 사용자가 변수 드롭다운에 입력한 내용에 따라 쿼리 결과를 동적으로 필터링할 수 있어요. 빈 값이면 __searchFilter는 *로 기본 설정되어 모든 값을 반환하고, 문자열을 입력하면 그 입력으로 치환됩니다.

Query:

apps.$app.servers.$__searchFilter

TagValues:

tag_values(server, server=~${__searchFilter:regex})

Graphite 템플릿 변수