콘텐츠로 이동

DQL 함수 참조


DQL은 데이터 집계, 변환 및 일치를 위한 다양한 함수를 제공합니다. 이 문서에서는 각 함수의 의미, 매개변수 및 사용 방법을 자세히 설명합니다.

집계 함수

집계 함수는 여러 행의 데이터를 단일 값으로 집계하는 데 사용되며, 일반적으로 시간 윈도우(time-expr) 및 그룹화(BY 절)와 함께 사용합니다.

기본 집계

sum

필드 값의 합계를 계산합니다.

구문:

sum(field)

매개변수:

  • field: 숫자 필드

예시:

// 각 호스트 NIC의 수신 총 바이트 수 계산
M::net:(sum(bytes_recv) AS total_recv_bytes) [1h] BY host

// 각 APM 서비스의 총 소요 시간 계산
T::*:(sum(duration) AS total_duration_ns) [1h] BY service

avg

필드 값의 평균값을 계산합니다.

구문:

avg(field)

매개변수:

  • field: 숫자 필드

예시:

// 각 호스트의 평균 CPU 총 사용률 계산
M::cpu:(avg(usage_total) AS avg_cpu) [1h] BY host

// 각 APM 서비스의 평균 응답 소요 시간 계산
T::*:(avg(duration) AS avg_duration_ns) [1h] BY service

count

데이터 행 수 또는 비어 있지 않은 필드 값 수를 계산합니다.

구문:

count(field)
count(distinct(field))
count(*)

매개변수:

  • field: 임의의 필드, 비어 있지 않은 값의 수를 계산합니다.
  • distinct(field): 필드의 정확한 중복 제거 값 수를 계산합니다.
  • *: 모든 행 수를 계산합니다(로그 L, 트레이스 T, 객체 O, RUM R, 이벤트 E 등 비메트릭 네임스페이스에만 적용 가능. M 메트릭 네임스페이스는 구체적인 메트릭 필드 이름을 지정해야 합니다).

예시:

// 최근 1시간 로그 총 건수 계산
L::*:(count(*) AS log_count) [1h]

// 서비스별 APM 호출 스팬 수 집계
T::*:(count(duration) AS span_count) [1h] BY service

// 페이지를 방문한 서로 다른 사용자 ID 수를 정확히 집계
R::view:(count(distinct(userid)) AS exact_uv) [1h] BY app_id

min / max

필드의 최솟값 또는 최댓값을 계산합니다.

구문:

min(field)
max(field)

매개변수:

  • field: 숫자 필드

예시:

// 각 서비스의 최대 응답 소요 시간 찾기
T::*:(max(duration) AS max_duration_ns) [1h] BY service

// 각 호스트 CPU 사용률의 최솟값과 최댓값 찾기
M::cpu:(min(usage_total) AS min_cpu, max(usage_total) AS max_cpu) [1h] BY host

first / last

시간 순서에 따라 첫 번째 또는 마지막 값을 가져옵니다.

구문:

first(field)
last(field)
last_row(field)

매개변수:

  • field: 임의의 필드

설명:

  • first: 시간 윈도우 내에서 시간상 가장 이른 값을 반환합니다.
  • last: 시간 윈도우 내에서 시간상 가장 늦은 값을 반환하며, 필드가 배열 유형이면 펼칩니다.
  • last_row: 시간 윈도우 내에서 시간상 가장 늦은 값을 반환하며, 배열 유형은 펼치지 않습니다.

예시:

// 각 호스트의 최신 시스템 1분 부하 값 가져오기
M::system:(last(load1) AS latest_load1) [1h] BY host

// 각 호스트의 윈도우 시작과 종료 시점 메모리 사용률 가져오기
M::mem:(first(used_percent) AS start_mem, last(used_percent) AS end_mem) [1h] BY host

any

비어 있지 않은 임의의 값을 반환합니다. 그룹 집계 시 샘플 데이터(예: 샘플 오류 메시지 하나)를 가져오거나 특정 시간 순서가 필요 없는 시나리오에 적합합니다.

구문:

any(field)

매개변수:

  • field: 임의의 필드

예시:

// 서비스별로 오류 로그 수를 집계하고 로그 샘플 하나를 함께 표시
L::*:(count(*) AS err_cnt, any(message) AS sample_message) {status = 'error'} [1h] BY service

// 오류 유형별로 프런트엔드 오류를 집계하고 샘플 오류 상세 하나 가져오기
R::error:(count(*) AS cnt, any(error_message) AS sample_error) [1h] BY error_type

SHIFT

표현식 수준 SHIFT는 프로젝션에서 과거 윈도우의 집계 값을 참조하여 현재 집계 결과와 정렬해 표시합니다:

<aggregate-or-subquery-measure> SHIFT <duration>

현재 값, 과거 값 및 파생 계산은 모두 프로젝션 표현식에서 명시적으로 제공됩니다. 동일한 과거 값을 여러 번 참조할 때는 동일한 SHIFT 표현식을 반복해서 작성하면 됩니다:

L::*:(
  service,
  count(*) AS requests,
  count(*) SHIFT 7d AS requests_last_week,
  CASE
    WHEN (count(*) SHIFT 7d) = nil OR (count(*) SHIFT 7d) = 0 THEN nil
    ELSE count(*) / (count(*) SHIFT 7d)
  END AS requests_ratio
) [1d:1h] BY service

duration은 1h, 7d와 같이 양의 고정 기간이어야 합니다.

사용 제한:

  • 프로젝션에만 나타날 수 있으며, 현재 프로젝션에서 행 ID가 윈도우 간 안정적인 집계 표현식 또는 이러한 집계 출처를 가진 하위 쿼리 measure에만 적용할 수 있습니다.
  • 동일한 SELECT에서 방금 선언한 프로젝션 별칭, 차원 열, WHERE, BY, HAVING, ORDER BY, SORDER BY에는 적용할 수 없으며 SHIFT를 중첩할 수도 없습니다.
  • distinct, distinct_by_collapse, field_values, histogram 등 출력 행이 각 윈도우 데이터에 의해 결정되는 집계는 피연산자가 될 수 없습니다. uint(field) 등 원시 필드만 변환하는 표현식은 집계 measure가 아니며, abs(sum(field)) 등 안정적인 집계를 감싸는 스칼라 변환은 사용할 수 있습니다.
  • 과거 값을 기반으로 필터링하거나 정렬해야 할 때는 외부 SELECT에서 수행합니다.
  • 동일한 SELECT 내의 모든 표현식 수준 SHIFT는 합계에서 최대 16개의 서로 다른 offset을 포함할 수 있습니다.

쿼리 수준 SHIFT(DQL 메인 문서의 시간 이동 참고)와 표현식 수준 SHIFT는 조합할 수 있습니다. 쿼리 수준 offset이 먼저 전체 쿼리의 기준 윈도우를 결정하고, 표현식 수준 offset은 해당 기준 윈도우를 기준으로 더 이른 집계 값을 읽습니다.


spread

범위(최댓값과 최솟값의 차이)를 계산합니다.

구문:

spread(field)

매개변수:

  • field: 숫자 필드

예시:

// 각 호스트의 1시간 동안 CPU 사용률 변동 범위(최댓값 - 최솟값) 계산
M::cpu:(spread(usage_total) AS cpu_spread) [1h] BY host

// 각 APM 서비스 응답 소요 시간의 범위 계산
T::*:(spread(duration) AS duration_spread) [1h] BY service

stddev

표준편차를 계산하여 메트릭 또는 지연 시간의 분산 변동 정도를 측정합니다.

구문:

stddev(field)

매개변수:

  • field: 숫자 필드

예시:

// 각 호스트 CPU 사용률의 표준편차 계산
M::cpu:(stddev(usage_total) AS cpu_stddev) [1h] BY host

// 각 서비스 응답 소요 시간의 표준편차 계산
T::*:(stddev(duration) AS duration_stddev) [1h] BY service

mode

최빈값(가장 자주 나타나는 값)을 계산합니다.

구문:

mode(field)

매개변수:

  • field: 임의의 필드

예시:

// 각 서비스의 APM 호출에서 가장 자주 나타나는 HTTP 상태 코드 찾기
T::*:(mode(http_status_code) AS most_common_status) [1h] BY service

count_series

시계열(Series) 수를 계산하여 현재 쿼리 범위 내에 독립적인 시계열이 몇 개 있는지 반환합니다.

구문:

count_series(field)

매개변수:

  • field: 구체적인 메트릭 필드 이름(참고: M 메트릭 네임스페이스는 * 와일드카드를 지원하지 않으므로 usage_total, used_percent 등 실제 필드 이름을 지정해야 합니다)

예시:

// 현재 보고되는 CPU usage_total 메트릭의 시계열 총수 통계
M::cpu:(count_series(usage_total) AS total_series) [1h]

// 호스트별 디스크 메트릭의 시계열 수 통계(예: 각 호스트에 마운트된 디스크 파티션 수)
M::disk:(count_series(used_percent) AS disk_series_cnt) [1h] BY host

통계 집계(추정 함수)

다음 함수는 확률적 데이터 구조를 사용해 추정하며, 대용량 데이터 시나리오에 적합하고 정확도와 성능 사이의 균형을 제공합니다.

count_distinct

필드의 서로 다른 값 수(추정값)를 계산합니다.

구문:

count_distinct(field)

매개변수:

  • field: 임의의 필드

알고리즘 설명:

HyperLogLog 알고리즘으로 카디널리티를 추정합니다: - 레지스터 수: 2¹⁶ = 65536 - LogLog-Beta 추정 방법 사용 - 표준 오차: 약 0.4%

사용 사례:

  • 순 사용자 수(UV) 집계
  • 로그를 보고하는 서로 다른 호스트 또는 Pod 수 계산
  • 고유 Trace ID 수 분석

중복 제거 카운트 방식 선택 안내: - count(distinct(field)): 정확한 중복 제거 카운트입니다. 필드 값에 대해 정확히 중복 제거 집계를 수행하며 결과에 오차가 없으므로, 수치 정확도가 엄격히 요구되는 청구 대사 및 리포트 통계에 적합합니다. - count_distinct(field): 근사 중복 제거 카운트입니다. HyperLogLog 카디널리티 추정 알고리즘을 기반으로 하며 메모리 사용량이 매우 낮고 쿼리 속도가 매우 빨라, 대량 로그, 순 사용자 수(UV) 등 작은 오차를 허용하는 대규모 카디널리티 분석 시나리오에 적합합니다.

예시:

// 지난 24시간 각 페이지의 순 방문자 수(UV) 집계
R::view:(count_distinct(userid) AS uv) [24h] BY view_path

// 지난 1시간 각 서비스에서 로그를 생성한 서로 다른 Pod 수 집계
L::*:(count_distinct(pod_name) AS pod_cnt) [1h] BY service

percentile

필드의 백분위수(추정값)를 계산합니다.

구문:

percentile(field, n)
pXX(field)  // 축약형(XX는 1~99의 정수)

매개변수:

  • field: 숫자 필드
  • n: 백분위수, 범위 0-100

축약형:

  • p50(field)는 percentile(field, 50)과 동일합니다.
  • p95(field)는 percentile(field, 95)와 동일합니다.
  • p99(field)는 percentile(field, 99)와 동일합니다.

알고리즘 설명:

로그-선형 보간 히스토그램으로 추정합니다: - 버킷 범위: 10⁻⁹ ~ 10¹⁸로 대부분의 수치 시나리오를 커버 - 각 자릿수 구간을 128개 버킷으로 분할 - 로그 공간의 선형 보간을 사용해 정확도 향상

사용 사례:

  • APM 응답 지연 시간 또는 RUM 페이지 로드 지연 시간의 P99, P95 계산
  • 성능 메트릭의 테일 레이턴시 분석
  • 서비스 수준 계약(SLA) 달성 현황 평가

예시:

// 각 APM 서비스 응답 소요 시간의 P99 계산
T::*:(percentile(duration, 99) AS p99_duration) [1h] BY service

// 축약형으로 P50, P95, P99 동시 계산
T::*:(p50(duration) AS p50_ns, p95(duration) AS p95_ns, p99(duration) AS p99_ns) [1h] BY service

// Rollup 함수 호출로 사용: 각 CPU 시계열에서 먼저 P95를 계산한 다음 host별로 평균
M::cpu:(avg(usage_total)) [1h::5m:percentile(95)] BY host

