OpenTSDB 템플릿 변수

OpenTSDB 템플릿 변수 (OpenTSDB template variables)

메트릭 쿼리에서 서버·애플리케이션·센서 이름을 하드코딩하지 않고 템플릿 변수를 사용할 수 있어요. 변수는 대시보드 상단의 드롭다운 메뉴로 나타나므로 쿼리를 편집하지 않고 표시 데이터를 바꿀 수 있죠. OpenTSDB 데이터 소스는 OpenTSDB에서 직접 값을 가져오는 쿼리형 변수를 지원하고, 중첩 변수·다중 값 변수도 쓸 수 있어요.

출처: 문서

본문

쿼리 변수

OpenTSDB 데이터 소스는 OpenTSDB에서 직접 값을 가져오는 쿼리형 템플릿 변수를 지원해요. 데이터베이스 데이터에 따라 동적으로 채워집니다.

지원되는 쿼리 함수

쿼리	설명	사용 API
`metrics(prefix)`	접두사와 일치하는 메트릭 이름 반환. 빈 괄호는 모든 메트릭	`/api/suggest?type=metrics`
`tag_names(metric)`	특정 메트릭에 존재하는 태그 키(이름) 반환	`/api/search/lookup`
`tag_values(metric, tagkey)`	특정 메트릭·태그 키의 태그 값 반환	`/api/search/lookup`
`suggest_tagk(prefix)`	모든 메트릭에서 접두사와 일치하는 태그 키 반환	`/api/suggest?type=tagk`
`suggest_tagv(prefix)`	모든 메트릭에서 접두사와 일치하는 태그 값 반환	`/api/suggest?type=tagv`

참고: tag_names와 tag_values는 lookup API를 사용하므로 데이터베이스에 메트릭이 존재해야 해요. suggest_tagk와 suggest_tagv는 모든 메트릭을 검색하는 suggest API를 사용해요.

쿼리 변수 만들기

업데이트할 대시보드로 이동해 Edit 클릭
Add new element 아이콘(파란 더하기) 클릭
Variable 클릭
변수 유형으로 Query 선택
변수 Name 입력 (예: host)
Display 드롭다운에서 변수 표시 위치 선택
Open variable editor 클릭해 Query Variable 대화상자 열기
OpenTSDB 데이터 소스 선택
지원 쿼리 함수 중 하나로 쿼리 입력
Close 클릭
(선택) Multi-value 구성
(선택) Include All value 구성
(선택) Allow custom values 활성화
Save 클릭 후 (선택) 설명 입력, Save, Exit edit

쿼리 변수 예시

모든 메트릭 나열: metrics() → 데이터베이스의 모든 메트릭 이름
접두사가 있는 메트릭 나열: metrics(sys.cpu) → sys.cpu.user, sys.cpu.system, sys.cpu.idle 등
메트릭의 태그 키 나열: tag_names(sys.cpu.user) → host, env, datacenter 등
메트릭·태그 키의 태그 값 나열: tag_values(sys.cpu.user, host) → webserver01, webserver02, dbserver01 등
접두사로 태그 키 검색: suggest_tagk(host) → host, hostname, host_id 등
접두사로 태그 값 검색: suggest_tagv(web) → webserver01, webserver02, web-prod-01 등

Preview of values 섹션에 변수가 채워지지 않으면 Troubleshooting을 참고하세요.

중첩 템플릿 변수

한 템플릿 변수로 다른 변수의 값을 필터링할 수 있어요. 데이터센터를 먼저 선택하면 그 데이터센터의 호스트만 보여주는 캐스케이딩 필터를 만들 수 있죠.

필터 문법

tag_values 함수는 태그 키 뒤에 추가 태그 필터를 받아요.

tag_values(metric, tagkey, tag1=value1, tag2=value2, ...)

필터 값으로 템플릿 변수를 사용해 동적 의존을 만들 수 있어요.

tag_values(metric, tagkey, tag1=$variable1, tag2=$variable2)

중첩 변수 예시

쿼리	설명
`tag_values(sys.cpu.user, host, env=$env)`	선택된 `env` 값으로 필터링된 host 값 반환
`tag_values(sys.cpu.user, host, env=$env, datacenter=$dc)`	`env`와 `datacenter` 둘 다로 필터링된 host 값 반환
`tag_values(app.requests, endpoint, service=$service)`	선택된 service의 endpoint 값 반환

캐스케이딩 필터 만들기

부모 변수: Name datacenter, Query tag_values(sys.cpu.user, datacenter)
자식 변수: Name host, Query tag_values(sys.cpu.user, host, datacenter=$datacenter)
추가 레벨: Name cpu, Query tag_values(sys.cpu.user, cpu, datacenter=$datacenter, host=$host)

사용자가 데이터센터 선택을 바꾸면 host 변수가 자동으로 그 데이터센터의 호스트만 보여주도록 갱신돼요.

쿼리에서 변수 사용하기

$variablename 또는 ${variablename} 문법으로 변수를 참조하세요. 실행 시 Grafana가 변수를 현재 값으로 치환해요.

필드	예시	설명
Metric	`$metric`	쿼리할 메트릭을 동적으로 선택
Tag value	`host=$host`	변수로 선택한 태그 값으로 필터링
Filter value	`$host`	필터 값 필드에서 사용
Alias	`$tag_host - $host`	범례 라벨에 변수 값 포함
Downsample interval	`$interval`	다운샘플 간격에 변수 사용

변수 문법 옵션

문법	설명
`$variablename`	대부분의 경우에 쓰는 단순 문법
`${variablename}`	변수가 다른 텍스트와 인접할 때(예: `${host}_suffix`)
`${variablename:format}`	변수 값에 특정 포맷 적용

다중 값 변수

변수에 Multi-value를 활성화하면 여러 값을 동시에 선택할 수 있어요. OpenTSDB 데이터 소스는 다중 값 변수를 파이프(|) 구분으로 처리하며, 이는 OpenTSDB의 literal_or 필터 유형과 호환됩니다.

변수 생성 시 Multi-value 활성화
(선택) Include All option 활성화
literal_or 필터 유형으로 변수 사용

host 변수가 다중 값일 때:

Filter Key: host, Filter Type: literal_or, Filter Value: $host
사용자가 webserver01, webserver02, webserver03을 선택하면 필터 값은 webserver01|webserver02|webserver03

All 값 동작

"All" 선택 시 Grafana는 모든 값을 파이프 구분으로 보내요. 값이 많으면 와일드카드 필터를 대신 고려하세요: Filter Key host, Filter Type wildcard, Filter Value *.

간격·자동 간격 변수

Grafana는 OpenTSDB 다운샘플링에 유용한 내장 간격 변수를 제공해요.

변수	설명
`$__interval`	시간 범위와 패널 너비 기반으로 자동 계산된 간격
`$__interval_ms`	`$__interval`과 같지만 밀리초 단위

다운샘플 간격 필드(예: Downsample Interval $__interval)에서 자동 간격 조정에 사용하세요.

다음 단계

쿼리 빌드에 템플릿 변수 사용
템플릿 쿼리로 알림 설정
변수가 채워지지 않으면 문제 해결

OpenTSDB 템플릿 변수