InfluxDB 템플릿 변수

InfluxDB 템플릿 변수 (Template variables)

지표 쿼리에 서버, 애플리케이션, 센서 이름 같은 세부 정보를 하드코딩하는 대신 변수를 사용할 수 있어요. Grafana는 이 변수를 대시보드 상단의 드롭다운 선택 상자에 표시해 대시보드에 표시되는 데이터를 바꿀 수 있게 해줘요. Grafana는 이러한 변수를 템플릿 변수라고 부러요.

출처: InfluxDB template variables

본문

변수 일반 정보는 Variables와 Add and manage variables를 참고하세요.

시작하기 전에

지원되는 변수 유형

변수 유형 지원
Query 예
Custom 예
Data source 예
Ad-hoc filter 예 (InfluxQL 전용)

대시보드를 InfluxDB 인스턴스 간에 전환하려면 데이터 소스 변수를 사용해요. 변형으로 데이터 소스 이름을 반환하는 쿼리 변수를 사용하지 마세요. 쿼리 기반 변형은 내부 식별자에 의존하므로 Grafana 업그레이드 후 깨질 수 있어요. 자세한 내용은 Add a data source variable 참고.

변수를 사용할 수 있는 곳

변수 지원은 쿼리 편집기와 모드에 따라 달라져요.

편집기 변수 지원
InfluxQL 시각적 편집기 드롭다운에 데이터베이스의 값과 함께 템플릿 변수가 포함됨
InfluxQL raw 모드 전체 지원
SQL builder 모드 드롭다운은 데이터베이스의 테이블과 열만 나열. 변수를 사용하려면 code 모드로 전환
SQL code 모드 전체 지원. Ctrl+Space를 눌러 변수 제안 표시
Flux 코드 편집기 전체 지원

쿼리 변수 만들기

쿼리 템플릿 변수를 추가하면 InfluxDB 메타데이터 탐색 쿼리를 작성할 수 있어요. 이 쿼리는 measurement 이름, 키 이름, 키 값 같은 결과를 반환해요. 자세한 내용은 Add a query variable을 참고하세요.

InfluxQL 쿼리 변수 예시

hostname 태그의 모든 값을 담은 변수를 만들려면 Query 필드에 다음 쿼리를 사용해요.

SHOW TAG VALUES WITH KEY = "hostname"

주어진 measurement의 키 이름을 가져올 수 있어요.

SHOW TAG KEYS [FROM <measurement_name>]

사용 가능한 measurement를 나열할 수 있어요.

SHOW MEASUREMENTS

Flux 쿼리 변수 예시

Flux 구성 데이터 소스에서는 단일 값 열을 반환하는 Flux 쿼리를 작성해요.

import "influxdata/influxdb/schema"
schema.tagValues(bucket: v.defaultBucket, tag: "hostname")

SQL 쿼리 변수 예시

SQL 구성 데이터 소스(InfluxDB 3.x)에서는 단일 값 열을 반환하는 SQL 쿼리를 작성해요.

SELECT DISTINCT hostname FROM cpu

사용 가능한 테이블을 나열할 수 있어요.

SHOW TABLES

특정 테이블의 열을 나열할 수 있어요.

SHOW COLUMNS FROM cpu

변수를 대시보드 시간 범위로 한정

기본적으로 SHOW TAG VALUES 같은 메타데이터 쿼리는 대시보드 시간 범위가 아닌 전체 보존 기간의 값을 반환해요. 호스트나 센서가 오래전에 보고를 멈췄어도 값이 보존 기간 내에 존재하는 한 변수 드롭다운에 계속 나타나요.

변수 결과를 대시보드 시간 범위로 제한하려면:

  1. 변수 쿼리에 시간 조건을 포함해요. 변수 쿼리는 일반 쿼리와 동일한 시간 매크로를 보간해요: InfluxQL은 $timeFilter, SQL은 $__timeFilter(<column>), Flux는 v.timeRangeStart와 v.timeRangeStop.
  2. 변수의 Refresh 옵션을 On time range change로 설정해 대시보드 시간 범위가 바뀌면 값이 업데이트되게 해요.

InfluxQL 예시:

SHOW TAG VALUES WITH KEY = "hostname" WHERE $timeFilter