median

중앙값을 계산하며, percentile(field, 50)과 동일합니다.

구문:

median(field)

예시:

// 각 서비스 응답 소요 시간의 중앙값 계산
T::*:(median(duration) AS median_duration) [1h] BY service

히스토그램 함수

DQL은 데이터 소스와 시나리오에 따라 세 가지 히스토그램 관련 함수를 제공합니다:

함수 사용 사례 데이터 소스 유형 권장도
histogram_auto 로그, Trace 등 상세 데이터의 수치 분포 통계 상세 모델(로그/Trace) ⭐⭐⭐ 권장
histogram 고정 버킷 경계가 필요한 히스토그램 상세 모델(로그/Trace) ⭐⭐ Deprecated
histogram_quantile Prometheus 히스토그램 메트릭에서 분위수 계산 Prometheus 메트릭 ⭐⭐⭐ 권장

histogram_auto(권장)

분포 히스토그램을 자동 생성하며, 로그, Trace 등 상세 데이터의 수치 분포 통계를 위해 설계되었습니다.

특징:

  • 버킷 경계를 지정할 필요 없이 데이터 분포에 자동 적응
  • 로그-선형 보간 히스토그램 알고리즘을 사용하여 10⁻⁹ ~ 10¹⁸ 수치 범위 커버
  • 분위수 통계와 버킷 분포 정보를 동시에 반환

구문:

histogram_auto(field)

매개변수:

  • field: 숫자 필드

반환값: | 열 이름 | 설명 | | -------------- | ---------------- | | lower_bounds | 각 버킷의 하한 배열 | | upper_bounds | 각 버킷의 상한 배열 | | counts | 각 버킷의 카운트 배열 | | min | 최솟값 | | p50 | 중앙값 | | p75 | 75분위수 | | p90 | 90분위수 | | p95 | 95분위수 | | p99 | 99분위수 | | max | 최댓값 |

알고리즘 설명: 추정 히스토그램(로그-선형 보간)을 사용하며, 각 자릿수 구간을 128개 버킷으로 나누어 대용량 데이터의 분포 통계에 적합합니다.

사용 사례:

  • 로그의 응답 시간 분포 분석
  • Trace의 지연 시간 분포 통계
  • 버킷 경계를 미리 설정하지 않는 탐색적 데이터 분석

예시:

// APM 트레이스 호출의 지연 시간 분포 분석
T::*:(histogram_auto(duration)) [1h] BY service

// RUM 페이지 로드 지연 시간 분포 분석
R::view:(histogram_auto(loading_time)) [24h] BY view_path

결과 예시:

lower_bounds upper_bounds counts min p50 p75 p90 p95 p99 max
[0, 10, 100] [10, 100, 1000] [1000, 500, 100] 0.5 45 120 280 450 850 1200

참고: lower_bounds, upper_bounds, counts는 배열 유형이며 각 버킷의 경계와 카운트를 나타냅니다.


histogram(Deprecated)

지정한 버킷 경계로 히스토그램을 생성합니다. 이 함수는 Deprecated이며 histogram_auto 사용을 권장합니다.

설명: histogram은 버킷 경계 매개변수를 수동으로 지정해야 하므로 사용이 유연하지 않습니다. histogram_auto는 데이터 분포에 자동 적응하고 더 넓은 수치 범위를 커버하며 더 풍부한 통계 정보를 반환합니다.

구문:

histogram(field, left_bound, right_bound, bucket_size [, threshold])

매개변수:

  • field: 숫자 필드
  • left_bound: 왼쪽 경계
  • right_bound: 오른쪽 경계
  • bucket_size: 버킷 크기
  • threshold(선택 사항): 단일 버킷 최소 카운트로, 이 값보다 낮은 버킷은 반환하지 않습니다.

반환값: bucket_le(버킷의 오른쪽 경계)와 count(카운트) 두 열을 반환합니다.

예시:

// 0-1000 범위에서 100 단위 버킷으로 히스토그램 생성
R::view:(histogram(loading_time, 0, 1000, 100)) [1h]

// histogram_auto 사용을 권장
R::view:(histogram_auto(loading_time)) [1h]

결과 예시:

bucket_le count
100 1500
200 2800
300 3500
... ...
1000 5000

histogram_quantile

Prometheus 히스토그램 메트릭에서 분위수를 계산합니다.

특징:

  • Prometheus가 보고한 히스토그램 유형 메트릭 처리 전용
  • le 태그(또는 VictoriaMetrics의 vmrange 태그)를 기반으로 bucket 경계 식별
  • 입력 데이터는 누적 카운트(cumulative)여야 함

구문:

histogram_quantile(field, q)

매개변수:

  • field: 히스토그램 카운트 필드(예: http_request_duration_bucket)
  • q: 분위수, 범위 0-1(예: 0.99는 P99)

사용 사례 비교:

시나리오 권장 함수 설명
로그의 응답 시간 분포 분석 histogram_auto 로그는 상세 데이터이며 사전 집계된 히스토그램이 없음
Prometheus 히스토그램 메트릭의 P99 분석 histogram_quantile 메트릭이 이미 le 태그로 사전 집계됨
Trace 호출의 지연 시간 분포 통계 histogram_auto Trace는 상세 데이터

le 태그 처리 메커니즘:

histogram_quantile은 le 태그(less than or equal)를 기반으로 히스토그램 bucket의 경계를 식별합니다:

  1. Prometheus 형식(기본값): le 태그를 사용해 bucket 상한을 직접 표현합니다.
  2. le 값은 숫자(예: "0.1", "1", "10") 또는 "+Inf"(무한대)입니다.
  3. 데이터는 누적 카운트(cumulative)여야 합니다.

  4. VictoriaMetrics 형식: vmrange 태그로 범위를 표현합니다.

  5. 형식은 "하한...상한"(예: "0.1...0.2")입니다.
  6. 데이터는 범위 카운트(비누적)입니다.
  7. 함수는 범위 카운트를 자동으로 누적 카운트로 변환합니다.

계산 과정: 1. le 값 기준으로 모든 bucket 정렬 2. vmrange 형식이면 카운트를 누적해 누적 분포로 변환 3. bucket 카운트가 단조 증가하도록 보장(가능한 이상 데이터 수정) 4. 선형 보간으로 목표 분위수 계산

PromQL과의 차이:

특성 DQL PromQL
함수 유형 집계 함수 변환 함수
입력 데이터 le 태그가 있는 메트릭을 직접 읽음 sum(rate(...)) by (le)와 함께 사용해야 함
사용 방식 histogram_quantile(field, 0.99) histogram_quantile(0.99, sum(rate(...)) by (le))
데이터 형식 le 및 vmrange 두 태그 지원 le 태그만 지원
그룹화 방식 DQL의 BY 절 사용 by (le)로 명시적 그룹화

동등 예시:

le 태그(예: 0.1, 0.5, 1, 5, +Inf)와 service 태그를 포함하는 히스토그램 메트릭 http_request_duration_bucket이 있다고 가정합니다.

시나리오 1: P99 지연 시간 계산

DQL:

M::http_request_duration:(histogram_quantile(duration_bucket, 0.99)) [1h] BY service

PromQL 동등:

histogram_quantile(0.99, sum(rate(http_request_duration_bucket[1h])) by (le, service))

시나리오 2: 각 서비스의 P95 지연 시간 계산(다중 그룹)

DQL:

M::http_request_duration:(
    histogram_quantile(duration_bucket, 0.95)
) [1h] BY service, endpoint

PromQL 동등:

histogram_quantile(0.95, sum(rate(http_request_duration_bucket[1h])) by (le, service, endpoint))

시나리오 3: P50(중앙값) 및 P99 계산

DQL:

M::http_request_duration:(
    histogram_quantile(duration_bucket, 0.50) AS p50,
    histogram_quantile(duration_bucket, 0.99) AS p99
) [1h] BY service

PromQL 동등:

label_join(
  histogram_quantile(0.50, sum(rate(http_request_duration_bucket[1h])) by (le, service)), "quantile", "", "0.50"
)
or
label_join(
  histogram_quantile(0.99, sum(rate(http_request_duration_bucket[1h])) by (le, service)), "quantile", "", "0.99"
)

참고: PromQL은 서로 다른 분위수 결과를 구분하기 위해 label_join 또는 label_replace가 필요합니다.

참고 사항:

  • 입력 데이터에 le 또는 vmrange 태그가 없으면 계산할 수 없습니다.
  • +Inf bucket이 없으면 마지막 bucket의 상한이 최댓값으로 사용됩니다.
  • 카운트가 0 또는 NaN인 bucket은 건너뜁니다.
  • 분위수가 < 0이면 -Inf, > 1이면 +Inf를 반환합니다.

TopN 함수

top

그룹 내에서 가장 큰 값 N개를 가져옵니다.

구문:

top(field, n)

매개변수:

  • field: 숫자 필드
  • n: 반환할 값 수

예시:

// 각 서비스에서 응답 지연 시간이 가장 긴 5개 값 가져오기
T::*:(top(duration, 5)) [1h] BY service

// CPU 사용률이 가장 높은 10개 샘플 값 가져오기
M::cpu:(top(usage_total, 10)) [1h] BY host

결과 예시:

service top(duration, 5)
api 1250
api 1180
api 1050
api 980
api 920

참고: 여러 행을 반환하며, 각 행에는 TopN 값 하나가 포함됩니다. 그룹(Series) 간 정렬하여 상위 N개 그룹을 가져와야 하는 경우 SORDER BY ... DESC SLIMIT N(DQL 메인 문서의 그룹 간 정렬 참고)을 사용합니다.


bottom

그룹 내에서 가장 작은 값 N개를 가져옵니다.

구문:

bottom(field, n)

매개변수:

  • field: 숫자 필드
  • n: 반환할 값 수

예시:

// 각 서비스에서 응답 지연 시간이 가장 짧은 5개 값 가져오기
T::*:(bottom(duration, 5)) [1h] BY service

// 각 호스트에서 사용 가능한 메모리 백분율이 가장 낮은 5개 샘플 값 가져오기
M::mem:(bottom(available_percent, 5)) [1h] BY host

결과 예시:

service bottom(duration, 5)
api 12
api 18
api 25
api 32
api 45

참고: 여러 행을 반환하며, 각 행에는 BottomN 값 하나가 포함됩니다.


값 수집 함수

distinct

필드의 모든 서로 다른 값을 반환합니다(각 행에 서로 다른 값 하나).

구문:

distinct(field)

예시:

// 각 서비스의 로그에 나타난 모든 로그 상태 레벨 가져오기
L::*:(distinct(status)) [1h] BY service

결과 예시:

service distinct(status)
api info
api warn
api error
web info

참고: 여러 행을 반환하며, 각 행에는 서로 다른 값 하나가 포함됩니다.


distinct_by_collapse

접기 전략으로 필드의 서로 다른 값을 가져오고, 중복 제거 시 지정한 다른 필드의 마지막 값을 유지합니다.

구문:

distinct_by_collapse(field, [last_field1, last_field2, ...])

매개변수:

  • field: 중복 제거 기준 필드
  • last_fields(선택 사항): 마지막 값을 유지해야 하는 필드 목록

설명: distinct와 달리 distinct_by_collapse는 중복 제거 시 다른 관련 필드 정보를 유지하며(마지막 값 사용), 컨텍스트 정보를 보존해야 하는 시나리오에 적합합니다.

예시:

// 서로 다른 서비스 이름을 가져오고 각 서비스의 최신 오류 로그 내용과 호스트 이름 유지
L::*:(distinct_by_collapse(service, [host, message])) {status = 'error'} [1h]

// 서로 다른 호스트를 가져오고 마지막 운영 체제, 상태 및 CPU 사용률 유지
O::HOST:(distinct_by_collapse(host, [os, state, cpu_usage])) [1h]

결과 예시:

service last(host) last(message)
payment node-01 "connection reset by peer"
order node-02 "query timeout"

참고: 중복 제거된 기본 필드 값과 last_fields에 지정한 다른 필드의 마지막 값을 반환합니다.


collect

모든 값(중복 포함)을 수집하여 배열 유형으로 반환합니다.

구문:

collect(field [, limit])

매개변수:

  • field: 임의의 필드
  • limit(선택 사항): 최대 수집 수

예시:

// 서비스별로 최대 20개의 느린 요청 지연 시간 값 수집
T::*:(collect(duration, 20)) {duration > 1000000000} [1h] BY service

결과 예시:

service collect(duration, 20)
api [1200000000, 1350000000, 1100000000]
web [1500000000, 1800000000]

참고: 수집된 모든 값을 포함하는 배열 유형을 반환합니다(중복 값 포함 가능).


collect_distinct

모든 서로 다른 값을 수집하여 중복 제거된 배열을 반환합니다.

구문:

collect_distinct(field [, limit])

매개변수:

  • field: 임의의 필드
  • limit(선택 사항): 최대 수집 수

예시:

// 서비스별로 오류 로그를 생성한 모든 호스트 목록 수집
L::*:(collect_distinct(host)) {status = 'error'} [1h] BY service

결과 예시:

service collect_distinct(host)
api ["node-01", "node-02"]
web ["node-03"]

참고: 중복 제거된 모든 값을 포함하는 배열 유형을 반환합니다.


field_values

필드의 모든 서로 다른 값과 발생 횟수(hits)를 집계하여 중복 제거 값 열과 대응하는 hits 카운트 열을 반환합니다.

구문:

field_values(field)

매개변수:

  • field: 임의의 필드(스칼라 또는 배열 필드. 배열 필드는 자동으로 펼쳐 각 요소의 발생 횟수를 집계)

예시:

// 로그의 status 필드에 대한 모든 값과 각 값의 로그 건수 집계
L::*:(field_values(status)) [1h]

결과 예시:

field_values(status) hits
"info" 15420
"warn" 320
"error" 45

참고: 여러 행을 반환하며, 중복 제거된 필드 값 열 field_values(field)와 대응하는 발생 횟수 열 hits를 포함합니다.


필터 집계

count_filter

지정한 목록에 포함된 필드 값의 수를 집계합니다.

구문:

count_filter(field, [value1, value2, ...])

매개변수:

  • field: 임의의 필드
  • values: 값 목록

예시:

// 특정 HTTP 상태 코드의 APM 요청 수 집계
T::*:(count_filter(http_status_code, ["200", "201", "204"])) [1h] BY service

// 오류 및 심각 수준 로그 건수 집계
L::*:(count_filter(status, ["error", "critical"])) [1h] BY service

보조 함수

default

필드에 기본값을 설정하며, 집계 결과가 비어 있으면 기본값을 반환합니다.

구문:

default(field, default_value)

매개변수:

  • field: 임의의 필드
  • default_value: 기본값(숫자, 문자열, 부울 또는 null 가능)

예시:

// 널 값에 기본 소요 시간 0 설정
T::*:(default(duration, 0)) [1h] BY service

시계열 함수

시계열 함수는 시간에 따라 변하는 데이터, 특히 Counter 유형 메트릭을 처리하는 데 사용합니다.

Rollup 함수

Rollup 함수는 시간 윈도우에서 원시 시계열 데이터를 전처리하는 데 사용합니다. 자세한 설명은 이 문서의 Rollup 함수를 참고하십시오.

표기 설명:

  • Rollup은 시간 절에 작성합니다(예: [rate], [1h::5m:rate]).
  • 쿼리 외부에 작성하는 경우(예: rate(DQL)) 외부 함수에 해당하며 Rollup이 아닙니다.
  • Rollup 축약, Rollup 함수 호출 및 명시적 집계 호출의 실행 단계와 매개변수 차이는 DQL 메인 문서의 Rollup 함수를 참고하십시오.

시간 절은 Rollup 축약을 지원하며, Rollup 함수에 추가 알고리즘 매개변수를 전달할 수도 있습니다(예: [1h::1m:ewma(0.3)]). 시간 절의 매개변수는 알고리즘 매개변수만 의미하며, 입력 필드는 여전히 Select 필드로 결정됩니다. 여러 입력 필드가 필요한 함수는 Select 절에서 명시적 집계 호출을 사용해야 합니다.

Rollup 축약을 지원하는 함수:

함수 설명
rate 초당 증가율 계산
irate 순간 증가율 계산
increase 증가량 계산
deriv 도함수(변화율) 계산
difference 차이 계산
non_negative_derivative 비음수 도함수 계산
non_negative_difference 비음수 차이 계산
rate_over_sum 초당 평균값 계산
rate_over_count 초당 카운트 계산
sum 합계
avg 평균값
min 최솟값
max 최댓값
count 카운트
first 첫 번째 값
last 마지막 값
stddev 표준편차
mode 최빈값
spread 범위
any 임의의 값
slope 선형 추세 기울기
zscore 최신 포인트 Z-Score
mad_score 최신 포인트 MAD 이상 점수
change_score 시계열 급변 점수

Rollup 함수 호출을 지원하는 함수:

함수 설명
ewma(alpha) 지수 가중 이동 평균
moving_average(n) 이동 평균
percentile(p) 백분위수

예시:

// 각 호스트 NIC의 초당 수신 속도 계산(바이트/초)
M::net:(sum(bytes_recv)) [1h::5m:rate] BY host

// 축약형(Rollup 함수만 지정하고 시간 범위는 외부 요청에서 전달)
M::net:(sum(bytes_recv)) [rate] BY host

// 알고리즘 매개변수가 있는 Rollup 함수 호출
M::cpu:(avg(usage_total)) [1h::1m:ewma(0.3)] BY host

증가율 계산

rate

Counter 메트릭의 초당 평균 증가율을 계산합니다.

구문:

rate(field)

설명: rate는 Counter 메트릭의 시간 윈도우 내 초당 평균 증가율을 계산하며, 프로세스 재시작으로 인한 카운터 재설정을 자동 처리합니다. 단조 증가하는 Counter 유형 메트릭(예: net의 bytes_recv, bytes_sent, packets_recv)은 원시 값으로 직접 집계하는 것이 의미가 없으므로 먼저 증가율을 계산해야 합니다.

사용 사례:

  • 네트워크 트래픽 처리량 계산(바이트/초, 패킷/초)
  • 요청 QPS 계산
  • 누적 카운터 증가 추세 분석

예시:

// 각 호스트 NIC의 초당 수신 바이트 수 계산(Rollup과 함께 사용 권장)
M::net:(sum(bytes_recv) AS recv_bps) [1h::5m:rate] BY host

// Select 절에서 rate 직접 호출
M::net:(rate(bytes_recv) AS recv_bps) [1h::5m] BY host

irate

Counter 메트릭의 순간 증가율(초당)을 계산합니다.

구문:

irate(field)

설명: rate와 달리 irate는 윈도우 내 마지막 두 데이터 포인트만 사용해 증가율을 계산하므로 순간 변화율을 반영하며 단기 스파이크에 더 민감합니다.

예시:

// 각 호스트 NIC의 순간 수신 바이트 속도 계산
M::net:(sum(bytes_recv) AS instant_recv_bps) [1h::1m:irate] BY host

increase

Counter 메트릭의 시간 윈도우 내 총 증가량을 계산합니다.

구문:

increase(field)

설명: increase는 초당 속도가 아니라 시간 윈도우 내 누적 증분을 반환합니다.

예시:

// 각 호스트가 지난 1시간 동안 5분마다 새로 수신한 데이터 패킷 수 계산
M::net:(sum(packets_recv) AS new_packets) [1h::5m:increase] BY host

rate_over_sum

초당 평균값(sum(field) / 시간 윈도우 초 수)을 계산합니다.

구문:

rate_over_sum(field)

설명: sum(field) / 시간 윈도우(초)와 동일하며, 윈도우 내에서 보고된 비누적 증분 값을 초당 속도로 변환하는 데 사용합니다.

rate와의 차이:

  • rate: 단조 증가 Counter의 증가율 계산(첫 값과 마지막 값의 차이를 시간 차이로 나누고 재설정 처리)
  • rate_over_sum: 윈도우 내 모든 샘플 값을 합산한 후 시간 윈도우 초 수로 나눔

예시:

// 윈도우 내 바이트 수를 합산한 후 윈도우 초 수로 나누기
M::net:(rate_over_sum(bytes_recv)) [1h] BY host

rate_over_count

초당 이벤트 발생 횟수(count(field) / 시간 윈도우 초 수)를 계산합니다.

구문:

rate_over_count(field)

설명: count(field) / 시간 윈도우(초)와 동일하며, 로그 또는 트레이스 상세 데이터에서 초당 요청 수(QPS)를 계산할 때 자주 사용합니다.

예시:

// 각 서비스에서 초당 생성되는 오류 로그 수 계산
L::*:(rate_over_count(*) AS err_qps) {status = 'error'} [1h::5m] BY service

차이 계산

이 섹션은 함수 의미를 설명합니다. 동일한 함수를 Rollup으로 사용하거나(예: [rate], [increase]) 쿼리 내 표현식으로 작성할 수 있습니다(예: rate(field), increase(field)). 두 방식은 실행 단계가 다르므로 비즈니스 요구사항에 따라 위치를 선택하는 것이 좋습니다.

rate / deriv

변화율(도함수)을 계산합니다. rate는 Counter 유형 메트릭에 사용하고(음수 값 무시), deriv는 Gauge 유형 메트릭에 사용합니다(음수 값 유지).

별칭: rate의 별칭은 non_negative_derivative이고, deriv의 별칭은 derivative(PromQL 스타일)입니다.

구문:

// Counter 메트릭: 비음수 변화율 계산(재설정으로 인한 음수 값 무시)
rate(field)

// Gauge 메트릭: 전체 변화율 계산(음수 포함)
deriv(field)

함수 선택:

함수 설명 사용 사례
rate 비음수 변화율만 계산 Counter 유형 메트릭(단조 증가)
deriv 전체 변화율 계산(음수 포함) Gauge 유형 메트릭(증가/감소 가능)

예시:

// Counter 메트릭: NIC의 초당 송신 바이트 속도 계산
M::net:(rate(bytes_sent)) [1h::5m] BY host

// Gauge 메트릭: 사용된 메모리의 변화율 계산(초당 증가 또는 해제된 바이트 수)
M::mem:(deriv(used)) [1h::5m] BY host

increase / difference

인접 값의 차이를 계산합니다. increase는 Counter 유형 메트릭에 사용하고(음수 값 무시), difference는 Gauge 유형 메트릭에 사용합니다(음수 값 유지).

설명: increase와 difference는 서로 독립적인 함수이며 동작이 다르고 별칭 관계가 아닙니다.

구문:

// Counter 메트릭: 비음수 차이 계산(재설정으로 인한 음수 값 무시)
increase(field)

// Gauge 메트릭: 전체 차이 계산(음수 포함)
difference(field)

함수 선택:

함수 설명 사용 사례
increase 비음수 차이만 계산 Counter 유형 메트릭(단조 증가)
difference 전체 차이 계산(음수 포함) Gauge 유형 메트릭(증가/감소 가능)

예시:

// Counter 메트릭: NIC 수신 패킷 수의 증가량 계산
M::net:(increase(packets_recv)) [1h::5m] BY host

// Gauge 메트릭: 호스트 프로세스 수의 증감 변화량 계산(증가 또는 감소 가능)
M::system:(difference(process_count)) [1h::5m] BY host

이동 계산

moving_average

이동 평균을 계산합니다.

구문:

moving_average(field, n)

매개변수:

  • field: 숫자 필드
  • n: 윈도우 크기(데이터 포인트 수)

예시:

// CPU 사용률의 5포인트 이동 평균 계산
M::cpu:(moving_average(usage_total, 5)) [1h::1m] BY host

// Rollup 함수 호출로 사용: 각 시계열에 먼저 5포인트 이동 평균을 적용한 다음 host별로 집계
M::cpu:(avg(usage_total)) [1h::1m:moving_average(5)] BY host

시계열 분석 집계

다음 함수는 쿼리 내에서 집계 함수로 사용되며, 각 시간 윈도우와 그룹 내의 수치 시퀀스에 대해 하나의 수치 결과를 계산합니다.

ewma

지수 가중 이동 평균(Exponentially Weighted Moving Average)을 계산합니다. alpha는 평활 계수이며 명시적으로 전달해야 합니다.

구문:

ewma(field, alpha)

매개변수:

  • field: 숫자 필드
  • alpha: 평활 계수,取值范围 (0, 1]; 값이 클수록 최신 데이터 포인트의 가중치가 높습니다.

