InfluxDB 쿼리 편집기

InfluxDB 쿼리 편집기 (Query editor)

InfluxDB 쿼리 편집기는 InfluxDB 데이터 소스에 대한 쿼리를 만들고 실행하는 데 도움을 줘요. Explore 페이지에서 접근하거나, 대시보드 패널 오른쪽 위의 줄임표를 클릭하고 Edit을 선택해 접근할 수 있어요. 편집기는 SQL, InfluxQL, Flux의 세 가지 쿼리 언어를 지원해요.

출처: InfluxDB query editor

본문

각 언어는 고유한 편집 경험과 매크로 시스템을 가져요. SQL과 InfluxQL은 시각적 빌더 모드와 코드 편집 모드를 모두 제공하고, Flux는 코드 편집기만 제공해요. 쿼리 편집기로 로그 데이터를 검색할 수도 있어요. Grafana 쿼리 편집기 일반 정보는 Query and transform data를 참고하세요.

시작하기 전에

• InfluxDB 데이터 소스를 구성했는지 확인해요.
• 자격 증명이 대상 데이터베이스나 버킷을 질의할 적절한 권한을 갖고 있는지 확인해요.

핵심 개념

InfluxDB가 처음이라면 쿼리 편집기 전체에서 사용되는 다음 용어를 알아두세요.

용어	설명
Measurement	필드, 태그, 타임스탬프의 논리적 그룹화. 관계형 데이터베이스의 테이블과 유사
Field	실제 데이터 값(숫자, 문자열, 불리언 값)을 저장하는 measurement의 열
Tag	메타데이터와 인덱싱에 사용되는 열. 태그는 인덱싱되며 필터링에 최적화됨
Retention policy	자동 삭제 전 데이터가 저장되는 기간을 제어하는 InfluxDB 1.x 설정
Bucket	데이터베이스와 보존 정책을 결합한 InfluxDB 2.x 및 3.x 저장 위치

쿼리 편집기 선택

InfluxDB 데이터 소스에는 데이터 소스 구성에서 선택한 쿼리 언어에 해당하는 세 가지 쿼리 편집기가 있어요.

• InfluxQL
• SQL
• Flux

편집기 옵션은 쿼리 언어에 따라 달라져요.

InfluxQL 쿼리 편집기

InfluxQL 쿼리 편집기는 지표와 태그를 선택해 InfluxQL 쿼리를 만드는 데 도움을 줘요. visual editor mode와 raw query mode 두 가지 모드가 있어요. 두 모드를 전환하려면 오른쪽 위의 연필 아이콘을 클릭해요.

시각적 쿼리 편집기 모드는 다음 구성 요소를 포함해요.

• FROM - 질의할 measurement를 선택해요.
• WHERE - + 기호를 클릭해 필터를 선택해요. 정규식을 입력하거나 정규식 태그 값에 텍스트 입력을 사용할 수 있어요.
• SELECT - 드롭다운에서 필드와 함수를 선택해요. + 기호를 클릭해 필드와 함수를 여러 개 추가할 수 있어요.
• GROUP BY - 드롭다운 메뉴에서 태그를 선택해요.
• TIMEZONE - 선택 특정 시간대로 데이터를 그룹화해요.
• ORDER BY TIME - 데이터를 시간으로 오름차순 또는 내림차순 정렬해요.
• LIMIT - 선택 쿼리가 반환하는 행 수를 제한해요.
• SLIMIT - 선택 쿼리가 반환하는 시리즈 수를 제한해요. 자세한 내용은 SLIMIT clause 참고.
• FORMAT AS - 드롭다운 메뉴에서 time series, table, logs 중 형식 옵션을 선택해요.
• ALIAS - 별칭을 추가해요. 자세한 내용은 Alias patterns 참고.

Raw 쿼리 편집기 모드

Raw 쿼리 모드로 전환해 원시 InfluxQL 쿼리를 작성할 수 있어요. 쿼리 편집기 오른쪽 위의 연필을 클릭해 모드를 전환해요. 시각적 편집기 모드로 전환하면 raw 쿼리 모드에서 한 변경 사항은 손실돼요.

raw 쿼리 모드를 사용한다면 쿼리에 WHERE $timeFilter가 포함되어야 해요. 또한 group by time과 집계 함수를 제공해야 해요. 그렇지 않으면 InfluxDB가 수십만 개의 데이터 포인트를 반환해 브라우저가 멈출 수 있어요.

정규식으로 매칭

메트릭 이름이나 태그 필터 값에 정규식을 입력할 수 있어요. 이 예시처럼 정규식 패턴을 슬래시(/)로 감싸요: /measurement/. Grafana가 태그 필터 조건을 자동으로 InfluxDB 정규식 일치 연산자(=~)를 사용하도록 조정해요.

필드 및 집계 함수

SELECT 행에서 사용할 필드와 함수를 지정할 수 있어요. 시간으로 그룹화한다면 집계 함수를 사용해야 해요. derivative 같은 특정 함수도 집계 함수가 필요해요.