SQL 예시:

SELECT DISTINCT hostname FROM cpu WHERE $__timeFilter(time)

변수 체인 또는 중첩

중첩 변수(chained variables라고도 함)를 만들 수 있어요. 예를 들어 region 변수가 있다면 hosts 변수를 선택한 region의 호스트만 표시하도록 구성할 수 있어요.

InfluxQL:

SHOW TAG VALUES WITH KEY = "hostname"  WHERE region = '$region'

SQL:

SELECT DISTINCT hostname FROM cpu WHERE region = '$region'

키 이름을 담은 변수가 있다면 GROUP BY 절에서 사용할 수 있어요. 이렇게 하면 대시보드 상단의 변수 목록에서 선택해 그룹화를 조정할 수 있어요.

필터 사용

InfluxDB는 InfluxQL에 대한 필터 사용을 지원해요. 여러 키/값 필터를 정의할 수 있고, Grafana가 모든 InfluxDB 쿼리에 자동으로 적용해요. 필터는 표현식도 지원해요.

필터를 추가하려면:

  1. 업데이트할 대시보드로 이동해 Edit을 클릭해요.
  2. Add new element 아이콘(파란색 더하기)을 클릭해요.
  3. Filter and Group by를 클릭해요.
  4. 필터의 Name을 입력해요.
  5. Display 드롭다운에서 필터를 표시할 대시보드 위치 옵션을 선택해요.
  6. Data source 드롭다운에서 InfluxDB 데이터 소스를 선택해요.

자세한 내용은 Filter and Group by documentation을 참고하세요.

변수 문법 선택

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

  • $<varname> - 독립 변수 참조에 사용. 단어나 표현식 중간에서 변수를 사용할 수 없어요.
  • ${varname} - 표현식 중간에서 변수를 보간하려면 사용.

InfluxQL 예시:

SELECT mean("value") FROM "logins" WHERE "hostname" =~ /^$host$/ AND $timeFilter GROUP BY time($__interval), "hostname"

SELECT mean("value") FROM "logins" WHERE "hostname" =~ /^${host}$/ AND $timeFilter GROUP BY time($__interval), "hostname"

InfluxQL에서 Multi-value 또는 Include all value 옵션을 활성화하면 Grafana가 라벨을 일반 텍스트에서 정규식 호환 문자열로 변환하므로, = 대신 =~를 사용하고 변수를 /^$host$/ 같은 정규식으로 감싸야 해요.

예를 들어 $host가 multi-value 변수이고 server1과 server2를 선택하면 Grafana가 값을 |로 연결하고 괄호로 감싼 다음 특수 문자를 이스케이프해요. 보간된 쿼리는 다음과 같아요.

SELECT mean("value") FROM "logins" WHERE "hostname" =~ /^(server1|server2)$/ AND $timeFilter GROUP BY time($__interval), "hostname"

SQL 예시:

SELECT $__dateBin(time), mean(usage_system) FROM cpu WHERE $__timeFilter(time) AND host = '$host' GROUP BY $__dateBin(time)

SELECT $__dateBin(time), mean(usage_system) FROM cpu WHERE $__timeFilter(time) AND host IN ($host) GROUP BY $__dateBin(time)

SQL에서 Multi-value 옵션을 활성화하면 여러 값을 일치시키려면 = 대신 IN 연산자를 사용해요.

원하지 않는 값 이스케이프 방지

변수를 정규식 안에서 사용하거나 변수가 multi-value일 때 Grafana는 쿼리가 유효하게 유지되도록 값의 특수 문자를 이스케이프해요. 리터럴·수정되지 않은 값이 필요하다면 raw 형식 옵션을 사용해요.

SELECT mean("value") FROM "requests" WHERE "path" = '${path:raw}' AND $timeFilter GROUP BY time($__interval)

이것은 값이 Grafana가 이스케이프할 문자를 의도적으로 담고 있는 커스텀 변수에 유용해요. 사용 가능한 모든 형식 옵션은 Advanced variable format options을 참고하세요.

템플릿 대시보드 예시

템플릿 대시보드의 예시를 보려면 InfluxDB 예시 대시보드를 참고하세요.

더 알아보기 (Learn more)