설명:

  • ewma에는 암시적 기본 alpha가 없으며, ewma(field)는 오류가 발생합니다.
  • 시간 절에서 Rollup으로 사용할 때는 [...:ewma(alpha)]로 작성합니다. 시간 절의 매개변수는 alpha만 전달하며 필드 이름은 전달하지 않습니다.
  • ewma는 alpha가 필요하므로 [...:ewma]처럼 매개변수 없는 Rollup 축약은 지원하지 않습니다.

예시:

// 명시적 집계 호출: Select 집계 단계에서 EWMA 계산
M::cpu:(ewma(usage_total, 0.3)) [1h::1m] BY host

// Rollup 함수 호출: 각 시계열에서 먼저 EWMA를 계산한 다음 host별로 집계
M::cpu:(avg(usage_total)) [1h::1m:ewma(0.3)] BY host

slope

시계열의 시간에 따른 선형 추세 기울기를 계산하며, 시간 단위는 초입니다.

구문:

slope(field)

설명:

  • 유효 포인트가 2개 이상 필요합니다.
  • 시간이 변하지 않았거나 유효 포인트가 부족하면 null을 반환합니다.

예시:

// 메모리 사용량의 선형 증가 기울기 계산(메모리 누수 추세 평가에 사용)
M::mem:(slope(used)) [1h::5m] BY host

zscore

최신 포인트의 윈도우 내 평균 및 표준편차 대비 Z-Score를 계산합니다.

구문:

zscore(field)

설명:

  • 결과는 (latest - mean) / stddev입니다.
  • 유효 포인트가 2개 이상 필요하며, 표준편차가 0이면 null을 반환합니다.

예시:

// 각 호스트의 최신 CPU 사용률이 과거 윈도우 대비 얼마나 벗어났는지 평가
M::cpu:(zscore(usage_total)) [1h::5m] BY host

mad_score

최신 포인트의 MAD(Median Absolute Deviation) 이상 점수를 계산합니다.

구문:

mad_score(field)

설명:

  • 중앙값과 MAD를 사용해 최신 포인트의 편차 정도를 측정하며, 평균/표준편차보다 극단값에 더 로버스트합니다.
  • 유효 포인트가 2개 이상 필요하며, MAD가 0이면 null을 반환합니다.

예시:

// 로버스트 이상 점수로 최신 CPU 사용률 포인트 탐지
M::cpu:(mad_score(usage_total)) [1h::5m] BY host

change_score

윈도우 내 시계열의 급변 점수를 계산하여 평균이 뚜렷하게 전환되는 시계열을 발견하는 데 사용합니다.

구문:

change_score(field)

설명:

  • 가능한 분할점을 열거하고, 분할점 좌우 두 구간의 평균 차이를 비교하며, 합동 표준편차로 정규화합니다.
  • 유효 포인트가 4개 이상 필요하며, 유효 포인트가 부족하면 null을 반환합니다.

예시:

// 메모리 사용률이 윈도우 내에서 계단식 급변을 일으켰는지 탐지
M::mem:(change_score(used_percent)) [1h::5m] BY host

corr

두 숫자 필드 간의 Pearson 상관 계수를 계산합니다.

구문:

corr(left_field, right_field)

설명:

  • 반환값 범위는 일반적으로 [-1, 1]입니다.
  • 유효 포인트가 2쌍 이상 필요하며,任一 필드에 변화가 없으면 null을 반환합니다.
  • corr은 두 입력 필드가 필요하므로 시간 절 Rollup 표기를 지원하지 않습니다.

예시:

// 사용자 모드 CPU와 커널 모드 CPU 사용률 간의 상관관계 계산
M::cpu:(corr(usage_user, usage_system)) [1h::5m] BY host

cumsum

누적 합을 계산합니다(외부 함수).

구문:

cumsum(DQL_expression)

예시:

// 각 서비스 로그 건수의 누적 합 계산
cumsum(L::*:(count(*)) [1h::5m] BY service)

변환 함수

변환 함수는 필드 값에 대한 수학 연산, 유형 변환 또는 문자열 처리를 수행합니다.

수학 함수

abs

절댓값을 계산합니다.

구문:

abs(field)

예시:

// 메모리 변화율의 절댓값 계산
M::mem:(abs(deriv(used))) [1h::5m] BY host

round / ceil / floor

반올림/올림/내림 함수입니다.

구문:

round(field)          // 정수로 반올림
round(field, digits)  // 지정한 소수 자릿수로 반올림
ceil(field)           // 올림
floor(field)          // 내림

예시:

// 디스크 사용률 올림
M::disk:(ceil(used_percent)) [1h] BY host

// CPU 사용률을 정수로 반올림
M::cpu:(round(usage_total)) [1h] BY host

// 평균 CPU 사용률을 소수점 2자리로 반올림
M::cpu:(round(avg(usage_total), 2) AS avg_cpu) [1h] BY host

log / log2 / log10

로그 함수입니다.

구문:

log(field)    // 자연로그
log2(field)   // 밑이 2인 로그
log10(field)  // 밑이 10인 로그

예시:

// 응답 지연 시간의 밑이 10인 로그 변환 값 계산
T::*:(log10(duration)) [1h] BY service

유형 변환

int / uint / float / string / bool

유형 변환 함수입니다.

구문:

int(field)    // 부호 있는 정수형으로 변환
uint(field)   // 부호 없는 정수형으로 변환
float(field)  // 부동소수점형으로 변환
string(field) // 문자열로 변환
bool(field)   // 부울형으로 변환

예시:

// 문자열 유형의 HTTP 상태 코드를 정수형으로 변환하여 필터링 또는 표시에 사용
T::*:(service, int(http_status_code) AS status_num) [15m] LIMIT 10

// 수치 필드를 문자열로 변환
O::HOST:(host, string(cpu_usage) AS cpu_str) LIMIT 10

문자열 함수

lower

문자열을 소문자로 변환합니다.

구문:

lower(field)

매개변수:

  • field: 문자열 필드

반환값: 변환된 소문자 문자열을 반환합니다.

예시:

// 로그 status를 모두 소문자로 변환한 후 그룹화하여 집계
L::*:(count(*)) [1h] BY lower(status) AS norm_status

upper

문자열을 대문자로 변환합니다.

구문:

upper(field)

매개변수:

  • field: 문자열 필드

반환값: 변환된 대문자 문자열을 반환합니다.

예시:

// 로그 status를 모두 대문자로 변환하여 표시
L::*:(service, upper(status) AS status_upper, message) [15m] LIMIT 10

trim

문자열 양쪽 끝의 공백 문자를 제거합니다.

구문:

trim(field)

매개변수:

  • field: 문자열 필드

반환값: 양쪽 끝 공백이 제거된 문자열을 반환합니다.

예시:

// service 필드 양쪽에 있을 수 있는 공백 문자를 제거한 후 그룹화
L::*:(count(*)) [1h] BY trim(service) AS clean_service

ltrim

문자열 왼쪽의 공백 문자를 제거합니다.

구문:

ltrim(field)

매개변수:

  • field: 문자열 필드

반환값: 왼쪽 공백이 제거된 문자열을 반환합니다.

예시:

// 로그 메시지 왼쪽 공백 문자 제거
L::*:(ltrim(message) AS trimmed_msg) [15m] LIMIT 10

rtrim

문자열 오른쪽의 공백 문자를 제거합니다.

구문:

rtrim(field)

매개변수:

  • field: 문자열 필드

반환값: 오른쪽 공백이 제거된 문자열을 반환합니다.

예시:

// 로그 메시지 오른쪽의 공백 또는 줄바꿈 문자 제거
L::*:(rtrim(message) AS trimmed_msg) [15m] LIMIT 10

length

문자열 길이를 반환합니다(문자 수 기준).

구문:

length(field)

매개변수:

  • field: 문자열 필드

반환값: 문자열 길이를 반환합니다.

예시:

// 로그 본문 문자 길이를 확인하고 초과 길이 로그 필터링
L::*:(service, length(message) AS msg_len) {CASE WHEN length(message) > 1000 THEN true ELSE false END} [15m] LIMIT 10

substr

하위 문자열을 추출합니다.

구문:

substr(field, start)
substr(field, start, length)

매개변수:

  • field: 문자열 필드
  • start: 시작 위치(0부터 시작, 음수는 끝에서부터 시작)
  • length(선택 사항): 하위 문자열 길이

반환값: 추출된 하위 문자열을 반환합니다.

예시:

// 로그 메시지 앞 100자를 잘라 미리보기
L::*:(service, substr(message, 0, 100) AS msg_preview) [15m] LIMIT 20

// 로그 메시지 마지막 10자 추출
L::*:(substr(message, -10) AS msg_tail) [15m] LIMIT 20

결과 예시:

message substr(message, 0, 10) substr(message, -5)
"Error: connection timeout" "Error: con" "eout"

regexp_extract

정규식으로 추출합니다.

구문:

regexp_extract(field, pattern)
regexp_extract(field, pattern, n)

매개변수:

  • field: 문자열 필드
  • pattern: 정규식
  • n(선택 사항): n번째 캡처 그룹을 추출하며 기본값은 0(전체 일치)

반환값: n번째 캡처 그룹의 내용을 추출한 단일 문자열을 반환합니다. 일치하는 항목이 없으면 null을 반환합니다.

예시:

// 로그 본문에서 오류 코드 추출
L::*:(regexp_extract(message, 'error_code: (\\d+)', 1) AS err_code) [15m] LIMIT 20

// 로그 본문에서 첫 번째 IPv4 주소 추출
L::*:(regexp_extract(message, '(\\d+\\.\\d+\\.\\d+\\.\\d+)', 1) AS ip) [15m] LIMIT 20

결과 예시:

service regexp_extract(message, 'error_code: (\d+)', 1)
api "404"
api "500"
web null

regexp_extract_all

일치하는 모든 결과를 추출합니다.

구문:

regexp_extract_all(field, pattern)
regexp_extract_all(field, pattern, n)

반환값: 일치하는 모든 하위 문자열을 포함하는 문자열 배열을 반환합니다.

예시:

// 로그 메시지의 모든 숫자 시퀀스 추출
L::*:(regexp_extract_all(message, '\\d+', 0) AS numbers) [15m] LIMIT 20

// 로그 메시지의 모든 IPv4 주소 추출
L::*:(regexp_extract_all(message, '\\d+\\.\\d+\\.\\d+\\.\\d+', 0) AS ips) [15m] LIMIT 20

결과 예시:

message regexp_extract_all(message, '\d+\.\d+\.\d+\.\d+', 0)
Request from 192.168.1.1 to 10.0.0.1 ["192.168.1.1", "10.0.0.1"]

regexp_replace

정규식을 사용해 일치한 텍스트를 치환합니다.

구문:

regexp_replace(field, pattern, replacement)

매개변수:

  • field: 문자열 필드
  • pattern: 정규식
  • replacement: 치환 문자열. 캡처 그룹을 참조할 때 $1, ${1}, $2 등을 사용합니다. 캡처 그룹 뒤에 영문자, 숫자 또는 밑줄이 바로 오는 경우 ${1}을 사용해 모호성을 제거합니다(예: ${1}_suffix). 리터럴 $를 출력해야 할 때는 $$를 사용합니다.

반환값: 치환된 문자열을 반환합니다. 일치하는 항목이 없으면 원래 문자열을 반환합니다.

예시:

// 메시지에서 숫자를 삭제한 후 앞 20자 접두사로 그룹화하여 집계
L::*:(count(*)) [1h] BY substr(regexp_replace(message, '\\d+', ''), 0, 20) AS prefix

// 캡처 그룹을 사용해 사용자 ID 마스킹 또는 정규화
L::*:(regexp_replace(message, 'user=([0-9]+)', 'uid=$1') AS normalized) [15m] LIMIT 20

md5

MD5 해시 값을 계산합니다.

구문:

md5(field)

반환값: 32자리 16진수 문자열(소문자)을 반환합니다.

예시:

// 로그 메시지의 MD5 지문 계산
L::*:(service, md5(message) AS msg_md5) [15m] LIMIT 20

결과 예시:

service md5(message)
api 5d41402abc4b2a76b9719d911017c592
web 098f6bcd4621d373cade4e832627b4f6

concat

문자열을 연결합니다.

구문:

concat(field, ...)

반환값: 연결된 단일 문자열을 반환합니다.

예시:

// 서비스 이름과 로그 상태 연결(예: "api:error")
L::*:(concat(service, ":", status) AS service_status, message) [15m] LIMIT 20

결과 예시:

service status concat(service, ":", status)
api error "api:error"
web info "web:info"

set

배열 필드의 중복을 제거하고 정렬합니다.

구문:

set(DQL_expression)

반환값: 중복이 제거되고 정렬된 배열을 반환합니다.

예시:

// collect로 수집한 상태 목록을 중복 제거하고 정렬
set(L::*:(collect(status)) [1h] BY service)

결과 예시:

service set(collect(status))
api ["error", "info", "warn"]
web ["info", "warn"]

로그 클러스터링

drain

Drain 알고리즘을 사용해 유사한 로그를 동일한 클래스로 묶고 해당 클래스의 로그 템플릿을 반환합니다.

구문:

drain(field, similarity_threshold)
drain(field, similarity_threshold, max_clusters)

매개변수:

  • field: 문자열 필드 또는 문자열 표현식, 일반적으로 message
  • similarity_threshold: 유사도 임계값, 범위 (0, 1]; 값이 클수록 더 유사한 로그만 동일한 클래스로 묶입니다.
  • max_clusters: 선택 사항, 최대 클러스터 수, 범위 [1, 10000]; 생략 시 기본값은 1000입니다.

반환값:

문자열 유형의 로그 템플릿을 반환합니다. 템플릿은 해당 클러스터가 생성될 때의 원본 로그를 골격으로 삼아 원본 공백과 구두점을 유지하고, 클러스터 내에서 값이 다른 토큰을 자리표시자로 바꿉니다: <num>(숫자), <hex>(16진수), <id>(식별자) 및 <*>(분류할 수 없는 가변 부분).

알고리즘 설명:

Drain은 파싱 트리 기반 로그 클러스터링 알고리즘입니다. 함수는 실행 과정에서 지속적으로 클러스터러를 학습합니다. 새 로그가 기존 클러스터에 매칭되면 해당 클러스터에 병합되고, 매칭되지 않으면 새 클러스터를 생성합니다. 템플릿은 새 로그가 병합되면서 계속 일반화되므로 동일한 클러스터라도 학습 초기와 후기에 반환되는 템플릿이 다를 수 있습니다.

사용 사례:

  • 유사 로그별 그룹화 집계
  • 이상 로그 클러스터링 분석
  • 로그 노이즈 감소

예시:

// 유사 로그 클러스터링으로 집계, 유사도 0.7, 최대 1000개 클러스터
L::*:(count(*)) [1h] BY drain(message, 0.7, 1000) AS template

// max_clusters 생략 시 기본 최대 1000개 클러스터
L::*:(count(*)) [1h] BY drain(message, 0.9) AS template

// 여러 필드를 먼저 연결한 후 클러스터링할 수도 있습니다.
L::*:(count(*)) [1h] BY drain(concat(service, " ", message), 0.7) AS template

결과 예시:

template count(*)
"Request from ... to /api/users took ms" 128
"Query SELECT * FROM orders executed in ms" 42

일치 함수

일치 함수는 WHERE 절에서 텍스트 일치를 수행하는 데 사용합니다.

하위 문자열 일치

match

필드에 지정한 하위 문자열이 포함되어 있는지 확인합니다.

구문:

match(pattern)
match(field, pattern)

매개변수:

  • pattern: 일치시킬 하위 문자열
  • field: 필드 이름(선택 사항, WHERE 절에서 생략하면 기본적으로 message와 일치)

예시:

// WHERE에서 지정 필드 일치
L::*:(service, message) {match(message, "error")} [15m] LIMIT 20

// 축약형(기본적으로 message 필드와 일치)
L::*:(service, message) {match("error")} [15m] LIMIT 20

구문 일치

토큰화 구문 일치를 수행하며 중영문 혼합을 지원합니다.

구문:

search(query)
search(field, query)

매개변수:

  • query: 쿼리 구문
  • field: 필드 이름(선택 사항)

