MySQL 템플릿 변수

MySQL 템플릿 변수 (MySQL template variables)

메트릭 쿼리에서 서버·애플리케이션·센서 이름을 하드코딩하지 않고 변수를 사용할 수 있어요. Grafana는 변수를 대시보드 상단의 드롭다운 선택 박스에 표시해 데이터를 쉽게 바꾸게 해 주는데, 이를 템플릿 변수라고 해요. MySQL 데이터 소스에서는 SQL 쿼리로 변수 옵션을 채우는 쿼리 변수를 만들 수 있어요.

출처: 문서

본문

템플릿과 템플릿 변수 소개는 Templating과 변수 추가·관리 문서를 참고하세요.

쿼리 변수

쿼리 변수는 쿼리를 사용해 데이터 소스에서 값을 동적으로 가져와요. 드롭다운 선택 박스에 표시될 measurement 이름·키 이름·키 값 등을 반환하는 SQL 쿼리를 작성할 수 있습니다. 변수 쿼리 편집기는 메인 쿼리 편집기와 동일한 Builder와 Code 모드를 지원해요. Builder 모드는 데이터셋·테이블·컬럼·필터를 시각적으로 선택하고, Code 모드는 SQL을 직접 작성합니다.

hostname 컬럼의 모든 값을 반환하는 예:

SELECT hostname FROM my_host

쿼리는 여러 컬럼을 반환할 수 있고, Grafana가 그 값들을 자동으로 목록으로 생성해요.

SELECT my_host.hostname, my_other_host.hostname2 FROM my_host JOIN my_other_host ON my_host.city = my_other_host.city

$__timeFilter(column) 같은 시간 범위 의존 매크로를 사용하려면 템플릿 변수의 refresh 모드를 On Time Range Change로 설정해야 해요.

SELECT event_name FROM event_log WHERE $__timeFilter(time_column)

키/값 변수

드롭다운에 사용자 친화적 라벨(예: hostname)을 표시하고 패널 쿼리에는 다른 값(예: ID)을 쓰려면 키/값 변수를 만들 수 있어요. 변수 편집기 쿼리 섹션 하단의 Value field와 Text field에 값·라벨을 제공할 쿼리 컬럼을 지정하세요. 쿼리는 아무 컬럼 이름이나 사용할 수 있고 SQL에 __value/__text가 필요 없어요.

예: hostname과 id를 반환하는 쿼리를 실행하고 Text field를 hostname, Value field를 id로 설정.

SELECT hostname, id FROM my_host

텍스트 컬럼의 값은 고유해야 해요. 중복이 있으면 Grafana는 첫 번째 매칭 항목만 사용합니다. 레거시 방식으로는 쿼리에서 __text와 __value 컬럼을 반환해도 돼요 (SELECT hostname AS __text, id AS __value FROM my_host).

중첩 변수

한 변수가 다른 변수의 값에 의존하는 중첩 변수를 만들 수 있어요. region 변수에 따라 hosts 변수가 선택한 지역의 호스트만 보여주게 하려면, region이 다중 값 변수이면 = 대신 IN 연산자를 사용하세요.

SELECT hostname FROM my_host WHERE region IN($region)

__searchFilter로 결과 필터링

쿼리 필드에 __searchFilter를 사용하면 드롭다운의 사용자 입력에 따라 결과가 필터링돼요. 아무것도 입력하지 않으면 기본값은 %입니다. __searchFilter 표현식은 Grafana가 자동으로 따옴표를 붙이지 않으므로 직접 따옴표로 감싸야 해요.

SELECT hostname FROM my_host WHERE hostname LIKE '$__searchFilter'

쿼리에서 변수 사용하기

Grafana는 템플릿 변수가 multi-value일 때만 자동으로 값에 따옴표를 붙여요. 다중 값 변수 사용 시 = 대신 IN 비교 연산자를 쓰세요.

Grafana는 두 가지 문법을 지원합니다.

$<varname> 문법

SELECT
  UNIX_TIMESTAMP(atimestamp) as time,
  aint as value,
  avarchar as metric
FROM my_table
WHERE $__timeFilter(atimestamp) and hostname in($hostname)
ORDER BY atimestamp ASC

[[varname]] 문법

SELECT
  UNIX_TIMESTAMP(atimestamp) as time,
  aint as value,
  avarchar as metric
FROM my_table
WHERE $__timeFilter(atimestamp) and hostname in([[hostname]])
ORDER BY atimestamp ASC

다중 값 변수의 따옴표 비활성화

기본적으로 Grafana는 다중 값 변수를 따옴표가 붙은 콤마 구분 문자열로 포맷해요 ('server01', 'server02'처럼). 따옴표를 끄려면 변수에 csv 포맷 옵션을 사용하세요.

${servers:csv}

이러면 따옴표 없는 콤마 구분 목록으로 출력됩니다.

문자열 변수에 명시적 따옴표 사용

SQL 쿼리에서 문자열 변수의 암시적 따옴표 동작에 의존하지 마세요. 패널 유형·컨텍스트에 따라 따옴표 동작이 달라질 수 있어요.

Repeat panels는 단일 값 변수에 따옴표를 전혀 붙이지 않아 SQL에 원시 값이 나타나 쿼리가 깨질 수 있어요.
변수를 수동으로 따옴표로 감싸면(WHERE name = '$myvar') Grafana가 자체 따옴표도 적용해 이중 따옴표(''30'')가 될 수 있어요. (Grafana 11.3에서 의도된 따옴표 동작 복원됨)

두 문제를 피하려면 sqlstring 포맷 옵션을 사용하세요. 이스케이프와 따옴표를 한 번에 처리하므로 변수 주위에 따옴표를 직접 추가하지 않아요.

SELECT *
FROM my_table
WHERE hostname = ${hostname:sqlstring}

패널 유형·컨텍스트와 무관하게 안전하게 따옴표 처리된 문자열('server01')을 만들어요. 다중 값 변수에는 IN과 ${var:sqlstring}을 함께 쓰세요.

SELECT *
FROM my_table
WHERE hostname IN (${hostname:sqlstring})

주의: ${var:sqlstring}을 추가로 따옴표로 감싸지 마세요. 이미 따옴표 처리된 값을 생성하므로 '${var:sqlstring}'는 이중 따옴표가 됩니다.

추가 정보는 고급 변수 포맷 옵션을 참고하세요.

MySQL 템플릿 변수