쿼리 편집기 입력은 InfluxDB SELECT 절을 생성해요. 예를 들어:

SELECT derivative(mean("value"), 10s) / 10 AS "REQ/s"
FROM ....

SELECT 문에서 *를 사용해 모든 필드를 선택할 수도 있어요.

SELECT * FROM <measurement_name>

GROUP BY 결과

태그로 결과를 그룹화하려면 GROUP BY 행에 태그를 지정해요.

1. GROUP BY 행에서 + 기호를 클릭해요.
2. 드롭다운에서 태그를 선택해요.

GROUP BY 옵션을 여러 개 사용할 수 있어요. GROUP BY 옵션을 제거하려면 옆의 X 아이콘을 클릭해요.

별칭 패턴

별칭 패턴	대체 내용
$m	Measurement 이름
$measurement	Measurement 이름
$1 - $9	Measurement 이름의 일부(measurement 이름을 점으로 구분한 경우)
$col	열 이름
$tag_exampletag	exampletag 태그의 값. 문법은 $tag_yourTagName이며 $tag_로 시작해야 해요. 태그를 ALIAS BY 필드의 별칭으로 사용하려면 쿼리에서 태그로 그룹화해야 해요.

[[tag_hostname]] 패턴 대체 문법도 사용할 수 있어요. 예를 들어 ALIAS BY 필드에 Host: [[tag_hostname]] 값을 입력하면 각 범례 값에 대해 hostname 태그 값으로 대체돼요. 예시 범례 값은 Host: server1이에요.

SQL 쿼리 편집기

Grafana는 InfluxDB 3.x 및 최신 클라우드 제품(Cloud Serverless, Cloud Dedicated, Clustered)을 위한 SQL 쿼리 언어를 지원해요. SQL은 새 배포에 대한 InfluxData의 권장 쿼리 언어예요.

SQL 쿼리 편집기는 두 가지 모드를 제공해요.

• Builder 모드 - 드롭다운 메뉴에서 테이블, 열, 필터, 집계를 선택해 SQL 쿼리를 구성하는 데 도움을 주는 시각적 쿼리 빌더. SQL을 직접 작성하지 않고 쿼리를 만들 때 유용해요.
• Code 모드 - 자동 완성과 문법 강조로 원시 SQL 쿼리를 작성하는 텍스트 편집기. 쿼리 편집기 상단의 토글로 모드를 전환해요.

SQL 쿼리는 대규모 결과 집합에 고성능 데이터 전송을 제공하는 FlightSQL(gRPC) 프로토콜로 InfluxDB에 연결해요.

출력 형식

SQL 쿼리 편집기는 두 가지 출력 형식을 지원해요.

• Time series (기본값) - 데이터를 시계열 프레임으로 반환. 쿼리는 타임스탬프 열을 포함해야 해요.
• Table - 데이터를 표 프레임으로 반환. 비시계열 쿼리나 원시 결과를 표시할 때 유용.

쿼리 편집기의 Format 드롭다운에서 형식을 선택해요.

매크로

쿼리에서 매크로를 사용해 Grafana 컨텍스트의 값으로 자동 대체할 수 있어요.

매크로 예시	대체 내용
$__timeFrom	현재 활성 시간 선택의 시작. 예: cast('2020-06-11T13:31:00Z' as timestamp)
$__timeTo	현재 활성 시간 선택의 끝. 예: cast('2020-06-11T14:31:00Z' as timestamp)
$__timeFilter(<column>)	지정된 열에 적용되는 시간 범위 필터. <column> >= $__timeFrom AND <column> <= $__timeTo로 확장
$__interval	활성 시간 선택의 시간 범위를 기반으로 Grafana 계산 간격에 해당하는 간격 문자열. 예: interval '5 second'
$__dateBin(<column>)	$__interval을 사용해 date_bin 함수 적용. 열은 타임스탬프여야 함
$__dateBinAlias(<column>)	_binned 접미사 별칭으로 date_bin 함수 적용. 열은 타임스탬프여야 함
$__timeGroup(<column>)	$__interval로 date_bin()을 사용해 시간 간격으로 결과 그룹화. 열은 타임스탬프여야 함
$__timeGroupAlias(<column>)	$__interval로 date_bin()을 사용해 시간 간격으로 그룹화하고 _binned 접미사 별칭 추가. 열은 타임스탬프여야 함

SQL 쿼리 예시

기본 시계열 쿼리:

SELECT time, usage_system, usage_user
FROM cpu
WHERE $__timeFilter(time)
ORDER BY time

date_bin이 있는 집계 시계열 쿼리:

SELECT
  $__dateBin(time) AS time,
  mean(usage_system) AS avg_system,
  mean(usage_user) AS avg_user
FROM cpu
WHERE $__timeFilter(time)
GROUP BY $__dateBin(time)
ORDER BY time