일치 및 토큰화 규칙:

  • 영어와 숫자: 연속된 영문자와 숫자는 하나의 토큰으로 병합되며 대소문자를 구분하지 않습니다(예: Error, error, ERROR는 모두 동일한 토큰 error로 간주되고 http2는 하나의 토큰으로 간주됩니다).
  • 중국어: 일반적인 단어 또는 단일 문자 단위로 토큰화하여 일치시킵니다(예: 连接超时는 连接, 超时로 분할됩니다).
  • 구두점 및 구분자: 공백, 탭, 줄바꿈 및 모든 일반적인 구두점(., _, :, /, -, @, ?, =, & 등 포함)은 토큰 경계 구분자로 간주됩니다. 예:
  • user_name은 user, name으로 분할됩니다.
  • api.example.com은 api, example, com으로 분할됩니다.
  • host-01:8080은 host, 01, 8080으로 분할됩니다.
  • 키워드 일치(기본값): 쿼리 문자열에 여러 토큰이 포함된 경우(예: search("connection timeout")) 기본적으로 대상 텍스트에 모든 토큰이 동시에 포함되어야 하며, 토큰의 순서나 인접성은 요구하지 않습니다.
  • 구문 일치(#"..."): 값이 #으로 시작하고 큰따옴표로 감싸진 경우(예: #"build error") 구문 일치로 처리하며, 분할된 각 토큰이 원문에서 순서대로 인접해 나타나야 합니다(토큰 사이에는 공백 또는 구두점 구분자만 허용). #과 양쪽 큰따옴표는 일치 대상에 포함되지 않습니다.
  • 이전 버전 큰따옴표 표기("..."): 값이 큰따옴표로 시작하고 끝나는 경우(예: "build error") 모니터(referer=func)에서는 여전히 구문 일치 의미를 유지합니다. 그 외 쿼리 진입점에서는 따옴표 없는 키워드 일치와 동일하며, #"..." 사용을 통일하는 것이 좋습니다.
  • 순수 구두점 및 특수 경계:
  • 위 따옴표 특수 형식에 공백이나 구두점만 포함된 경우(영문자, 숫자, 중국어 문자 없음, 예: #"---") 연속 리터럴 하위 문자열 일치로 대체됩니다.
  • 빈 쿼리 ""는 어떤 내용과도 일치하지 않습니다.
  • 한쪽에만 큰따옴표가 있거나 큰따옴표가 양 끝에 있지 않은 형식은 모두 일반 토큰화 검색 인자로 처리하며 특별히 해석하지 않습니다.
  • match 또는 re로 전환해야 하는 경우:
  • 구두점을 엄격히 구분해야 하는 경우(예: user_name과 user-name 구분, @ 또는 /를 포함한 원본 하위 문자열 전체 일치): match(field, "user_name")를 사용합니다.
  • 단어 내부 하위 문자열을 일치시켜야 하는 경우(예: ana로 banana 일치, 토큰화 검색은 단어 내부 조각을 찾지 못함): match(field, "ana") 또는 wildcard(field, "*ana*")를 사용합니다.
  • 대소문자를 구분하거나 복잡한 형식으로 일치시켜야 하는 경우: re(field, "...")를 사용합니다.
  • 더 자세한 토큰화 규칙과 일반적인 예시는 DQL 전체 텍스트 검색 및 토큰화 규칙을 참고하십시오.

예시:

// "connection" 및 "timeout" 토큰을 포함하는 로그 일치
L::*:(message) {search("connection timeout")} [15m] LIMIT 20

// 중국어 일치
L::*:(message) {search("连接超时")} [15m] LIMIT 20

// 중영문 혼합
L::*:(message) {search("error 错误")} [15m] LIMIT 20

// 인접하고 순서가 일치하는 구문 일치; "build succeeded, parse error"와는 일치하지 않음
L::*:(message) {search("#\"build error\"")} [15m] LIMIT 20

// 이전 표기 큰따옴표 형식; referer=func일 때 여전히 구문 일치
L::*:(message) {search("\"build error\"")} [15m] LIMIT 20

// 구두점만 포함된 경우 연속 리터럴 하위 문자열로 직접 일치
L::*:(message) {search("#\"---\"")} [15m] LIMIT 20

정규식 일치

re / regex / regexp

정규식 일치를 수행하며 대소문자를 구분합니다.

구문:

re(pattern)
re(field, pattern)
regex(pattern)
regex(field, pattern)
regexp(pattern)
regexp(field, pattern)

매개변수:

  • pattern: 정규식(PromRegex 구문 지원)
  • field: 필드 이름(선택 사항)

예시:

// error를 포함하는 로그 일치(대소문자 구분, ERROR는 일치하지 않음)
L::*:(message) {re("error.*")} [15m] LIMIT 20

// 특정 형식의 오류 코드 일치
L::*:(message) {regexp(message, "ERR-\\d{4}")} [15m] LIMIT 20

// 데이터 소스에서 정규식으로 메저먼트 일치
M::re('cpu.*'):(avg(usage_total)) [1h] BY host

와일드카드 일치

wildcard

와일드카드 패턴 일치를 수행하며 대소문자를 구분합니다.

구문:

wildcard(pattern)
wildcard(field, pattern)

매개변수:

  • pattern: 와일드카드 패턴
  • *: 임의의 여러 문자와 일치
  • ?: 단일 문자와 일치
  • field: 필드 이름(선택 사항)

예시:

// error로 시작하는 메시지 일치(대소문자 구분, ERROR는 일치하지 않음)
L::*:(message) {wildcard("error*")} [15m] LIMIT 20

// 특정 형식 일치
L::*:(message) {wildcard(message, "ERR-????")} [15m] LIMIT 20

CIDR 일치

cidr

IP 주소 대역 일치를 수행합니다.

구문:

cidr(cidr)
cidr(field, cidr)

매개변수:

  • cidr: CIDR로 표현한 네트워크 대역, 예: 192.168.1.0/24
  • field: IP 주소 필드(선택 사항)

예시:

// 내부 네트워크 IP 일치
L::nginx:(*) {cidr(client_ip, "10.0.0.0/8")} [15m] LIMIT 20

// 특정 네트워크 대역 일치
L::nginx:(*) {cidr(client_ip, "192.168.1.0/24")} [15m] LIMIT 20

필드 존재 확인

exists

필드가 존재하는지 확인합니다. exists()는 특수 자리표시자이며 일반적으로 비교 표현식 오른쪽에 사용합니다.

구문:

exists()

권장 사용법:

field = exists()   // 필드 존재(비어 있지 않음)
field != exists()  // 필드가 없거나 비어 있음

예시:

// pod_name 필드가 있는 컨테이너 로그 찾기
L::*:(service, pod_name, message) {pod_name = exists()} [15m] LIMIT 20

// pod_name 필드가 없는 호스트 로그 찾기
L::*:(service, host, message) {pod_name != exists()} [15m] LIMIT 20

쿼리 문자열 구문

query_string

쿼리 문자열 구문으로 복잡한 일치를 수행합니다.

구문:

query_string(query)
query_string(field, query)

매개변수:

  • query: 쿼리 문자열
  • field: 필드 이름(선택 사항, 기본적으로 전체 텍스트와 일치)

쿼리 문자열 구문:

1. 토큰 일치
foo              # foo를 포함하는 내용 일치
"foo bar"        # 정확한 구문 일치, 반드시 연속으로 나타나야 함
foo\ bar         # 공백을 이스케이프하여 "foo bar" 전체와 일치
2. 와일드카드
foo*             # foo로 시작하는 내용 일치
foo?bar          # ?는 단일 문자와 일치
"foo*bar"        # 큰따옴표 안의 와일드카드는 해석하지 않고 리터럴로 일치
3. 정규식
/foo.*bar/       # 슬래시로 감싼 정규식
/joh?n(ath[oa]n)/  # 복잡한 정규식
4. 부울 연산자
foo AND bar      # 논리 AND, 둘 다 포함해야 함
foo OR bar       # 논리 OR, 하나 이상 포함해야 함
NOT foo          # 논리 NOT, foo를 포함하지 않음

# 축약형
foo && bar       # foo AND bar와 동일
foo || bar       # foo OR bar와 동일
!foo             # NOT foo와 동일
5. 그룹화
(foo OR bar) AND baz       # 괄호로 우선순위 변경
!(status 429 reading)      # 전체 표현식 부정
6. 기본 연산자

공백으로 여러 토큰을 구분할 때 기본적으로 AND로 연결합니다(모든 토큰을 동시에 포함해야 함):

foo bar          # foo AND bar와 동일
7. 토큰화 및 일치 규칙

query_string의 각 일반 토큰과 구문은 search와 동일한 토큰화 규칙을 따릅니다:

  • 토큰 분할: 연속된 영문자와 숫자는 하나의 토큰이 되며(대소문자 무시), 중국어는 단어 또는 문자 단위로 분할됩니다. 공백과 각종 구두점(예: ., _, :, /, -, @, = 등)은 모두 구분자로 사용됩니다. 예를 들어 query_string("user_name")은 user와 name 토큰을 동시에 포함하는 데이터를 검색합니다.
  • 구문 일치: 큰따옴표로 감싸거나(예: query_string("\"connection reset\"")) 공백을 이스케이프한 경우(예: query_string("connection\\ reset")) 토큰화된 토큰이 순서대로 인접해 나타나야 합니다.
  • 구두점 또는 단어 내부 하위 문자열을 일치시켜야 하는 경우: 구두점은 토큰화 단계에서 구분자로 처리되므로, 구두점을 엄격히 구분해야 하거나(예: user_name과 user.name 구분) 단어 내부 하위 문자열을 일치시켜야 하는 경우에는 match 함수를 사용하거나 query_string에서 /.../ 정규식을 사용합니다.
  • 자세한 분할 규칙과 일반적인 예시는 DQL 전체 텍스트 검색 및 토큰화 규칙을 참고하십시오.

예시:

// 단순 토큰 일치
L::*:(message) {query_string("error timeout")} [15m] LIMIT 20

// 부울 조합
L::*:(message) {query_string("error AND NOT timeout")} [15m] LIMIT 20

// 정규식
L::*:(message) {query_string("/ERR-\\d{4}/")} [15m] LIMIT 20

// 복잡한 쿼리
L::*:(message) {query_string("(error OR warn) AND timeout")} [15m] LIMIT 20

// 지정 필드
L::*:(*) {query_string(message, "error AND timeout")} [15m] LIMIT 20

// 중국어 쿼리
L::*:(message) {query_string("错误 AND 超时")} [15m] LIMIT 20

외부 함수

사용 권장 사항: 간단한 계산을 Rollup + 집계 함수(예: [rate], [last], [increase] 등)로 해결할 수 있는 경우 Rollup 방식을 우선 사용합니다. 고급 시계열 분석(anomalies, outliers, forecast 등 전체 이력 워밍업 또는 Series 간 횡단면 정렬이 필요한 함수)에는 동등한 Rollup 표기법이 없으므로 외부 함수로 사용하며, eval(...)에서 명명된 데이터 소스로 조합할 수 있습니다.

외부 함수는 전체 DQL 쿼리 결과 위에 작용하며, 쿼리 출력 시계열 데이터에 대한 2차 계산에 사용합니다. 외부 함수는 Select 절 내부가 아니라 전체 DQL 표현식을 감쌉니다.

쿼리 내 함수와 외부 함수

  • 쿼리 내 함수: DQL 표현식 내부에서 사용하는 함수(예: sum, avg, max 등)
  • 외부 함수: 전체 DQL 쿼리 결과를 감싸 출력된 시계열을 후처리하는 함수

표기 비교:

// Rollup(시간 절): 각 시계열에 먼저 증가율을 적용한 다음 집계
M::net:(sum(bytes_recv)) [1h::1m:rate] BY host

// 외부 함수: 쿼리 결과를 먼저 얻은 다음 2차 계산
rate(M::net:(sum(bytes_recv)) [1h::1m] BY host)

구문:

outer_function((DQL_expression) [, arg2, ...])

중요 구문 참고: 외부 함수에 여러 매개변수가 있고(예: moving_average, fill, top, bottom) 내부 DQL에 BY 절이 포함된 경우, 내부 DQL을 괄호 (...)로 감싸야 합니다(예: fill((M::cpu:(avg(usage_total)) [1h::5m] BY host), 0)). 그렇지 않으면 쉼표 ,가 BY 절의 두 번째 그룹화 필드로 우선解析되어 매개변수 개수 오류가 발생할 수 있습니다.

예시:

// 쿼리 내 함수: 원시 데이터에 대한 평균
M::cpu:(avg(usage_total)) [1h::5m] BY host

// 외부 함수: 쿼리 결과에 대한 이동 평균 계산(BY 절과 추가 매개변수가 있으면 내부 쿼리를 괄호로 감쌈)
moving_average((M::cpu:(avg(usage_total)) [1h::5m] BY host), 5)

누적 계산

cumsum

누적 합을 계산하여 시계열의 각 포인트에 대해 앞선 모든 포인트의 누적 값을 계산합니다.

구문:

cumsum(DQL_expression)

예시:

// 각 서비스 로그 건수의 누적 합 계산
cumsum(L::*:(count(*)) [1h::5m] BY service)

차이와 도함수

권장 사용: 이 함수들은 Rollup 함수(예: [rate], [deriv])로 사용하는 것이 우선이며, 외부 함수 형식은 집계 결과에 대한 2차 계산에만 사용합니다.

다음 함수는 외부 함수로 사용할 수 있습니다:

함수 설명
derivative(DQL) 도함수(변화율) 계산
difference(DQL) 이전 값과의 차이 계산
non_negative_derivative(DQL) 비음수 도함수 계산
non_negative_difference(DQL) 비음수 차이 계산
rate(DQL) 초당 증가율 계산
irate(DQL) 순간 증가율 계산

예시:

// 외부 함수: 쿼리 결과에 대한 도함수 계산
derivative(M::cpu:(avg(usage_total)) [1h::5m] BY host)

// 권장: 쿼리 내 집계 / Rollup 방식 사용
M::cpu:(deriv(usage_total)) [1h::5m] BY host

이동 계산

moving_average

쿼리 결과에 대한 이동 평균을 계산합니다.

권장 사용: 쿼리 내 / Rollup 방식 moving_average(field, n)을 우선 사용하며, 외부 함수 형식은 집계 결과에 대한 2차 평활에만 사용합니다.

구문:

moving_average((DQL_expression), n)

매개변수:

  • DQL_expression: DQL 쿼리 표현식(BY 절이 포함된 경우 괄호 (...)로 감싸야 함)
  • n: 윈도우 크기(데이터 포인트 수)

참고:

  • 이 형식은 수치 시퀀스에 대해 결과 집합에 최소 n개의 비어 있지 않은 데이터 포인트가 있어야 값을 출력하며, 앞의 n-1개 포인트는 null입니다. 포인트 수가 부족하면 전체 시계열이 null입니다.
  • 모니터처럼 집계 간격을 지정하지 않는 쿼리는 전체 탐지 범위가 하나의 포인트로 집계되어 각 그룹에 데이터 포인트가 하나만 있을 수 있습니다. 이 경우 DQL 내에 집계 스텝을 명시적으로 작성해야 합니다(예: moving_average((L::*:(count(*)) [1m::10s] BY host), 3)). 그렇지 않으면 윈도우가 채워지지 않아 값을 얻을 수 없습니다.

예시:

// 외부 함수: 쿼리 결과에 대한 이동 평균 계산
moving_average((M::cpu:(avg(usage_total)) [1h::1m] BY host), 5)

// 권장: 쿼리 내 방식 사용
M::cpu:(moving_average(usage_total, 5)) [1h::1m] BY host

시계열 분석과 이상 탐지

anomalies

하나의 시계열을 자체 과거 기준선과 비교하여 과거 패턴에서 벗어난 시계열 이상점을 식별합니다. 주기 없는 롤링 기준선, 일/주/시간 주기 기준선, 레벨 적응형 및 자동 선택을 지원합니다.

구문:

anomalies((<metrics-dql>), algorithm='basic|robust|agile|auto', seasonality='hourly|daily|weekly|auto', history='auto'|<duration>, band='mad|quantile', deviation=3, lower_q=0.01, upper_q=0.99, recent_window=30m)

매개변수:

  • (<metrics-dql>): 내부 기본 Metrics DQL 쿼리(시간 윈도우와 고정 step 필수, 단일 수치 measure).
  • algorithm: 알고리즘 유형, 선택 사항, 기본값 basic:
  • basic: 주기 없는 롤링 기준선으로, 평탄하거나 고정 주기가 없는 메트릭에 적합합니다.
  • robust: 주기적 로버스트 기준선(슬롯별 중앙값 + MAD로 계산)으로, 주기성이 강한 메트릭에 적합합니다.
  • agile: 주기적 적응형 기준선으로, 최근의 계단식 수준 드리프트에 빠르게 적응할 수 있습니다.
  • auto: 자동 선택으로, 과거 자기상관 계수를 기반으로 최적 주기를 자동 선택하거나 basic으로 폴백합니다.
  • seasonality: 주기 슬롯 유형: hourly, daily, weekly, auto. robust와 agile은 명시적으로 지정해야 합니다.
  • history: 이력 워밍업 윈도우 길이, 기본값 auto(basic은 max(12*step, 1h), robust/agile은 6개 전체 주기).
  • band: 정상 구간 알고리즘: mad(기본값) 또는 quantile(basic만 해당).
  • deviation: 정상 구간 너비 배수(MAD 분기 기본값 3).
  • lower_q / upper_q: 하한/상한 분위수(quantile 분기 기본값 0.01 / 0.99).
  • recent_window: 수준 조정 윈도우(agile 기본값 30m).

반환값(표준화 와이드 테이블):

열 이름 유형 설명
time int64 타임스탬프
value float64/null 실제 관측값
expected float64/null 모델 기대 기준선 값
lower / upper float64/null 정상 구간 하한과 상한
residual float64/null 실제 값과 기대 값의 잔차
score float64/null 편차 점수
is_anomaly int64/null 이상 플래그: 1(이상) 또는 0(정상)
status string 상태: ok, missing, insufficient_history, undefined_model 등
algorithm string 실제 적용된 알고리즘

예시:

// 일 주기 과거 이상 탐지
anomalies((M::cpu:(avg(usage_total) AS value) [2h::5m] BY host), algorithm='robust', seasonality='daily')

// eval에서 복합 조건 알림 수행(값이 상한 초과 및 편차 점수 > 1)
eval(
  A.value > A.upper AND A.score > 1,
  A=anomalies((M::cpu:(avg(usage_total) AS value) [2h::5m] BY host), algorithm='robust', seasonality='daily')
)

outliers

동일 시점에서 동일 피어 집합 내 서로 다른 Series(예: 클러스터 내 서로 다른 Pod 또는 Host)를 횡단면 비교하여 피어에서 벗어난 이상치를 식별합니다.

구문:

outliers((<metrics-dql>), algorithm='mad|dbscan', peer_by=['tag1', ...], tolerance=3, eps=0.5, min_peers=3, scaled=false)

매개변수:

  • (<metrics-dql>): 내부 기본 Metrics DQL 쿼리.
  • peer_by: 필수, 문자열 배열. 피어 집합을 나누는 BY 태그 하위 집합을 지정합니다(예: ['cluster']는 동일 클러스터 내에서 머신을 비교).
  • algorithm: 이상치 알고리즘, mad(횡단면 중앙값 절대 편차, 기본값) 또는 dbscan(1차원 밀도 클러스터링).
  • tolerance: MAD 편차 허용 배수, 기본값 3.
  • eps: DBSCAN 이웃 거리, 기본값 0.5.
  • min_peers: 판정에 필요한 최소 피어 수, 기본값 3(부족 시 insufficient_peers로 표시).
  • scaled: 스케일 정규화 사용 여부, 기본값 false.

반환값(표준화 와이드 테이블):

열 이름 유형 설명
time int64 타임스탬프
value float64/null 현재 피어 실제 값
expected float64/null 동일 그룹 피어 중앙값(DBSCAN은 null)
lower / upper float64/null 동일 그룹 정상 범위 하한/상한
score float64/null 이상치 점수
is_outlier int64/null 이상치 플래그: 1(이상치) 또는 0(정상)
peer_count int64/null 비교에 참여한 유효 피어 수
status string 상태: ok, insufficient_peers 등

예시:

// 동일 cluster 내에서 CPU가 피어와 크게 다른 host 탐지
outliers((M::cpu:(avg(usage_total) AS value) [1h::5m] BY cluster, host), peer_by=['cluster'], algorithm='mad')

forecast

시계열의 미래 추세와 주기를 예측하여 미래 시점의 예측값과 동적 신뢰구간을 출력합니다.

구문:

// 확장 표준 형식
forecast((<metrics-dql>), algorithm='linear|seasonal|auto', seasonality='hourly|daily|weekly|auto', history='auto'|<duration>, steps=5, deviations=3)

// 호환 축약 형식
forecast(DQL_expression, steps)

매개변수:

  • (<metrics-dql>): 내부 기본 Metrics DQL 쿼리.
  • algorithm: 예측 알고리즘, 기본값 linear:
  • linear: 선형 추세 외삽 및 발산 신뢰대.
  • seasonal: 주기 슬롯 기준선 + 수준 드리프트 보정 + 선형 추세 외삽.
  • auto: 자동 선택으로, 자기상관이 유의하면 seasonal을 선택하고 그렇지 않으면 linear로 폴백합니다.
  • seasonality: 주기 유형(hourly, daily, weekly, auto).
  • history: 이력 워밍업 윈도우, 기본값 auto(linear는 max(12*step, 1h), seasonal은 6개 주기).
  • steps: 미래 포인트 수, 선택 사항, 기본값 5, 양의 정수여야 합니다.
  • deviations: 신뢰대 너비 배수, 기본값 3.

반환값(표준화 와이드 테이블):

열 이름 유형 설명
time int64 미래 예측 타임스탬프 시퀀스($To + k \cdot step$)
forecast float64/null 미래 포인트 예측값
lower / upper float64/null 동적 신뢰구간 하한과 상한(스텝에 따라 자연스럽게 발산)
status string 상태: ok, insufficient_history, zero_variance
algorithm string 실제 적용된 알고리즘

예시:

// 향후 12개 포인트(1시간)의 CPU 추세 예측, 일 주기 고려
forecast((M::cpu:(avg(usage_total) AS value) [2h::5m] BY host), algorithm='seasonal', seasonality='daily', steps=12)

// eval에서 용량 초과 예측 알림 수행(미래 평균 90% 초과 또는 상한 95% 초과)
eval(
  F.forecast > 90 OR F.upper > 95,
  F=forecast((M::cpu:(avg(usage_total) AS value) [2h::5m] BY host), algorithm='seasonal', seasonality='daily', steps=12)
)

dbscan

쿼리 결과의 수치 시계열에 DBSCAN 이상치 탐지를 수행하고 수치형 이상 플래그를 출력합니다.

구문:

dbscan(DQL_expression)
dbscan(DQL_expression, eps)

매개변수:

  • DQL_expression: DQL 쿼리 표현식. 일반적으로 시간 윈도우와 BY 그룹화가 있는 다중 시계열 쿼리 결과에 사용합니다.
  • eps: 이웃 거리 임계값, 선택 사항, 기본값 0.5, 범위 (0, 3.0].

반환값:

  • 각 수치 열에 대해 대응하는 dbscan(column) 수치 열을 출력합니다.
  • 1은 이상치, 0은 비이상치를 나타냅니다.
  • 유효한 수치 포인트가 5개 미만이면 null을 반환하며, 샘플이 부족해 탐지를 수행하지 않았음을 나타냅니다.

설명:

  • 유효한 수치 포인트가 최소 5개 필요하며, 유효 포인트가 부족하면 null을 반환합니다.
  • 현재 구현은 입력 테이블의 각 수치 열에 대해 각각 1차원 DBSCAN을 수행하고 시간 열을 유지합니다.

예시:

// 기본 eps=0.5로 CPU 사용률 이상치 탐지
dbscan(M::cpu:(avg(usage_total)) [1h::5m] BY host)

// eps 명시적 지정
dbscan(M::cpu:(avg(usage_total)) [1h::5m] BY host, 0.8)

TopN

top / bottom

권장 사용: 쿼리 내 방식 top(field, n) 또는 bottom(field, n)을 우선 사용하며, 외부 함수 형식은 집계 결과에 대한 2차 필터링에만 사용합니다.

쿼리 결과에서 TopN 또는 BottomN을 가져옵니다.

구문:

top((DQL_expression), n)
bottom((DQL_expression), n)

예시:

// 외부 함수: 쿼리 결과에서 TopN 가져오기(내부에 BY 절이 있으면 괄호로 감쌈)
top((T::*:(max(duration)) [1h::5m] BY service), 5)

// 권장: 쿼리 내 방식 사용
T::*:(top(duration, 5)) [1h::5m] BY service

널 값 채우기

fill

쿼리 결과의 null 값을 채웁니다.

자세한 설명은 fill 함수를 참고하십시오.

예시:

// 0으로 null 값 채우기(내부에 BY 절이 있으면 괄호로 감쌈)
fill((M::cpu:(avg(usage_total)) [1h::5m] BY host), 0)

// 선형 보간으로 채우기
fill((M::cpu:(avg(usage_total)) [1h::5m] BY host), LINEAR)

기타 외부 함수

다음 함수도 외부 함수로 사용할 수 있습니다:

함수 설명
abs(DQL) 절댓값
round(DQL) / ceil(DQL) / floor(DQL) 반올림/올림/내림
log(DQL) / log2(DQL) / log10(DQL) 로그 변환
set(DQL) 중복 제거 및 정렬
concat(DQL) 문자열 연결
series_sum(DQL [, ['tag1', ...]]) 시계열(Series) 간 2차 합계

조합 사용

외부 함수는 중첩 조합하여 사용할 수 있습니다:

// 이동 평균 계산 후 반올림
round(moving_average((M::cpu:(avg(usage_total)) [1h::1m] BY host), 5))

// 증가율의 이동 평균 계산
moving_average(rate(M::net:(sum(bytes_recv)) [1h::5m] BY host), 3)

eval 표현식 계산

eval은 쿼리 외부에서 표현식 계산을 수행할 수 있는 특수 함수로, 여러 하위 쿼리의 결과를 참조해 조합 연산을 수행할 수 있습니다.

구문

eval(expression, name1=(query1), name2=(query2), ..., alias="result_name")

매개변수:

  • expression: 수학 표현식으로, name.field(또는 단일 열 별칭 name)를 사용해 하위 쿼리 결과를 참조합니다.
  • name=(query): 이름이 지정된 하위 쿼리
  • alias: 결과 별칭(선택 사항)

설명: eval은 name="query"라는 이전 표기도 지원하지만, 유형 표현과 가독성 측면에서 name=(query) 사용을 더 권장합니다.

작동 방식

  1. 모든 명명된 하위 쿼리를 실행합니다.
  2. 시간 및 그룹 태그를 기준으로 각 하위 쿼리 결과를 정렬합니다.
  3. 각 시점에 대해 표현식을 계산합니다.
  4. 계산 결과를 반환합니다.

사용 사례

  • 여러 메트릭 또는 서로 다른 데이터 소스의 비율 계산(예: 오류율, 메모리 사용률)
  • 여러 메저먼트(예: cpu와 mem)를 조합해 종합 점수 계산
  • anomalies 또는 forecast와 결합해 다중 조건 복합 알림 판단

예시

APM 서비스 오류율 백분율 계산

// 오류율 = 오류 요청 수 / 전체 요청 수 * 100
eval(a / b * 100,
     a=(T::*:(count(*)) {status = 'error'} [1h] BY service),
     b=(T::*:(count(*)) [1h] BY service),
     alias="error_rate_pct")

호스트 메모리 사용률 계산

// 사용률 = used / total * 100
eval(used / total * 100,
     used=(M::mem:(avg(used)) [1h] BY host),
     total=(M::mem:(avg(total)) [1h] BY host),
     alias="memory_usage_percent")

네트워크 패킷 오류율 계산

// 수신 패킷 오류율 = err_in / packets_recv * 100
eval(err / pkt * 100,
     err=(M::net:(sum(err_in)) [1h::5m:increase] BY host),
     pkt=(M::net:(sum(packets_recv)) [1h::5m:increase] BY host),
     alias="packet_error_rate")

하위 쿼리의 특정 필드 참조

// 동일 하위 쿼리 또는 서로 다른 하위 쿼리의 특정 별칭 필드 참조
eval(a.user_cpu / b.total_cpu * 100,
     a=(M::cpu:(avg(usage_user) AS user_cpu) [1h] BY host),
     b=(M::cpu:(avg(usage_total) AS total_cpu) [1h] BY host),
     alias="user_cpu_share_pct")

참고 사항

  • 모든 하위 쿼리의 시간 윈도우는 호환되어야 합니다.
  • 하위 쿼리의 그룹화 차원은 일관되어야 합니다.
  • 표현식에서 참조하는 필드 이름은 name.field 형식을 사용합니다(하위 쿼리에 프로젝션 열이 하나만 있으면 name으로 직접 참조할 수도 있음).

기타 함수

fill

쿼리 결과의 null 값을 지정한 값으로 채웁니다.

권장 사용 방식: fill은 외부 함수로 사용하는 것을 권장하며, 전체 쿼리 결과에 적용합니다(참고: 내부 DQL에 BY 절이 있으면 내부 쿼리를 괄호 (...)로 감싸야 합니다):

fill((M::cpu:(avg(usage_total)) [1h::5m] BY host), 0)

동시에 Select 절에서도 fill(avg(usage_total), 0) 쿼리 내 표기를 지원합니다:

M::cpu:(fill(avg(usage_total), 0)) [1h::5m] BY host

구문(외부 함수):

fill((DQL_expression), value)
fill((DQL_expression), LINEAR)
fill((DQL_expression), PREVIOUS)

매개변수:

  • DQL_expression: DQL 쿼리 표현식(BY 절이 포함된 경우 괄호로 감싸야 함)
  • value: 채울 값, 여러 모드 지원:
  • 구체적인 값: 숫자, 문자열, null
  • LINEAR: 선형 보간
  • PREVIOUS: 이전 비어 있지 않은 값으로 채우기

예시:

// 권장: 외부 함수로 사용하여 빈 버킷을 0으로 채우기
fill((M::cpu:(avg(usage_total)) [1h::5m] BY host), 0)

// 선형 보간으로 채우기
fill((M::cpu:(avg(usage_total)) [1h::5m] BY host), LINEAR)

// 이전 비어 있지 않은 값으로 채우기
fill((M::cpu:(avg(usage_total)) [1h::5m] BY host), PREVIOUS)

now

현재 타임스탬프(밀리초)를 반환합니다.

구문:

now()

예시:

// 최근 10분(600000밀리초) 내에 보고된 호스트 객체 조회
O::HOST:(host, state, cpu_usage) {last_update_time > now() - 600000} LIMIT 20

unwrap

집계 함수 출력 열 이름의 외부 함수 이름 래핑을 제거하여 결과 열 이름이 내부 필드 이름을 유지하도록 합니다(예: avg(usage_total)의 출력 열 이름을 usage_total로 복원하며, avg(usage_total) AS usage_total과 동일).

구문:

unwrap(aggregate_expression)

예시:

// avg(usage_total)을 계산하고 반환 열 이름을 usage_total로 단순화
M::cpu:(unwrap(avg(usage_total))) [1h] BY host

Show 함수

Show 함수는 메타데이터(예: measurement, tag, field, 카디널리티 및 시리즈 수)를 조회하는 데 사용하며, 모델링 문제 해결과 쿼리 전 탐색에 자주 사용합니다.

일반 구문

show_xxx(arg1=..., arg2=...){ where_conditions } [time_window] LIMIT n OFFSET m
  • where, time_window, LIMIT, OFFSET은 모두 선택 사항입니다.
  • LIMIT/OFFSET은 음수일 수 없습니다.

M 네임스페이스 내장 Show 함수

함수 매개변수 반환 열 설명
show_measurement 선택 사항 re('pattern') name measurement 나열
show_tag_key 선택 사항 from=['measurement'], 선택 사항 by='field' tagKey; by='field'일 때 name, field, tagKey tag key 나열; by='field'이면 필드별로 그룹화하여 반환하고 한 번의 스캔으로 전체 메저먼트를 처리
show_field_key 선택 사항 from=['measurement'] fieldKey, fieldType field key 나열(현재 fieldType은 float)
show_tag_value keyin=['tagKey'](필수), 선택 사항 from, 선택 사항 by='field' key, value; by='field'일 때 name, field, key, value tag value 나열; by='field'이면 필드별로 그룹화하여 반환하고 한 번의 스캔으로 전체 메저먼트를 처리
show_measurement_cardinality 필수 매개변수 없음 count measurement 수
show_series_cardinality 필수 매개변수 없음 count series 카디널리티(추정)
show_tag_key_cardinality 필수 매개변수 없음 count tag key 카디널리티(추정)
show_tag_value_cardinality keyin=['tagKey'](필수) count 지정한 tag key의 value 카디널리티(추정)
show_field_key_cardinality 필수 매개변수 없음 count field key 카디널리티(추정)
show_series_count_by_field_key from=['measurement'](권장) name, count field key별 series 수 통계
show_series_count_by_tag_key from=['measurement'](권장) name, count, value_count tag key별 series 수와 value 수 통계
show_series_count_by_tag_value keyin=['tagKey'](필수), from=['measurement'](권장) name, count 지정한 tag key의 value별 series 수 통계

카디널리티 관련 함수는 내부적으로 HyperLogLog 병합을 사용하며 반환값은 추정값입니다.

비 M 네임스페이스 Show 함수

비 M 네임스페이스(로그 L, 트레이스 T, 객체 O, RUM R, 네트워크 N, 보안 이벤트 E, 미터링 metering 등)에는 명시적 namespace 매개변수 사용을 권장합니다:

  • show_source(namespace='L')
  • show_field(namespace='L', source='mysql')
  • show_label(namespace='L', name='env')
  • show_index(namespace='L')
  • show_class(namespace='L')
  • show_type(namespace='L')

예시:

show_source(namespace='L')
show_field(namespace='L')
show_field(namespace='T', source='mysql')
show_label(namespace='L', name='env')
show_label(namespace='L', names=['env', 'team'])
show_index(namespace='L')
show_field(namespace='metering')

이전 버전 호환 표기(접미사 모드)

기존 클라이언트 및 쿼리 이력과의 호환성을 위해 시스템은 다음 접미사 모드를 유지합니다:

  • show_<namespace>_source
  • show_<namespace>_class
  • show_<namespace>_type
  • show_<namespace>_field
  • show_<namespace>_label
  • show_<namespace>_index

여기서 <namespace>는 함수 이름 중간 세그먼트에서 자동으로 매핑됩니다. 예:

  • show_logging_source -> L
  • show_tracing_field -> T
  • show_object_source -> O

일반적인 예시:

show_logging_source()
show_tracing_field('mysql')
show_logging_field('*')
show_logging_label(name='env')
show_logging_label(names=['env', 'team'])

매개변수 및 동작 설명

  • from: measurement 목록, 문자열 또는 문자열 배열 지원.
  • keyin: tag key 목록, 문자열 또는 문자열 배열 지원.
  • field: field 목록, 문자열 또는 문자열 배열 지원(metric show의 field 필터링에 사용).
  • show_field의 경우:
  • source(또는 별칭 from): 데이터 소스 이름, 단일 문자열 또는 문자열 배열 지원(예: source='mysql' 또는 source=['mysql', 'redis']). 제공하지 않거나 source='*'를 지정하면 전체 데이터 소스 필드를 조회합니다.
  • 새 함수에는 이름 없는 위치 인자를 전달할 수 없으며, 반드시 명명된 매개변수를 명시적으로 사용해야 합니다.
  • 나머지 명명된 매개변수(예: env='prod')는 하위 데이터 쿼리의 where 필터 조건으로 변환됩니다.
  • 이전 버전 호환 함수 show_<namespace>_field의 경우:
  • 기존 위치 인자 로직 유지: 첫 번째 이름 없는 인자(예: 'mysql')는 source 필터로 사용되고, '*'는 source를 지정하지 않는 것과 동일합니다.
  • 명명된 매개변수는 where 필터 조건으로 변환됩니다.
  • isVariantField는 해당 필드가 독립적인 물리 열이 아니라 variant(var object) 열에 저장되어 있음을 나타냅니다. 여러 index를 조회할 때 하나의 index라도 이를 variant 열에 저장하면 true를 반환합니다.
  • show_*_label의 경우:
  • 명명된 매개변수가 필요하며, names는 name의 별칭으로 처리됩니다.

제약 및 참고 사항

  • show_tag_value와 show_tag_value_cardinality는 keyin을 반드시 제공해야 합니다.
  • show_tag_key(..., by='field')와 show_tag_value(..., by='field')는 (name, field) 기준으로 그룹화하여 반환하며, LIMIT/OFFSET은 각 그룹에 각각 적용되고 모든 필드가 하나의 페이지네이션 할당량을 공유하지 않습니다. 결과는 독립적인 서버 측 전체 상한의 제약도 받으며, 이 상한은 LIMIT/OFFSET에 따라 줄어들지 않습니다.
  • 그룹화된 tag key는 tagKey 기준으로 정렬한 후 페이지네이션합니다. 그룹화된 tag value는 먼저 keyin과 각 key의 값을 중복 제거한 다음 (key, value) 기준으로 정렬하며, 각 필드에 대해 한 번만 페이지네이션합니다. 예를 들어 keyin=['host', 'zone'] LIMIT 1 OFFSET 1은 각 key마다 한 행씩 반환하는 것이 아니라 각 필드에서 정렬된 두 번째 행을 반환합니다.
  • by='field' 결과에는 필드에 귀속될 수 있는 데이터만 포함됩니다. 결과에 특정 필드가 없으면 show_field_key로 해당 필드의 존재 여부를 확인할 수 있습니다.
  • show_tag_value(..., by='field')의 key 열은 keyin에 지정한 tag key입니다.
  • 그룹화된 tag value 쿼리는 시간 범위 내에 샘플이 존재하는지 검증합니다. 후보 시계열이 너무 많으면 인덱스 쿼리로 폴백되며, 결과에 지정한 시간 범위 밖에서만 나타나는 값이 포함될 수 있습니다.
  • show_series_count_by_tag_value는 keyin을 반드시 제공해야 합니다.
  • show_series_count_by_*는 from을 제공하거나 where에 동등한 source 제약(예: @__source__ 조건)을 제공해야 합니다.
  • show_<namespace>_source, show_<namespace>_class, show_<namespace>_type은 현재 동일한 실행 경로를 공유하며 source 중복 제거 목록을 반환합니다.
  • Query API가 show 시간 범위를 제공하지 않으면 일부 로그 show 쿼리는 최근 30분 윈도우로 폴백하여 실행됩니다.

반환 예시

다음 예시는 일반적인 열 구조와 예시 행만 보여 주며, 실제 결과는 테넌트 데이터, 필터 조건, 시간 범위 및 LIMIT/OFFSET의 영향을 받습니다.

쿼리 일반적인 열 예시 행(참고)
show_measurement() name cpu, disk, memory
show_tag_key(from=['windows'], by='field') name, field, tagKey windows, usage, host; windows, idle, device
show_tag_value(from=['windows'], keyin=['host'], by='field') name, field, key, value windows, usage, host, node-1; windows, idle, host, node-3
show_tag_value(from=['cpu'], keyin=['host']) key, value host, web-01; host, web-02
show_series_count_by_tag_key(from=['cpu']) name, count, value_count host, 3200, 120; service, 2800, 35
show_tag_value_cardinality(keyin=['host']) count 120
show_logging_field('*') fieldKey, fieldType, fieldIndices, isVariantField service, keyword, [{"type":"inverted"}], false
show_logging_source() source nginx, mysql, redis

함수 분류 빠른 참조표

기본 집계

함수 설명 정확/추정
sum 합계 정확
avg 평균값 정확
count 카운트 정확
count(distinct) 정확한 중복 제거 카운트 정확
count_distinct 중복 제거 카운트 추정(HyperLogLog, 오차 ≈0.4%)
min / max 최솟값/최댓값 정확
first / last 첫 번째/마지막 값 정확
any 임의의 값 정확

통계 집계

함수 설명 정확/추정
percentile / pXX 백분위수 추정(로그 히스토그램)
median 중앙값 추정
stddev 표준편차 정확
mode 최빈값 정확
spread 범위 정확
count_series 시계열 수 정확

시계열 분석 집계

함수 설명 비고
ewma 지수 가중 이동 평균 [...:ewma(alpha)] 지원
slope 선형 추세 기울기 Rollup 축약으로 사용 가능
zscore 최신 포인트 Z-Score Rollup 축약으로 사용 가능
mad_score 최신 포인트 MAD 이상 점수 Rollup 축약으로 사용 가능
change_score 시계열 급변 점수 Rollup 축약으로 사용 가능
corr 두 필드 Pearson 상관 계수 두 입력 필드 필요

필터 집계

함수 설명 정확/추정
top / bottom TopN / BottomN 정확
count_filter 조건부 카운트 정확

히스토그램 함수

함수 설명 적용 데이터 소스 정확/추정
histogram_auto 자동 히스토그램(권장) 로그, Trace 상세 데이터 추정
histogram 고정 버킷 경계 히스토그램(지원 중단) 로그, Trace 상세 데이터 정확
histogram_quantile Prometheus 히스토그램에서 분위수 계산 Prometheus 메트릭 추정

집합 함수

함수 설명 정확/추정
distinct 중복 제거 값 목록 정확
distinct_by_collapse 접힌 중복 제거(다른 필드의 마지막 값 유지) 정확
collect 모든 값 수집(배열 반환) 정확
collect_distinct 중복 제거 값 수집(배열 반환) 정확
field_values 중복 제거 값 및 발생 횟수(hits) 통계 정확

보조 함수

함수 설명 정확/추정
default 빈 집계 결과에 기본값 설정 정확
unwrap 집계 열 이름의 외부 함수 이름 제거 정확

시계열 함수

함수 설명
rate 증가율(초당)
irate 순간 증가율
increase 증가량
derivative 도함수
difference 차이
non_negative_derivative 비음수 도함수
non_negative_difference 비음수 차이
moving_average 이동 평균
cumsum 누적 합
ewma 지수 가중 이동 평균
slope 추세 기울기
zscore 최신 포인트 Z-Score
mad_score MAD 이상 점수
change_score 급변 점수
corr 상관 계수

Rollup 함수

함수 설명
rate 초당 증가율 계산
irate 순간 증가율 계산
increase 증가량 계산
rate_over_sum 초당 평균값 계산
rate_over_count 초당 카운트 계산
deriv 도함수 계산(derivative)
difference 차이 계산(difference)
sum 합계
avg 평균값
min 최솟값
max 최댓값
count 카운트
first 첫 번째 값
last 마지막 값
stddev 표준편차
mode 최빈값
spread 범위
any 임의의 값
ewma(alpha) 지수 가중 이동 평균
moving_average(n) 이동 평균
percentile(p) 백분위수
slope 선형 추세 기울기
zscore 최신 포인트 Z-Score
mad_score 최신 포인트 MAD 이상 점수
change_score 시계열 급변 점수

변환 함수

함수 설명
abs 절댓값
round / ceil / floor 반올림/올림/내림
log / log2 / log10 로그
int / uint / float / string / bool 유형 변환
lower / upper 대소문자 변환
trim / ltrim / rtrim 공백 문자 제거
length 문자열 길이
substr 하위 문자열
regexp_extract 정규식 추출
regexp_extract_all 정규식 전체 추출
regexp_replace 정규식 치환
md5 MD5 해시
concat 문자열 연결
set 배열 중복 제거 및 정렬
drain 로그 클러스터링

일치 함수

함수 설명
match 하위 문자열 일치
search 토큰화 구문 일치
re / regex / regexp 정규식 일치
wildcard 와일드카드 일치
cidr CIDR 대역 일치
query_string 쿼리 문자열 구문
exists 필드 존재 확인

외부 함수

함수 설명
cumsum 누적 합
rate / irate 증가율(비음수)
deriv 도함수(음수 허용)
increase 증가량(비음수)
difference 차이(음수 허용)
moving_average 이동 평균
top / bottom TopN
dbscan DBSCAN 이상치 탐지
anomalies 시계열 이력 이상 탐지
outliers 동종 피어 이상치 탐지
forecast 추세 및 주기 예측
fill 널 값 채우기(외부 사용 권장)
abs / round / ceil / floor 수학 연산
set 중복 제거 및 정렬
concat 문자열 연결

표현식 계산

함수 설명
eval 다중 쿼리 표현식 계산

문서 평가

이 페이지가 도움이 되었나요?