DQL 함수 참조¶
DQL은 데이터 집계, 변환 및 일치를 위한 다양한 함수를 제공합니다. 이 문서에서는 각 함수의 의미, 매개변수 및 사용 방법을 자세히 설명합니다.
집계 함수¶
집계 함수는 여러 행의 데이터를 단일 값으로 집계하는 데 사용되며, 일반적으로 시간 윈도우(time-expr) 및 그룹화(BY 절)와 함께 사용합니다.
기본 집계¶
sum¶
필드 값의 합계를 계산합니다.
구문:
매개변수:
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¶
필드 값의 평균값을 계산합니다.
구문:
매개변수:
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¶
데이터 행 수 또는 비어 있지 않은 필드 값 수를 계산합니다.
구문:
매개변수:
field: 임의의 필드, 비어 있지 않은 값의 수를 계산합니다.distinct(field): 필드의 정확한 중복 제거 값 수를 계산합니다.*: 모든 행 수를 계산합니다(로그L, 트레이스T, 객체O, RUMR, 이벤트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¶
필드의 최솟값 또는 최댓값을 계산합니다.
구문:
매개변수:
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¶
시간 순서에 따라 첫 번째 또는 마지막 값을 가져옵니다.
구문:
매개변수:
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¶
비어 있지 않은 임의의 값을 반환합니다. 그룹 집계 시 샘플 데이터(예: 샘플 오류 메시지 하나)를 가져오거나 특정 시간 순서가 필요 없는 시나리오에 적합합니다.
구문:
매개변수:
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는 프로젝션에서 과거 윈도우의 집계 값을 참조하여 현재 집계 결과와 정렬해 표시합니다:
현재 값, 과거 값 및 파생 계산은 모두 프로젝션 표현식에서 명시적으로 제공됩니다. 동일한 과거 값을 여러 번 참조할 때는 동일한 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¶
범위(최댓값과 최솟값의 차이)를 계산합니다.
구문:
매개변수:
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¶
표준편차를 계산하여 메트릭 또는 지연 시간의 분산 변동 정도를 측정합니다.
구문:
매개변수:
field: 숫자 필드
예시:
// 각 호스트 CPU 사용률의 표준편차 계산
M::cpu:(stddev(usage_total) AS cpu_stddev) [1h] BY host
// 각 서비스 응답 소요 시간의 표준편차 계산
T::*:(stddev(duration) AS duration_stddev) [1h] BY service
mode¶
최빈값(가장 자주 나타나는 값)을 계산합니다.
구문:
매개변수:
field: 임의의 필드
예시:
// 각 서비스의 APM 호출에서 가장 자주 나타나는 HTTP 상태 코드 찾기
T::*:(mode(http_status_code) AS most_common_status) [1h] BY service
count_series¶
시계열(Series) 수를 계산하여 현재 쿼리 범위 내에 독립적인 시계열이 몇 개 있는지 반환합니다.
구문:
매개변수:
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¶
필드의 서로 다른 값 수(추정값)를 계산합니다.
구문:
매개변수:
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¶
필드의 백분위수(추정값)를 계산합니다.
구문:
매개변수:
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)과 동일합니다.
구문:
예시:
히스토그램 함수¶
DQL은 데이터 소스와 시나리오에 따라 세 가지 히스토그램 관련 함수를 제공합니다:
| 함수 | 사용 사례 | 데이터 소스 유형 | 권장도 |
|---|---|---|---|
histogram_auto |
로그, Trace 등 상세 데이터의 수치 분포 통계 | 상세 모델(로그/Trace) | ⭐⭐⭐ 권장 |
histogram |
고정 버킷 경계가 필요한 히스토그램 | 상세 모델(로그/Trace) | ⭐⭐ Deprecated |
histogram_quantile |
Prometheus 히스토그램 메트릭에서 분위수 계산 | Prometheus 메트릭 | ⭐⭐⭐ 권장 |
histogram_auto(권장)¶
분포 히스토그램을 자동 생성하며, 로그, Trace 등 상세 데이터의 수치 분포 통계를 위해 설계되었습니다.
특징:
- 버킷 경계를 지정할 필요 없이 데이터 분포에 자동 적응
- 로그-선형 보간 히스토그램 알고리즘을 사용하여 10⁻⁹ ~ 10¹⁸ 수치 범위 커버
- 분위수 통계와 버킷 분포 정보를 동시에 반환
구문:
매개변수:
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는 데이터 분포에 자동 적응하고 더 넓은 수치 범위를 커버하며 더 풍부한 통계 정보를 반환합니다.
구문:
매개변수:
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)여야 함
구문:
매개변수:
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의 경계를 식별합니다:
- Prometheus 형식(기본값):
le태그를 사용해 bucket 상한을 직접 표현합니다. le값은 숫자(예:"0.1","1","10") 또는"+Inf"(무한대)입니다.-
데이터는 누적 카운트(cumulative)여야 합니다.
-
VictoriaMetrics 형식:
vmrange태그로 범위를 표현합니다. - 형식은
"하한...상한"(예:"0.1...0.2")입니다. - 데이터는 범위 카운트(비누적)입니다.
- 함수는 범위 카운트를 자동으로 누적 카운트로 변환합니다.
계산 과정:
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:
PromQL 동등:
시나리오 2: 각 서비스의 P95 지연 시간 계산(다중 그룹)
DQL:
PromQL 동등:
시나리오 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태그가 없으면 계산할 수 없습니다. +Infbucket이 없으면 마지막 bucket의 상한이 최댓값으로 사용됩니다.- 카운트가 0 또는 NaN인 bucket은 건너뜁니다.
- 분위수가 < 0이면 -Inf, > 1이면 +Inf를 반환합니다.
TopN 함수¶
top¶
그룹 내에서 가장 큰 값 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개를 가져옵니다.
구문:
매개변수:
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¶
필드의 모든 서로 다른 값을 반환합니다(각 행에 서로 다른 값 하나).
구문:
예시:
결과 예시:
| service | distinct(status) |
|---|---|
| api | info |
| api | warn |
| api | error |
| web | info |
참고: 여러 행을 반환하며, 각 행에는 서로 다른 값 하나가 포함됩니다.
distinct_by_collapse¶
접기 전략으로 필드의 서로 다른 값을 가져오고, 중복 제거 시 지정한 다른 필드의 마지막 값을 유지합니다.
구문:
매개변수:
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¶
모든 값(중복 포함)을 수집하여 배열 유형으로 반환합니다.
구문:
매개변수:
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¶
모든 서로 다른 값을 수집하여 중복 제거된 배열을 반환합니다.
구문:
매개변수:
field: 임의의 필드limit(선택 사항): 최대 수집 수
예시:
결과 예시:
| service | collect_distinct(host) |
|---|---|
| api | ["node-01", "node-02"] |
| web | ["node-03"] |
참고: 중복 제거된 모든 값을 포함하는 배열 유형을 반환합니다.
field_values¶
필드의 모든 서로 다른 값과 발생 횟수(hits)를 집계하여 중복 제거 값 열과 대응하는 hits 카운트 열을 반환합니다.
구문:
매개변수:
field: 임의의 필드(스칼라 또는 배열 필드. 배열 필드는 자동으로 펼쳐 각 요소의 발생 횟수를 집계)
예시:
결과 예시:
| field_values(status) | hits |
|---|---|
| "info" | 15420 |
| "warn" | 320 |
| "error" | 45 |
참고: 여러 행을 반환하며, 중복 제거된 필드 값 열
field_values(field)와 대응하는 발생 횟수 열hits를 포함합니다.
필터 집계¶
count_filter¶
지정한 목록에 포함된 필드 값의 수를 집계합니다.
구문:
매개변수:
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¶
필드에 기본값을 설정하며, 집계 결과가 비어 있으면 기본값을 반환합니다.
구문:
매개변수:
field: 임의의 필드default_value: 기본값(숫자, 문자열, 부울 또는 null 가능)
예시:
시계열 함수¶
시계열 함수는 시간에 따라 변하는 데이터, 특히 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는 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 메트릭의 순간 증가율(초당)을 계산합니다.
구문:
설명:
rate와 달리 irate는 윈도우 내 마지막 두 데이터 포인트만 사용해 증가율을 계산하므로 순간 변화율을 반영하며 단기 스파이크에 더 민감합니다.
예시:
increase¶
Counter 메트릭의 시간 윈도우 내 총 증가량을 계산합니다.
구문:
설명:
increase는 초당 속도가 아니라 시간 윈도우 내 누적 증분을 반환합니다.
예시:
// 각 호스트가 지난 1시간 동안 5분마다 새로 수신한 데이터 패킷 수 계산
M::net:(sum(packets_recv) AS new_packets) [1h::5m:increase] BY host
rate_over_sum¶
초당 평균값(sum(field) / 시간 윈도우 초 수)을 계산합니다.
구문:
설명:
sum(field) / 시간 윈도우(초)와 동일하며, 윈도우 내에서 보고된 비누적 증분 값을 초당 속도로 변환하는 데 사용합니다.
rate와의 차이:
rate: 단조 증가 Counter의 증가율 계산(첫 값과 마지막 값의 차이를 시간 차이로 나누고 재설정 처리)rate_over_sum: 윈도우 내 모든 샘플 값을 합산한 후 시간 윈도우 초 수로 나눔
예시:
rate_over_count¶
초당 이벤트 발생 횟수(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¶
이동 평균을 계산합니다.
구문:
매개변수:
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는 평활 계수이며 명시적으로 전달해야 합니다.
구문:
매개변수:
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¶
시계열의 시간에 따른 선형 추세 기울기를 계산하며, 시간 단위는 초입니다.
구문:
설명:
- 유효 포인트가 2개 이상 필요합니다.
- 시간이 변하지 않았거나 유효 포인트가 부족하면 null을 반환합니다.
예시:
zscore¶
최신 포인트의 윈도우 내 평균 및 표준편차 대비 Z-Score를 계산합니다.
구문:
설명:
- 결과는
(latest - mean) / stddev입니다. - 유효 포인트가 2개 이상 필요하며, 표준편차가 0이면 null을 반환합니다.
예시:
mad_score¶
최신 포인트의 MAD(Median Absolute Deviation) 이상 점수를 계산합니다.
구문:
설명:
- 중앙값과 MAD를 사용해 최신 포인트의 편차 정도를 측정하며, 평균/표준편차보다 극단값에 더 로버스트합니다.
- 유효 포인트가 2개 이상 필요하며, MAD가 0이면 null을 반환합니다.
예시:
change_score¶
윈도우 내 시계열의 급변 점수를 계산하여 평균이 뚜렷하게 전환되는 시계열을 발견하는 데 사용합니다.
구문:
설명:
- 가능한 분할점을 열거하고, 분할점 좌우 두 구간의 평균 차이를 비교하며, 합동 표준편차로 정규화합니다.
- 유효 포인트가 4개 이상 필요하며, 유효 포인트가 부족하면 null을 반환합니다.
예시:
corr¶
두 숫자 필드 간의 Pearson 상관 계수를 계산합니다.
구문:
설명:
- 반환값 범위는 일반적으로
[-1, 1]입니다. - 유효 포인트가 2쌍 이상 필요하며,任一 필드에 변화가 없으면 null을 반환합니다.
corr은 두 입력 필드가 필요하므로 시간 절 Rollup 표기를 지원하지 않습니다.
예시:
cumsum¶
누적 합을 계산합니다(외부 함수).
구문:
예시:
변환 함수¶
변환 함수는 필드 값에 대한 수학 연산, 유형 변환 또는 문자열 처리를 수행합니다.
수학 함수¶
abs¶
절댓값을 계산합니다.
구문:
예시:
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¶
로그 함수입니다.
구문:
예시:
유형 변환¶
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¶
문자열을 소문자로 변환합니다.
구문:
매개변수:
field: 문자열 필드
반환값: 변환된 소문자 문자열을 반환합니다.
예시:
upper¶
문자열을 대문자로 변환합니다.
구문:
매개변수:
field: 문자열 필드
반환값: 변환된 대문자 문자열을 반환합니다.
예시:
trim¶
문자열 양쪽 끝의 공백 문자를 제거합니다.
구문:
매개변수:
field: 문자열 필드
반환값: 양쪽 끝 공백이 제거된 문자열을 반환합니다.
예시:
ltrim¶
문자열 왼쪽의 공백 문자를 제거합니다.
구문:
매개변수:
field: 문자열 필드
반환값: 왼쪽 공백이 제거된 문자열을 반환합니다.
예시:
rtrim¶
문자열 오른쪽의 공백 문자를 제거합니다.
구문:
매개변수:
field: 문자열 필드
반환값: 오른쪽 공백이 제거된 문자열을 반환합니다.
예시:
length¶
문자열 길이를 반환합니다(문자 수 기준).
구문:
매개변수:
field: 문자열 필드
반환값: 문자열 길이를 반환합니다.
예시:
// 로그 본문 문자 길이를 확인하고 초과 길이 로그 필터링
L::*:(service, length(message) AS msg_len) {CASE WHEN length(message) > 1000 THEN true ELSE false END} [15m] LIMIT 10
substr¶
하위 문자열을 추출합니다.
구문:
매개변수:
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¶
정규식으로 추출합니다.
구문:
매개변수:
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¶
일치하는 모든 결과를 추출합니다.
구문:
반환값: 일치하는 모든 하위 문자열을 포함하는 문자열 배열을 반환합니다.
예시:
// 로그 메시지의 모든 숫자 시퀀스 추출
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¶
정규식을 사용해 일치한 텍스트를 치환합니다.
구문:
매개변수:
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 해시 값을 계산합니다.
구문:
반환값: 32자리 16진수 문자열(소문자)을 반환합니다.
예시:
결과 예시:
| service | md5(message) |
|---|---|
| api | 5d41402abc4b2a76b9719d911017c592 |
| web | 098f6bcd4621d373cade4e832627b4f6 |
concat¶
문자열을 연결합니다.
구문:
반환값: 연결된 단일 문자열을 반환합니다.
예시:
// 서비스 이름과 로그 상태 연결(예: "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¶
배열 필드의 중복을 제거하고 정렬합니다.
구문:
반환값: 중복이 제거되고 정렬된 배열을 반환합니다.
예시:
결과 예시:
| service | set(collect(status)) |
|---|---|
| api | ["error", "info", "warn"] |
| web | ["info", "warn"] |
로그 클러스터링¶
drain¶
Drain 알고리즘을 사용해 유사한 로그를 동일한 클래스로 묶고 해당 클래스의 로그 템플릿을 반환합니다.
구문:
매개변수:
field: 문자열 필드 또는 문자열 표현식, 일반적으로messagesimilarity_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 |
128 |
| "Query SELECT * FROM orders executed in |
42 |
일치 함수¶
일치 함수는 WHERE 절에서 텍스트 일치를 수행하는 데 사용합니다.
하위 문자열 일치¶
match¶
필드에 지정한 하위 문자열이 포함되어 있는지 확인합니다.
구문:
매개변수:
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: 쿼리 구문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¶
와일드카드 패턴 일치를 수행하며 대소문자를 구분합니다.
구문:
매개변수:
pattern: 와일드카드 패턴*: 임의의 여러 문자와 일치?: 단일 문자와 일치field: 필드 이름(선택 사항)
예시:
// error로 시작하는 메시지 일치(대소문자 구분, ERROR는 일치하지 않음)
L::*:(message) {wildcard("error*")} [15m] LIMIT 20
// 특정 형식 일치
L::*:(message) {wildcard(message, "ERR-????")} [15m] LIMIT 20
CIDR 일치¶
cidr¶
IP 주소 대역 일치를 수행합니다.
구문:
매개변수:
cidr: CIDR로 표현한 네트워크 대역, 예:192.168.1.0/24field: 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()는 특수 자리표시자이며 일반적으로 비교 표현식 오른쪽에 사용합니다.
구문:
권장 사용법:
예시:
// 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: 쿼리 문자열field: 필드 이름(선택 사항, 기본적으로 전체 텍스트와 일치)
쿼리 문자열 구문:
1. 토큰 일치¶
foo # foo를 포함하는 내용 일치
"foo bar" # 정확한 구문 일치, 반드시 연속으로 나타나야 함
foo\ bar # 공백을 이스케이프하여 "foo bar" 전체와 일치
2. 와일드카드¶
3. 정규식¶
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. 그룹화¶
6. 기본 연산자¶
공백으로 여러 토큰을 구분할 때 기본적으로 AND로 연결합니다(모든 토큰을 동시에 포함해야 함):
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)
구문:
중요 구문 참고: 외부 함수에 여러 매개변수가 있고(예:
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¶
누적 합을 계산하여 시계열의 각 포인트에 대해 앞선 모든 포인트의 누적 값을 계산합니다.
구문:
예시:
차이와 도함수¶
권장 사용: 이 함수들은 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차 평활에만 사용합니다.
구문:
매개변수:
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 이상치 탐지를 수행하고 수치형 이상 플래그를 출력합니다.
구문:
매개변수:
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을 가져옵니다.
구문:
예시:
// 외부 함수: 쿼리 결과에서 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은 쿼리 외부에서 표현식 계산을 수행할 수 있는 특수 함수로, 여러 하위 쿼리의 결과를 참조해 조합 연산을 수행할 수 있습니다.
구문¶
매개변수:
expression: 수학 표현식으로,name.field(또는 단일 열 별칭name)를 사용해 하위 쿼리 결과를 참조합니다.name=(query): 이름이 지정된 하위 쿼리alias: 결과 별칭(선택 사항)
설명:
eval은name="query"라는 이전 표기도 지원하지만, 유형 표현과 가독성 측면에서name=(query)사용을 더 권장합니다.
작동 방식¶
- 모든 명명된 하위 쿼리를 실행합니다.
- 시간 및 그룹 태그를 기준으로 각 하위 쿼리 결과를 정렬합니다.
- 각 시점에 대해 표현식을 계산합니다.
- 계산 결과를 반환합니다.
사용 사례¶
- 여러 메트릭 또는 서로 다른 데이터 소스의 비율 계산(예: 오류율, 메모리 사용률)
- 여러 메저먼트(예:
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절이 있으면 내부 쿼리를 괄호(...)로 감싸야 합니다):동시에 Select 절에서도
fill(avg(usage_total), 0)쿼리 내 표기를 지원합니다:
구문(외부 함수):
매개변수:
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¶
현재 타임스탬프(밀리초)를 반환합니다.
구문:
예시:
// 최근 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과 동일).
구문:
예시:
Show 함수¶
Show 함수는 메타데이터(예: measurement, tag, field, 카디널리티 및 시리즈 수)를 조회하는 데 사용하며, 모델링 문제 해결과 쿼리 전 탐색에 자주 사용합니다.
일반 구문¶
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>_sourceshow_<namespace>_classshow_<namespace>_typeshow_<namespace>_fieldshow_<namespace>_labelshow_<namespace>_index
여기서 <namespace>는 함수 이름 중간 세그먼트에서 자동으로 매핑됩니다. 예:
show_logging_source->Lshow_tracing_field->Tshow_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 | 다중 쿼리 표현식 계산 |