테이블 간 JOIN 사용:

SQL은 InfluxQL이나 Flux에서는 사용할 수 없는 JOIN을 지원해요.

SELECT
  c.time,
  c.usage_system,
  m.used_percent AS mem_used
FROM cpu c
INNER JOIN mem m ON c.time = m.time AND c.host = m.host
WHERE $__timeFilter(c.time)
ORDER BY c.time

WHERE 절로 필터링:

SELECT $__dateBin(time) AS time, mean(usage_system) AS avg_system
FROM cpu
WHERE $__timeFilter(time)
  AND host = 'server01'
  AND cpu = 'cpu-total'
GROUP BY $__dateBin(time)
ORDER BY time

지원되는 SQL 문, 연산자, 함수의 전체 목록은 InfluxData의 SQL reference documentation을 참고하세요.

Flux 쿼리 편집기

Grafana는 InfluxDB v1.8 이상에서 Flux를 지원해요. 데이터 소스가 Flux용으로 구성되어 있다면 쿼리 편집기에서 Flux를 사용할 수 있어요. 이는 매크로 지원이 있는 원시 Flux 쿼리용 텍스트 편집기 역할을 해요.

자세한 내용과 연결 세부 정보는 InfluxDB 1.8 API compatibility를 참고하세요.

매크로 사용

쿼리에 매크로를 입력해 Grafana 컨텍스트의 값으로 대체할 수 있어요. 매크로는 InfluxData Chronograf에서 복사·붙여넣기를 지원해요.

매크로 예시	대체 내용
v.timeRangeStart	현재 활성 시간 선택의 시작. 예: 2020-06-11T13:31:00Z
v.timeRangeStop	현재 활성 시간 선택의 끝. 예: 2020-06-11T14:31:00Z
v.windowPeriod	활성 시간 선택의 시간 범위를 기반으로 Grafana 계산 간격에 해당하는 Flux 호환 간격 문자열. 예: 5s
v.defaultBucket	데이터 소스 구성의 Default Bucket 값
v.organization	데이터 소스 구성의 Organization 설정

예를 들어 다음 Flux 쿼리를 고려해요.

from(bucket: v.defaultBucket)
  |> range(start: v.timeRangeStart, stop: v.timeRangeStop)
  |> filter(fn: (r) => r["_measurement"] == "cpu" or r["_measurement"] == "swap")
  |> filter(fn: (r) => r["_field"] == "usage_system" or r["_field"] == "free")
  |> aggregateWindow(every: v.windowPeriod, fn: mean)
  |> yield(name: "mean")

Grafana는 활성 시간 선택에 따라 간격과 시간 기간 값이 바뀌면서 이 Flux 쿼리를 다음으로 보간해 InfluxDB로 보내요.

from(bucket: "grafana")
  |> range(start: 2020-06-11T13:59:07Z, stop: 2020-06-11T14:59:07Z)
  |> filter(fn: (r) => r["_measurement"] == "cpu" or r["_measurement"] == "swap")
  |> filter(fn: (r) => r["_field"] == "usage_system" or r["_field"] == "free")
  |> aggregateWindow(every: 2s, fn: mean)
  |> yield(name: "mean")

Query inspector로 쿼리의 보간된 버전을 보려면 Panel Inspector를 참고하세요.

로그 쿼리

Explore와 대시보드 Logs 패널에서 InfluxDB의 로그 데이터를 질의·표시할 수 있어요.

InfluxQL: 쿼리 편집기에서 InfluxDB 데이터 소스를 선택해요. FROM 섹션 옆의 Select measurement field 아래에서 로그 데이터를 담은 measurement를 선택한 다음 로그 메시지를 표시할 적절한 필드를 선택해요. WHERE 필드 옆의 + 기호를 클릭해 추가 필터를 추가해요. FORMAT AS를 Logs로 설정해요.

SQL: 타임스탬프 열과 로그 메시지를 담은 텍스트 열을 반환하는 SQL 쿼리를 작성해요. Format을 Table로 설정해요. 예를 들어:

SELECT time, message, level, host
FROM syslog
WHERE $__timeFilter(time)
ORDER BY time DESC

Flux: _value 필드에 로그 메시지를 담은 Flux 쿼리를 사용해요.

InfluxDB가 결과를 반환한 후 로그 패널은 막대 차트와 함께 로그 행을 표시해요. x축은 시간, y축은 빈도 또는 개수를 나타내요.

다음 단계

• 동적 대시보드를 위한 템플릿 변수 사용
• 그래프에 이벤트를 겹치는 어노테이션 설정
• InfluxDB 쿼리를 기반으로 한 알림 규칙 만들기

더 알아보기 (Learn more)

• Configure the InfluxDB data source - 데이터 소스 구성
• InfluxDB template variables - 템플릿 변수
• InfluxDB SQL reference - SQL 레퍼런스
• InfluxDB annotations - 어노테이션
• InfluxDB query editor - 원문 문서