DQL¶
DQL(Debug Query Language)은 Guance 플랫폼의 핵심 쿼리 언어로, 시계열 데이터, 로그 데이터, 이벤트 데이터 등을 효율적으로 쿼리하고 분석하기 위해 설계되었습니다. DQL은 SQL의 의미 표현과 PromQL의 구문 구조를 결합하여 사용자에게 유연하고 강력한 쿼리 도구를 제공하는 것을 목표로 합니다.
이 문서는 DQL의 기본 구문과 설계 사상을 빠르게 이해하고, 예시를 통해 DQL 쿼리를 작성하는 방법을 보여줍니다.
기본 쿼리 구조¶
DQL의 기본 쿼리 구조는 다음과 같습니다:
namespace[index]::datasource[:select-clause] [{where-clause}] [time-expr] [group-by-clause] [having-clause] [order-by-clause] [limit-clause] [sorder-by-clause] [slimit-clause] [soffset-clause]
여기서 index는 생략할 수 있으며, 생략하면 기본적으로 default 인덱스를 사용합니다.
데이터 소스를 생략할 때는 괄호를 사용하여 projections를 직접 지정할 수 있습니다:
예:
괄호가 없으면 :: 뒤의 표현식은 여전히 데이터 소스를 나타냅니다(참고: 메트릭 쿼리 M은 기본 전체 필드 *를 지원하지 않으므로 필드를 명시적으로 지정해야 합니다. 로그 L 등 비메트릭 네임스페이스는 필드를 생략하면 기본적으로 전체 필드 *를 반환합니다):
따라서 M::(cpu)는 필드 cpu를 선택하는 것을 의미하며, 더 이상 데이터 소스 cpu를 의미하지 않습니다.
괄호 형식의 데이터 소스에 필드를 명시적으로 지정해야 하는 경우 L::(nginx):(*) 또는 M::(cpu):(usage_total)와 같이 작성하십시오.
파생 테이블을 데이터 소스로 사용할 때도 명시적 projection 구분자를 사용합니다:
여기서 외부 (...)는 서브쿼리 데이터 소스이고, 바로 뒤의 :(...)는 외부 projections입니다.
실행 순서¶
DQL 쿼리의 실행 순서는 매우 중요하며, 쿼리의 의미와 성능을 결정합니다.
-
데이터 필터링:
namespace::datasource,where-clause,time-expr에 따라 데이터를 필터링합니다- 데이터 소스와 인덱스 결정
WHERE조건을 적용하여 원시 데이터 행 필터링- 시간 범위 필터 적용
- 이 단계에서 가능한 한 일찍 데이터를 필터링하여 후속 처리 효율 향상
-
시간 전처리(Rollup):
time-expr에 Rollup이 포함된 경우 각 원시 시계열에 대해 먼저 Rollup을 수행합니다- Rollup 함수는 시간 차원에서 단일 원시 타임라인을 전처리합니다
- Counter 유형 메트릭의 경우 일반적으로 원시 누적 값을 직접 사용하지 않고 속도(
rate) 또는 증가량(increase)을 계산합니다 - Gauge 유형 메트릭의 경우
last,avg등의 함수를 사용할 수 있습니다
-
그룹 집계:
group-by-clause그룹화를 수행하고, 그룹 내에서select-clause의 집계 함수를 실행합니다BY절의 표현식에 따라 데이터를 그룹화합니다- 각 그룹 내에서 집계 함수(
sum,count,avg,max,min등)를 계산합니다 - 시간 윈도우 간격(예:
[1h::5m])을 함께 지정하면 "그룹 × 시간 버킷"의 2차원 데이터 구조가 형성됩니다
-
그룹 필터링:
having-clause를 실행하여 집계된 결과를 필터링합니다HAVING절은 집계된 결과(또는 시간 버킷)에 적용됩니다- 집계 함수의 별칭 또는 결과를 사용하여 필터링할 수 있습니다
- 이는
WHERE절(원시 행 필터링)과의 핵심 차이입니다
-
스칼라 및 후처리 계산:
select-clause의 스칼라 변환 함수 또는 집계 산술 표현식을 실행합니다- 집계 결과에 대해 추가 계산을 수행합니다(예:
round(avg(usage_total), 2),(avg(used) / avg(total)) * 100)
- 집계 결과에 대해 추가 계산을 수행합니다(예:
-
그룹 간 정렬 및 페이지네이션:
sorder-by-clause,slimit-clause,soffset-clause를 실행하여 그룹(Series)을 정렬 및 페이지네이션합니다SORDER BY는 그룹 자체를 정렬합니다(단일 윈도우는 전체 구간 집계값 기준, 간격이 있는 다중 시점은 최신 시간 버킷 값 기준)SLIMIT/SOFFSET는 반환되는 그룹 수와 그룹 오프셋을 제한합니다
-
그룹 내 정렬 및 페이지네이션:
order-by-clause,limit-clause,offset-clause를 실행하여 각 그룹 내부의 데이터 행을 정렬 및 페이지네이션합니다ORDER BY는 선택된 각 그룹 내부에서 독립적으로 실행됩니다LIMIT/OFFSET는 각 그룹에서 반환되는 데이터 행 수와 행 오프셋을 제한합니다
전체 예시¶
DataKit 기본 수집 cpu 메저먼트를 사용하여 전체 예시를 통해 DQL 구조를 이해해 보겠습니다:
M::cpu:(avg(usage_total) AS avg_usage, max(usage_total) AS max_usage) {host =~ '.*', usage_total > 10} [1h::5m] BY host HAVING avg_usage > 20 ORDER BY time DESC LIMIT 12 SORDER BY avg_usage DESC SLIMIT 10
이 쿼리의 의미는 다음과 같습니다:
- 데이터 전제: 호스트 CPU 수집기가 활성화되어 있어야 합니다(메저먼트
cpu, 필드usage_total및 태그host포함) - 네임스페이스:
M(메트릭 데이터) - 인덱스: 생략 시 기본적으로
default인덱스 사용 - 데이터 소스:
cpu - 선택 필드:
usage_total필드의 평균값(별칭avg_usage) 및 최대값(별칭max_usage) - 필터 조건: 호스트 이름과 일치하고 원시 샘플 CPU 총 사용률이 10%보다 큼
- 시간 범위: 지난 1시간, 5분 간격으로 집계
- 그룹화: 호스트 이름
host기준 - 그룹 필터링: 윈도우 내 평균 CPU 사용률이 20%보다 큰 시간 버킷 필터링
- 그룹 내 정렬 및 페이지네이션: 각 호스트 그룹 내에서 시간 내림차순 정렬, 그룹당 최대 12개 시점 반환
- 그룹 간 정렬 및 페이지네이션: 최신 시간 버킷의
avg_usage내림차순 정렬, 최대 상위 10개 호스트 반환
네임스페이스(namespace)¶
네임스페이스는 서로 다른 유형의 데이터를 구분하는 데 사용되며, 각 데이터 유형에는 특정 쿼리 방식과 저장 정책이 있습니다. DQL은 다양한 비즈니스 데이터 유형 조회를 지원합니다:
| 네임스페이스 | 설명 | 일반적인 용도 |
|---|---|---|
| M | Metric, 시계열 메트릭 데이터 | CPU 사용률, 메모리 사용량, 요청 수 등 |
| L | Logging, 로그 데이터 | 애플리케이션 로그, 시스템 로그, 오류 로그 등 |
| O | Object, 인프라스트럭처 오브젝트 데이터 | 서버 정보, 컨테이너 정보, 네트워크 장비 등 |
| OH | History object, 오브젝트 이력 데이터 | 서버 구성 변경 이력, 성능 메트릭 이력 등 |
| CO | Custom object, 사용자 정의 오브젝트 데이터 | 비즈니스 사용자 정의 오브젝트 정보 |
| COH | History custom object, 사용자 정의 오브젝트 이력 데이터 | 사용자 정의 오브젝트의 이력 변경 기록 |
| N | Network, 네트워크 데이터 | 네트워크 트래픽, DNS 쿼리, HTTP 요청 등 |
| T | Trace, 트레이스 호출 데이터 | 분산 추적, 호출 체인 분석 등 |
| P | Profile, 호출 프로파일링 데이터 | 성능 프로파일링, CPU 플레임 그래프 등 |
| R | RUM, 사용자 방문 데이터 | 프론트엔드 성능, 사용자 행동 분석 등 |
| E | Event, 이벤트 데이터 | 알림 이벤트, 배포 이벤트, 시스템 이벤트 등 |
| UE | Unrecovered Event, 미복구 이벤트 데이터 | 미해결 알림 및 이벤트 |
| B | Cloud billing, 클라우드 청구 | 클라우드 서비스 비용 및 청구 분석 |
플랫폼 기본 데이터 소스 및 공통 필드 빠른 조회¶
워크스페이스에서 DataKit 기본 수집을 활성화하면 다음 내장 데이터 소스와 공통 필드를 추가 구성 없이 바로 복사하여 쿼리를 실행할 수 있습니다:
| 네임스페이스 | 일반 기본 데이터 소스(source / measurement) |
일반 표준 필드 / 태그 |
|---|---|---|
M(메트릭) |
cpu, mem, disk, diskio, net, system |
cpu: usage_total, usage_user, usage_system, usage_idle, usage_iowaitmem: used_percent, available_percent, used, total, availabledisk: used_percent, free, used, total, inodes_used_percent(태그: device, fstype)net: bytes_recv, bytes_sent, packets_recv, packets_sent, err_in, err_out(태그: interface)system: load1, load5, load15, load1_per_core, n_cpus, uptime공통 태그: host |
L(로그) |
*(전체 로그), nginx, system 등 |
message(로그 본문), status(로그 레벨: error/warn/info 등), service, source, host, pod_name, container_name, filepath |
O(오브젝트) |
HOST, docker_containers, kubelet_pod, host_processes |
HOST: host, name, state, os, arch, cpu_usage, mem_used_percent, disk_used_percent, load, cloud_provider, last_update_time |
T(트레이스) |
*(전체 서비스) 또는 구체적인 service 이름 |
service, resource, operation, duration(소요 시간, 일반적으로 나노초 또는 마이크로초), status(ok/error), span_type(entry/local/exit), trace_id, span_id, parent_id, http_status_code, http_method, env |
R(RUM) |
view, resource, error, action, long_task, session |
app_id, env, version, view_path, loading_time, lcp, fcp, fid, cls, error_message, error_type, browser, os, country, city, userid |
E / UE(이벤트) |
monitor, system, custom_event |
df_title, df_message, df_status(critical/error/warning/info/ok), df_event_id, df_monitor_checker_name, df_dimension_tags |
워크스페이스에 어떤 데이터 소스나 필드가 있는지 확실하지 않습니까? 다음 메타데이터 탐색 문을 직접 복사하여 실행할 수 있습니다(자세한 내용은 Show 함수 참조 참고): - 모든 메저먼트 조회:
show_measurement()-cpu메저먼트의 모든 필드 조회:show_field_key(from=['cpu'])- 로그 데이터 소스 목록과 필드 조회:show_source(namespace='L'),show_field(namespace='L')- 인프라스트럭처 오브젝트 분류 조회:show_source(namespace='O')
인덱스(index)¶
인덱스는 DQL 쿼리 최적화의 중요한 메커니즘으로, 기존 데이터베이스의 테이블 또는 파티션으로 이해할 수 있습니다. 단일 네임스페이스에서 시스템은 데이터 소스, 데이터 양, 액세스 패턴 등의 요인으로 데이터를 분할하여 쿼리 성능과 관리 효율을 향상시킬 수 있습니다.
인덱스의 역할¶
- 성능 최적화: 인덱스를 통해 데이터를 분산 저장하여 단일 쿼리의 데이터 스캔 양을 줄입니다
- 데이터 격리: 서로 다른 비즈니스, 환경 또는 시간 범위의 데이터를 서로 다른 인덱스에 저장할 수 있습니다
- 권한 관리: 서로 다른 인덱스에 서로 다른 액세스 권한을 설정할 수 있습니다
- 수명 주기 관리: 서로 다른 인덱스에 서로 다른 데이터 보존 정책을 설정할 수 있습니다
인덱스 명명 규칙¶
- 인덱스 이름은 명시적으로 선언할 수 있으며, 명시적으로 선언하지 않으면 기본적으로
default를 사용합니다 - 인덱스 이름을 명시적으로 선언할 때 와일드카드 또는 정규식을 사용한 일치는 지원되지 않습니다(로그 등은
L("*")로 모든 인덱스를 조회할 수 있습니다) - 인덱스 이름은 일반적으로 데이터의 비즈니스 속성을 반영합니다. 예:
default,production,staging,web-logs
기본 구문¶
// 기본 인덱스 사용(지정하지 않으면 자동으로 default 사용)
M::cpu:(avg(usage_total)) [1h] // M("default")::cpu:(avg(usage_total)) [1h]와 동일
L::*:(count(*)) [1h] // L("default")::*:(count(*)) [1h]와 동일
// 단일 인덱스 지정
M("default")::cpu:(avg(usage_total)) [1h] // default 인덱스의 CPU 메트릭 조회
L("default")::*:(count(*)) [1h] // default 인덱스의 로그 조회
// 다중 인덱스 쿼리(여러 인덱스의 데이터를 동시에 조회)
L("default", "web-logs")::*:(count(*)) [1h] // 여러 로그 인덱스를 동시에 조회
인덱스와 성능¶
인덱스를 합리적으로 사용하면 쿼리 성능을 크게 향상시킬 수 있습니다:
- 정확한 인덱스: 데이터가 어느 인덱스에 있는지 명확히 알 때 해당 인덱스를 직접 지정합니다
- 다중 인덱스 쿼리: 여러 인덱스에 걸쳐 쿼리해야 할 때 전체 스캔 대신 다중 인덱스 구문을 사용합니다
- 전체 인덱스 스캔 방지: 인덱스와 WHERE 조건의 조합을 통해 데이터 스캔 범위를 줄이도록 합니다
호환 구문(권장하지 않음)¶
역사적인 이유로 DQL은 where 절에서 인덱스를 지정하는 것도 지원하지만 권장하지 않습니다:
// 이전 구문, 권장하지 않음
L::*:(count(*)) { index = "default" } [1h]
L::*:(count(*)) { index IN ["default", "web-logs"] } [1h]
사용 예시¶
// 기본 인덱스에서 각 호스트의 평균 CPU 사용률 조회
M::cpu:(avg(usage_total)) [1h] BY host
// 기본 인덱스에서 로그 상태별 로그 수 조회
L("default")::*:(count(*)) [1h] BY status
// 여러 인덱스의 오류 로그 수 비교
L("default", "web-logs")::*:(count(*)) {status = 'error'} [1h] BY index
데이터 소스(datasource)¶
데이터 소스는 쿼리의 구체적인 데이터 출처를 지정하며, 데이터 세트 이름, 와일드카드 패턴, 정규식 또는 서브쿼리일 수 있습니다.
기본 데이터 소스¶
네임스페이스마다 데이터 소스 정의가 다릅니다:
| 네임스페이스 | 데이터 소스 유형 | 예시 |
|---|---|---|
| M | 메저먼트(measurement) | cpu, mem, disk, net, system |
| L | 데이터 소스(source) | *, nginx, system, redis |
| O | 인프라스트럭처 오브젝트 분류 | HOST, docker_containers, kubelet_pod |
| T | 서비스 이름(service) | *, `user-service`, `order-service` |
| R | RUM 데이터 유형 | session, view, resource, error, action, long_task |
데이터 소스 구문¶
참고: 데이터 소스 이름에 하이픈
-또는 기타 특수 문자(예:user-service)가 포함된 경우 반드시 백틱으로 감싸야 합니다(예:T::`user-service`:(count(*))). 그렇지 않으면-가 뺄셈 연산자로 해석됩니다.
데이터 소스 이름 지정¶
M::cpu:(avg(usage_total)) [1h] // cpu 메저먼트 조회
L::nginx:(count(*)) [1h] // nginx 로그 데이터 소스 조회
O::HOST:(host, cpu_usage, mem_used_percent) // HOST 호스트 오브젝트 조회
T::`user-service`:(count(*)) [1h] // 하이픈이 포함된 서비스 이름 조회(백틱으로 감쌈)
R::view:(count(*)) [1h] // RUM 페이지 조회(view) 데이터 조회
와일드카드 일치¶
L::*:(count(*)) [1h] BY source // 모든 로그 데이터 소스를 조회하고 source 기준으로 집계
T::*:(count(*)) [1h] BY service // 모든 APM 서비스를 조회하고 service 기준으로 집계
정규식 일치¶
M::re('cpu|mem'):(avg(usage_total), avg(used_percent)) [1h] // 정규식과 일치하는 메저먼트 조회
L::re('nginx.*'):(count(*)) [1h] // nginx로 시작하는 로그 소스 조회
T::re('.*-service'):(count(*)) [1h] BY service // -service로 끝나는 서비스 조회
서브쿼리 데이터 소스¶
서브쿼리는 DQL에서 복잡한 분석을 구현하는 중요한 기능으로, 하나의 쿼리 결과를 다른 쿼리의 데이터 소스로 사용할 수 있습니다. 이러한 중첩 쿼리 메커니즘은 다중 계층 분석 요구를 지원합니다.
실행 메커니즘¶
서브쿼리 실행은 다음 원칙을 따릅니다:
- 직렬 실행: 내부 서브쿼리가 먼저 실행되고, 완료되면 그 결과를 외부 쿼리의 데이터 소스로 사용합니다
- 결과 캡슐화: 서브쿼리 결과는 임시 테이블 구조로 캡슐화되어 외부 쿼리에서 사용됩니다
- 네임스페이스 혼합: 서브쿼리는 서로 다른 네임스페이스의 혼합 쿼리를 지원하여 데이터 유형 간 분석을 구현합니다
- 성능 고려: 서브쿼리는 계산 복잡성을 증가시키므로 쿼리 로직을 합리적으로 설계해야 합니다
기본 구문¶
실행 과정¶
최근 1시간 동안 오류 로그가 발생한 고유 서비스 수를 집계하는 일반적인 서브쿼리를 예로 들면:
L::(L::*:(count(*) AS err_cnt) {status = 'error'} [1h] BY service):(count(service) AS affected_services) [1h]
실행 과정은 다음과 같습니다:
-
내부 서브쿼리:
L::*:(count(*) AS err_cnt) {status = 'error'} [1h] BY service- 최근 1시간의 로그 데이터 스캔
status = 'error'인 오류 로그 필터링service별로 오류 수 집계- 임시 테이블 생성:
service | err_cnt
-
외부 쿼리:
L::(...):(count(service) AS affected_services) [1h]- 서브쿼리 결과를 데이터 소스로 사용
- 서로 다른
service그룹 수 집계 - 최종 결과: 오류 로그가 발생한 서비스 총 수
사용 예시¶
// 최근 1시간 동안 오류 로그가 있는 서비스 수 집계
L::(L::*:(count(*) AS err_cnt) {status = 'error'} [1h] BY service):(count(service) AS affected_services) [1h]
// 평균 CPU 사용률이 80%를 초과하는 고부하 호스트 수 집계(참고: 집계 결과 필터링에는 HAVING 사용)
M::(M::cpu:(avg(usage_total) AS avg_cpu) [1h] BY host HAVING avg_cpu > 80):(count(host) AS high_load_hosts) [1h]
// 먼저 호스트별로 5분 단위 피크 CPU를 계산한 후, 모든 호스트 피크의 평균 수준 계산
M::(M::cpu:(max(usage_total) AS peak_cpu) [1h::5m] BY host):(avg(peak_cpu) AS cluster_avg_peak) [1h::5m]
Select 절(select-clause)¶
Select 절은 쿼리에서 반환할 필드 또는 표현식을 지정하며, DQL 쿼리에서 가장 기본적이고 중요한 부분 중 하나입니다.
필드 선택¶
기본 구문¶
// 단일 메트릭 필드 선택(집계 또는 상세 시간 윈도우와 함께 사용)
M::cpu:(usage_total) [1h]
// 여러 메트릭 필드 선택
M::cpu:(usage_total, usage_system, usage_user) [1h]
// 비메트릭 네임스페이스의 모든 필드 선택(참고: M 메트릭 네임스페이스는 * 와일드카드 필드를 지원하지 않으므로 필드 이름을 명시적으로 나열해야 합니다)
L::*:(*) [15m] LIMIT 10
O::HOST:(*) LIMIT 10
필드 이름 규칙¶
필드 이름은 다음과 같은 작성 형식이 있습니다:
-
이름을 직접 작성: 영문자, 숫자, 밑줄
_, 점.또는@만 포함하는 일반 식별자에 적용- ✅
message - ✅
usage_total - ✅
df_status
- ✅
-
백틱(
`)으로 감싸기: 하이픈-, 슬래시/, 공백이 포함되거나 키워드와 같은 이름의 필드에 적용- ✅
`bytes_recv/sec` - ✅
`limit` - ✅
`host-name` - ✅
`column with spaces`
- ✅
-
피해야 할 작성법: 작은따옴표와 큰따옴표로 감싸는 것은 문자열 리터럴이며 필드 이름이 아닙니다
- ❌
'message' - ❌
"message"
- ❌
JSON 필드 추출¶
데이터 필드에 JSON 형식 콘텐츠가 포함된 경우 JSON Path 구문 하위 집합을 사용하여 내부 필드 데이터를 추출할 수 있습니다.
기본 구문¶
JSON Path 구문¶
- 점으로 객체 속성 가져오기:
.field_name - 대괄호로 객체 속성 가져오기:
["key"](공백 또는 특수 문자가 포함된 키에 적용) - 배열 인덱스로 값 가져오기:
[index]
사용 예시¶
다음과 같은 JSON 로그 데이터가 있다고 가정합니다:
{
"message": "User login attempt",
"request": {
"method": "POST",
"path": "/api/login",
"headers": {
"user-agent": "Mozilla/5.0",
"content-type": "application/json"
},
"body": {
"username": "john.doe",
"password": "***",
"permissions": ["read", "write", "admin"]
}
},
"response": {
"status": 200,
"time": 156,
"data": [
{"id": 1, "name": "user1"},
{"id": 2, "name": "user2"}
]
}
}
// 요청 메서드 추출
L::auth_logs:(message@request.method)
// 요청 경로 추출
L::auth_logs:(message@request.path)
// 사용자 이름 추출
L::auth_logs:(message@request.body.username)
// 응답 상태 추출
L::auth_logs:(message@response.status)
// User-Agent 추출(하이픈 포함, 대괄호 필요)
L::auth_logs:(message@request.headers["user-agent"])
// 권한 배열 첫 번째 요소 추출
L::auth_logs:(message@request.body.permissions[0])
// 응답 데이터 첫 번째 객체의 name 추출
L::auth_logs:(message@response.data[0].name)
// 서로 다른 요청 메서드 수 집계
L::auth_logs:(count(*)) [1h] BY message@request.method
// 응답 시간 분포 분석
L::auth_logs:(avg(message@response.time), max(message@response.time)) [1h] BY message@request.method
// 여러 필드 추출
L::auth_logs:(
message,
message@request.method as method,
message@request.path as path,
message@response.status as status,
message@response.time as response_time
) {message@response.status >= 400} [1h]
계산 필드¶
표현식 계산¶
기본 산술 연산을 지원합니다. 참고: BY 그룹화 또는 시간 윈도우 간격이 포함된 집계 쿼리에서 산술 연산의 피연산자는 반드시 집계 함수로 명시적으로 감싸야 합니다(예: (avg(used) / avg(total)) * 100). 비집계 상세 쿼리에서만 원시 필드에 직접 산술 연산을 수행할 수 있습니다.
// 상세 쿼리: 단위 변환(나노초를 밀리초로)
T::*:(service, resource, duration / 1000000 AS duration_ms) [15m] LIMIT 10
// 집계 쿼리: 메모리 사용률 계산(피연산자를 집계 함수로 감싸야 함)
M::mem:((avg(used) / avg(total)) * 100 AS usage_percentage) [1h] BY host
// 집계 쿼리: 네트워크 카드 총 처리량 계산(바이트를 MB로 변환)
M::net:((max(bytes_recv) + max(bytes_sent)) / 1024 / 1024 AS total_traffic_mb) [1h] BY host
함수 계산¶
다양한 집계 및 변환 함수를 지원합니다:
// 집계 함수: CPU 사용률의 최대값, 최소값, 평균값을 동시에 조회
M::cpu:(max(usage_total), min(usage_total), avg(usage_total)) [1h] BY host
// 변환 함수: 메트릭 평균값 반올림
M::cpu:(round(avg(usage_total), 2) AS avg_cpu_pct) [1h] BY host
조건 표현식¶
CASE WHEN은 쿼리에서 조건에 따라 서로 다른 값을 선택하는 데 사용됩니다. 일반적으로 집계 함수와 함께 사용하여 조건부 집계, 조건부 합계 또는 조건에 따른 필드 정규화를 수행합니다.
기본 구문¶
간단한 CASE 구문을 사용하여 동일한 필드에 대해 다중 값 매칭을 수행할 수도 있습니다:
WHEN은 작성 순서대로 차례로 일치하며, 첫 번째 조건이 일치하면 해당 THEN 값을 반환합니다. 모두 일치하지 않으면 ELSE 값을 반환합니다. ELSE를 명시적으로 작성하지 않으면 기본적으로 nil을 반환합니다.
사용 예시¶
조건부 집계: 오류 로그 수와 전체 로그 수 집계
L::*:(
count(*) AS total_logs,
count(CASE WHEN status = 'error' THEN 1 ELSE nil END) AS error_logs
) [1h] BY service
참고:
count(expr)은nil이 아닌 값을 집계합니다.0도nil이 아니므로count(CASE WHEN condition THEN 1 ELSE 0 END)는 조건에 일치하는 행만이 아니라 모든 행을 집계합니다. 조건부 집계를 수행할 때는ELSE nil을 사용하거나sum(CASE WHEN condition THEN 1 ELSE 0 END)를 사용하는 것이 좋습니다.
조건부 합계: 느린 요청(소요 시간 > 1초)의 총 소요 시간만 집계
T::*:(
sum(CASE WHEN duration > 1000000000 THEN duration ELSE 0 END) AS slow_duration_ns
) [1h] BY service
다중 분기 분류: 로그 레벨에 따라 심각도 등급 생성
L::*:(
max(CASE
WHEN status = 'critical' THEN 3
WHEN status = 'error' THEN 2
WHEN status = 'warn' THEN 1
ELSE 0
END) AS max_severity
) [1h] BY service
필드 정제 후 판단: 대소문자를 무시하고 오류 로그 집계
유형 변환 후 집계: 필드가 문자열일 때 숫자로 변환하여 합계에 참여
L::nginx:(
sum(CASE WHEN status = 'error' THEN int(message_length) ELSE 0 END) AS error_msg_bytes
) [1h] BY host
지원 범위¶
CASE WHEN은 현재 제한된 행 수준 조건 표현식이며, 고성능 푸시다운 실행을 지원하는 것이 설계 목표입니다. sum(CASE ...), count(CASE ...), max(CASE ...)와 같이 집계 함수 내부에 배치할 수 있습니다.
CASE 내부에서 지원하는 항목:
- 필드
- 리터럴 및
nil - 부울 조건(
=,!=,>,>=,<,<=,AND,OR;IN은 지원하지 않으며, 다중 값 일치는OR또는 간단한CASE field WHEN ...구문 사용) - 다음 스칼라 함수:
bool,int,uint,float,string,md5,lower,upper,trim,ltrim,rtrim,length,regexp_replace
CASE 내부에서 집계 함수를 사용하는 것은 지원하지 않습니다. 집계 함수는 CASE 외부에 있어야 합니다:
// 권장: 먼저 행별로 CASE를 계산한 후 집계
L::*:(
sum(CASE WHEN status = 'error' THEN 1 ELSE 0 END) AS error_count
) [1h] BY host
// 지원하지 않음(오류 발생): CASE 내부에 집계 함수를 직접 포함할 수 없음
L::*:(
CASE WHEN count(*) > 0 THEN "has_logs" ELSE "empty" END
) [1h] BY host
또한 CASE 내부에서 지원 범위에 포함되지 않은 복잡한 스칼라 함수(예: regexp_extract)를 사용하는 것도 지원하지 않습니다. 다른 복잡한 처리가 필요한 경우 쿼리 조건, 필드 정제 또는 서브쿼리를 통해 로직을 분리하여 CASE에서 대규모 상세 스캔이 트리거되지 않도록 하는 것이 좋습니다.
별칭¶
필드 또는 표현식에 별칭을 지정하면 결과를 더 읽기 쉽게 만들고 후속 참조에 편리합니다.
기본 구문¶
사용 예시¶
// 간단한 별칭
M::cpu:(avg(usage_total) AS avg_usage, max(usage_total) AS max_usage) [1h] BY host
// 집계 산술 표현식 별칭
M::mem:((avg(used) / avg(total)) * 100 AS usage_percent) [1h] BY host
// 함수 별칭
L::*:(count(*) AS error_count) {status = 'error'} [1h] BY service
// JSON 추출 별칭
L::*:(
message@request.method AS http_method,
message@response.status AS http_status,
message@response.time AS response_time_ms
) [15m] LIMIT 20
사용 팁¶
DQL에서는 단일 집계 함수의 결과를 원래 필드 이름으로 직접 참조할 수 있으므로 별칭 사용이 줄어듭니다:
M::cpu:(max(usage_total)) [1h] BY host
// 서브쿼리 결과에 max(usage_total) 열이 포함되어 있으므로 외부에서 usage_total로 해당 열을 직접 참조할 수 있습니다:
M::(M::cpu:(max(usage_total)) [1h] BY host):(max(usage_total)) { usage_total > 80 } [1h]
하지만 여러 집계 함수가 동일한 필드를 사용하는 경우 후속 단계에서 올바르게 구분하려면 반드시 별칭을 사용해야 합니다:
// 별칭을 반드시 사용해야 하는 경우
M::cpu:(max(usage_total) AS max_usage, min(usage_total) AS min_usage) [1h] BY host
시간 절(time-clause)¶
시간 절은 DQL의 핵심 기능 중 하나로, 쿼리의 시간 구간, 집계 시간 윈도우 및 Rollup 집계 함수를 지정합니다.
사용 팁: 콘솔의 "빠른 쿼리", 대시보드 차트 또는 쿼리 API를 호출할 때 쿼리의 시작/종료 시간(
start_time/end_time)은 일반적으로 화면 오른쪽 상단의 시간 선택기 또는 API 요청 파라미터를 통해 일괄 전달됩니다. 이때 DQL에서는 집계 간격 또는 Rollup만 지정하면 되며(예:[::5m],[::1m:rate]),[1h]를 하드코딩할 필요가 없습니다. 이렇게 하면 동일한 DQL이 페이지 시간 선택기에 따라 시간 범위를 동적으로 전환할 수 있습니다. 고정 쿼리 윈도우가 필요하거나 서로 다른 윈도우를 비교해야 할 때만 DQL에 시작/종료 시간을 명시적으로 작성합니다(예:[1h::5m]).
기본 구문¶
시간 범위¶
절대 타임스탬프¶
상대 시간¶
다양한 기간 단위를 지원하며 혼합하여 사용할 수 있습니다:
[1h] // 지난 1시간부터 현재까지
[1h:5m] // 지난 1시간부터 지난 5분까지
[1h30m] // 지난 1시간 30분
[2h15m30s] // 지난 2시간 15분 30초
기간 표현식 설명¶
| 단위 | 설명 | 예시 |
|---|---|---|
| s | 초 | 30s |
| m | 분 | 5m |
| h | 시간 | 2h |
| d | 일 | 7d |
| w | 주 | 4w |
| y | 년 | 1y |
기간 표현식은 시간 절에 사용될 때 현재 시간부터 이전으로의 오프셋을 나타내며, Select 절 또는 Where 절 등에 사용될 때는 밀리초 정수로 간주되어 계산에 참여합니다.
집계 쿼리에 사용할 때는 두 가지 기간 단위를 추가로 지원합니다:
| 단위 | 설명 | 예시 |
|---|---|---|
| i, is | 집계 시간 윈도우의 배수, 반환값은 부동 소수점 초 | 1i, 1is |
| ims | 집계 시간 윈도우의 배수, 반환값은 정수 밀리초 | 1ims |
O::HOST:(count(*)) { `last_update_time` > (now() - 10m) } // 10m은 600,000밀리초 정수로 간주되어 계산에 참여
L::*:(count(*) / 1i AS log_qps) [1h::1m] // 시간 윈도우 간격(1m = 60s)으로 나누어 로그 쓰기 QPS 계산
사전 설정 시간 범위¶
자주 사용하는 시간 범위 키워드를 제공합니다:
| 키워드 | 설명 | 시간 범위 |
|---|---|---|
| TODAY | 오늘 | 오늘 0시부터 현재까지 |
| YESTERDAY | 어제 | 어제 0시부터 오늘 0시까지 |
| THIS WEEK | 이번 주 | 이번 주 월요일 0시부터 현재까지 |
| LAST WEEK | 지난주 | 지난주 월요일 0시부터 이번 주 월요일 0시까지 |
| THIS MONTH | 이번 달 | 이번 달 1일 0시부터 현재까지 |
| LAST MONTH | 지난달 | 지난달 1일 0시부터 이번 달 1일 0시까지 |
[TODAY] // 오늘 데이터
[YESTERDAY] // 어제 데이터
[THIS WEEK] // 이번 주 데이터
[LAST WEEK] // 지난주 데이터
[THIS MONTH] // 이번 달 데이터
[LAST MONTH] // 지난달 데이터
시간 범위 키워드를 사용할 때는 워크스페이스의 시간대 설정이 올바른지 확인해야 하며, 사용자 요청의 시간대에 따라 엄격하게 변환해야 합니다.
시간 윈도우 집계¶
시간 윈도우는 데이터를 지정된 시간 간격으로 그룹화하여 집계하며, 반환 결과의 time 열은 각 시간 윈도우의 시작 시간을 나타냅니다.
단일 시간 윈도우¶
전체 시간 범위를 하나의 값으로 집계합니다:
쿼리 결과:
시간 윈도우 집계¶
시간 간격으로 그룹화하여 집계합니다:
쿼리 결과:
{
"columns": ["time", "max(usage_total)"],
"values": [
[1721059200000, 37.46],
[1721058600000, 34.12],
[1721058000000, 33.81],
[1721057400000, 30.92],
[1721056800000, 34.53],
[1721056200000, 36.11]
]
}
Rollup 함수¶
Rollup 함수는 DQL에서 중요한 전처리 단계로, 그룹 집계보다 먼저 실행되어 원시 시계열 데이터를 전처리합니다.
실행 시점¶
쿼리 실행 흐름에서 Rollup의 위치:
실행 메커니즘¶
Rollup 실행 과정은 두 단계로 나뉩니다:
- 타임라인별 처리: 각 독립 시계열에 Rollup 함수를 개별 적용합니다
- 집계 계산: Rollup 처리된 결과에서 그룹 집계를 수행합니다
Rollup 축약, Rollup 함수 호출 및 명시적 집계 호출¶
DQL에는 혼동하기 쉬운 세 가지 시계열 함수 작성 방식이 있습니다:
- Rollup 축약: 시간 절에 함수 이름만 작성합니다. 예:
[rate],[1h::5m:slope]. - Rollup 함수 호출: 시간 절에서 Rollup 함수에 알고리즘 파라미터를 전달합니다. 예:
[1h::1m:ewma(0.3)],[1h::1m:moving_average(5)],[1h::1m:percentile(95)]. - 명시적 집계 호출: Select 절에 완전한 함수 호출을 작성합니다. 예:
rate(bytes_recv),ewma(usage_total, 0.3),corr(usage_user, usage_system).
세 가지 작성 방식의 주요 차이는 실행 단계와 파라미터 기능입니다:
| 작성 방식 | 예시 | 실행 단계 | 적용 시나리오 |
|---|---|---|---|
| Rollup 축약 | [1h::5m:rate] |
그룹 집계 전, 각 원시 타임라인에서 실행 | 먼저 각 타임라인을 전처리한 후 그룹 집계 수행 |
| Rollup 함수 호출 | [1h::1m:ewma(0.3)] |
그룹 집계 전, 각 원시 타임라인에서 실행 | Rollup 함수에 추가 알고리즘 파라미터가 필요한 경우 |
| 명시적 집계 호출 | ewma(usage_total, 0.3) |
Select 절 집계 단계 | 필드, 추가 파라미터 또는 여러 입력 필드를 지정해야 하는 경우 |
시간 절의 Rollup 입력 필드는 Select 필드, 시간 윈도우 및 원시 타임라인에 의해 결정되므로, Rollup 함수 호출은 추가 알고리즘 파라미터만 전달하고 시간 절에는 필드 이름을 전달하지 않습니다. 단일 입력, 추가 파라미터가 없는 시계열 함수는 일반적으로 Rollup 축약을 지원할 수 있습니다. 추가 알고리즘 파라미터가 필요한 단일 입력 함수는 Rollup 함수 호출을 지원할 수 있습니다. 여러 입력 필드가 필요한 함수는 명시적 집계 호출을 사용해야 합니다.
예시: Counter 메트릭을 먼저 Rollup한 후 집계
Counter 메트릭(예: 누적 네트워크 카드 수신 바이트 bytes_recv)은 먼저 각 원시 타임라인에서 초당 증가율을 계산한 후 호스트 차원으로 합산해야 합니다:
// 권장: 먼저 각 네트워크 카드 타임라인에서 rate(초당 속도)를 계산한 후 host별로 합산하여 전체 호스트 총 처리 속도 계산
M::net:(sum(bytes_recv)) [1h::5m:rate] BY host
// 권장하지 않음: Counter 원시 누적 값을 직접 집계하면 현재 처리 속도가 아닌 과거 누적 총량이 계산됨
M::net:(sum(bytes_recv)) [1h::5m] BY host
예시: 추가 알고리즘 파라미터가 필요할 때 Rollup 함수 호출 사용
ewma는 평활 계수 alpha를 명시적으로 전달해야 합니다. 먼저 각 원시 타임라인에 EWMA를 수행한 후 그룹 집계로 진입하려면 시간 절에 작성할 수 있습니다:
// Rollup 함수 호출: 먼저 각 타임라인에 EWMA를 수행한 후 host별 평균 계산
M::cpu:(avg(usage_total)) [1h::1m:ewma(0.3)] BY host
다음 두 가지는 일반적인 잘못된 작성법입니다:
// 잘못됨: ewma에는 alpha가 필요하므로 함수 이름만 작성할 수 없음
M::cpu:(avg(usage_total)) [1h::1m:ewma] BY host
// 잘못됨: 시간 절의 Rollup 파라미터에는 알고리즘 파라미터만 작성하고 필드 이름은 작성하지 않음
M::cpu:(avg(usage_total)) [1h::1m:ewma(usage_total, 0.3)] BY host
Select 집계 단계에서 EWMA를 계산하려면 명시적 집계 호출을 사용할 수도 있습니다:
시간 절 Rollup에 적합한 단일 숫자 파라미터 함수에는 다음도 포함됩니다:
// 먼저 각 타임라인에 5점 이동 평균을 수행한 후 host별 평균 계산
M::cpu:(avg(usage_total)) [1h::1m:moving_average(5)] BY host
// 먼저 각 타임라인에서 P95를 계산한 후 host별 평균 계산
M::cpu:(avg(usage_total)) [1h::5m:percentile(95)] BY host
예시: 여러 입력 필드가 있을 때 명시적 집계 호출 사용
corr는 두 개의 입력 필드가 필요하므로 시간 절 Rollup에 작성할 수 없습니다:
// 올바름: Select 절에서 두 필드를 명시적으로 지정(사용자 모드와 커널 모드 CPU의 상관 계수 계산)
M::cpu:(corr(usage_user, usage_system)) [1h::5m] BY host
예시: 동일한 이름의 함수가 실행 단계에 따라 다름
어떤 함수가 Rollup 축약과 명시적 집계 호출을 모두 지원하는 경우, 두 작성 방식은 서로 다른 실행 단계를 나타내므로 기본적으로 완전히 동등하다고 이해해서는 안 됩니다:
// Rollup 축약: 먼저 각 원시 타임라인에서 zscore를 계산한 후 그룹 집계로 진입
M::cpu:(max(usage_total)) [1h::5m:zscore] BY host
// 명시적 집계 호출: Select 집계 단계에서 usage_total에 zscore 계산
M::cpu:(zscore(usage_total)) [1h::5m] BY host
적용 시나리오¶
Rollup 함수의 대표적인 적용 시나리오는 Counter 메트릭 처리입니다.
Prometheus 또는 시스템에서 수집한 Counter 유형 메트릭(예: net의 bytes_recv, HTTP 요청 누적 카운트 request_count)의 경우 Counter는 단조 증가하므로 원시 값을 직접 집계하는 것은 의미가 없습니다. 먼저 각 타임라인별로 증가율을 계산한 후 집계해야 합니다.
문제 예시: 두 서버의 요청 카운터가 다음과 같다고 가정합니다:
{
"host": "web-server-01",
"data": [
{"time": "2024-07-15 08:25:00", "request_count": 150},
{"time": "2024-07-15 08:20:00", "request_count": 140},
{"time": "2024-07-15 08:15:00", "request_count": 130},
{"time": "2024-07-15 08:10:00", "request_count": 120},
{"time": "2024-07-15 08:05:00", "request_count": 110},
{"time": "2024-07-15 08:00:00", "request_count": 100}
]
}
{
"host": "web-server-02",
"data": [
{"time": "2024-07-15 08:25:00", "request_count": 250},
{"time": "2024-07-15 08:20:00", "request_count": 240},
{"time": "2024-07-15 08:15:00", "request_count": 230},
{"time": "2024-07-15 08:10:00", "request_count": 220},
{"time": "2024-07-15 08:05:00", "request_count": 210},
{"time": "2024-07-15 08:00:00", "request_count": 200}
]
}
직접 집계할 때의 문제:
- web-server-01의 request_count 시작 값은 100
- web-server-02의 request_count 시작 값은 200
- 두 서버의 요청 속도는 동일하지만(모두 5분마다 10개 요청) 절대값은 다릅니다
Rollup을 사용한 해결 방법:
실행 과정:
-
Rollup 단계(각 타임라인에서 개별 실행):
- web-server-01: rate([100, 110, 120, 130, 140, 150])
- web-server-02: rate([200, 210, 220, 230, 240, 250])
-
집계 단계:
- 각 타임라인의 속도를 합산하여 클러스터 총 요청 속도 계산
함수 유형¶
일반적인 Rollup 함수는 다음과 같습니다:
| 함수 유형 | 설명 | 적용 시나리오 |
|---|---|---|
rate |
증가율 계산 | Counter 유형 메트릭 |
increase |
증가량 계산 | Counter 유형 메트릭 |
last |
마지막 값 가져오기 | Gauge 유형 메트릭 |
avg |
평균값 계산 | 데이터 평활화 |
max |
최대값 가져오기 | 피크 분석 |
min |
최소값 가져오기 | 저점 분석 |
하지만 거의 모든 단일 값을 반환하는 집계 함수를 사용할 수 있으므로 여기서 전체 함수 목록을 나열하지는 않습니다.
기본 Rollup¶
Rollup 함수를 명시적으로 지정하지 않으면 DQL은 기본적으로 Rollup 계산을 수행하지 않습니다. PromQL의 기본 Rollup은 last이므로 Prometheus 메트릭을 계산하는 경우 이 차이를 반드시 이해하고 Rollup 함수를 수동으로 지정해야 합니다.
사용 예시¶
// 모든 호스트의 총 네트워크 수신 속도 계산(바이트/초)
M::net:(sum(bytes_recv)) [1h::5m:rate]
// 호스트별로 네트워크 수신 및 전송 속도 집계
M::net:(
sum(bytes_recv) AS recv_bps,
sum(bytes_sent) AS sent_bps
) [1h::5m:rate] BY host
시간 윈도우 유연한 구문¶
DQL은 다양한 시간 윈도우 축약 형식을 지원하여 쿼리 작성을 더 편리하게 합니다.
축약 형식¶
[1h] // 시간 범위만 지정
[1h::5m] // 시간 범위 + 집계 간격
[1h:5m] // 시작 시간 + 종료 시간
[1h:5m:1m] // 시작 + 종료 + 간격
[1h:5m:1m:avg] // 전체 형식
[::5m] // 집계 간격만 지정(시간 범위는 외부 요청에서 제공)
[:::sum] // rollup 함수만 지정
[sum] // rollup 함수만 지정(가장 간단한 형식)
시간 이동(SHIFT)¶
쿼리 수준 SHIFT는 전체 쿼리의 시간 윈도우를 duration만큼 앞으로 이동하여 해당 기간 이전의 데이터를 읽습니다. 결과의 시간 열은 여전히 현재 윈도우로 표시됩니다:
SHIFT는 두 위치에 작성할 수 있으며 효과는 동일합니다:
- 시간 윈도우 바로 뒤, 다른 절 앞:
BY,HAVING,ORDER BY등 절 끝에 작성:
규칙:
duration은 양의 고정 기간이어야 합니다. 예:1h,7d;- 각
SELECT는 쿼리 수준SHIFT를 하나만 선언할 수 있습니다; - 절 끝의
SHIFT는 절 최상위(괄호 내부가 아님)에서만 유효합니다.BY (service SHIFT 1d)의SHIFT는 여전히 표현식 수준입니다; - 필터링, 그룹화, 집계, 정렬 및 페이지네이션은 모두 이동 전 데이터를 기반으로 실행됩니다. 결과 구조는
SHIFT를 추가하지 않은 쿼리와 동일하며, 시간 열만 여전히 현재 윈도우에 속합니다.
중첩 SELECT는 각각 쿼리 수준 SHIFT를 선언할 수 있으며, 오프셋은 계층별로 누적됩니다. 쿼리 수준 SHIFT와 표현식 수준 SHIFT(DQL 함수 참조의 SHIFT 참고)는 조합할 수 있습니다. 쿼리 수준 오프셋이 먼저 전체 쿼리의 기준 윈도우를 결정하고, 표현식 수준 오프셋은 해당 기준 윈도우를 기준으로 더 이전의 집계 값을 읽습니다.
필터 조건(where-clause)¶
필터 조건은 데이터 행을 필터링하여 조건을 충족하는 데이터만 후속 처리에 유지하는 데 사용됩니다.
기본 구문¶
여러 조건은 쉼표 ,, AND, OR, &&, ||로 연결할 수 있습니다(쉼표는 AND와 동일).
비교 연산자¶
| 연산자 | 설명 | 예시 |
|---|---|---|
= |
같음 | host = 'web-01' |
!= |
같지 않음 | status != 'info' |
> |
보다 큼 | usage_total > 80 |
>= |
크거나 같음 | used_percent >= 90 |
< |
보다 작음 | duration < 1000000 |
<= |
작거나 같음 | used_percent <= 80 |
패턴 일치 연산자¶
| 연산자 | 설명 | 예시 |
|---|---|---|
=~ |
정규식 일치 | message =~ 'error.*\\d+' |
!~ |
정규식 불일치 | message !~ 'debug.*' |
집합 연산자¶
| 연산자 | 설명 | 예시 |
|---|---|---|
IN |
집합에 포함 | status IN ['error', 'critical'] |
NOT IN |
집합에 포함되지 않음 | status NOT IN ['debug', 'info'] |
논리 연산자¶
| 연산자 | 설명 | 예시 |
|---|---|---|
AND 또는 && |
논리 AND | usage_total > 80 AND usage_system > 30 |
OR 또는 \|\| |
논리 OR | status = 'error' OR status = 'critical' |
NOT |
논리 NOT | NOT status = 'info' |
팁:
OR연산자는 논리 OR 실행 외에도 널 값 폴백(null fallback) 의미를 제공합니다. 왼쪽 표현식이NULL을 반환하면 오른쪽 표현식의 결과를 직접 반환하므로 우선순위 폴백 로직을 구현하는 데 사용할 수 있습니다. 예:status OR backup_status.
사용 예시¶
기본 필터링¶
// 단일 조건
M::cpu:(usage_total) {host = 'web-01'} [1h]
// 여러 AND 조건(쉼표로 구분)
M::cpu:(usage_total) {host = 'web-01', usage_total > 80} [1h]
// AND 키워드 사용
M::cpu:(usage_total) {host = 'web-01' AND usage_total > 80} [1h]
// 논리 연산자 혼합 사용
M::cpu:(usage_total) {(host = 'web-01' OR host = 'web-02') AND usage_total > 80} [1h]
정규식 일치¶
// ERROR와 4자리 숫자가 포함된 로그 일치
L::*:(message) {message =~ 'ERROR.*\\d{4}'} [15m] LIMIT 20
// 특정 레벨 접두사가 있는 로그 일치
L::*:(message) {message =~ '\\[(ERROR|WARN)\\].*'} [15m] LIMIT 20
// 디버그 정보 제외
L::*:(message) {message !~ 'DEBUG.*'} [15m] LIMIT 20
// 호스트 이름 패턴 일치
M::cpu:(avg(usage_total)) {host =~ 'web-.*'} [1h] BY host
집합 연산¶
// 로그 상태 필터링
L::*:(count(*)) {status IN ['error', 'critical']} [1h] BY service
// 일반 레벨 로그 제외
L::*:(count(*)) {status NOT IN ['debug', 'info', 'ok']} [1h] BY service
// APM 트레이스 HTTP 상태 코드 필터링
T::*:(count(*)) {http_status_code IN ['500', '502', '503', '504']} [1h] BY service
배열 필드 처리¶
필드 유형이 배열(예: 호스트 오브젝트 O::HOST의 태그 배열 필드 df_label 또는 labels)인 경우 DQL은 배열 요소에 대한 포함 일치를 지원합니다.
특정 행 데이터의 배열 필드 값이 df_label = ['web', 'prod', 'api']라고 가정합니다:
권장 구문: IN 및 NOT IN 사용(임의 요소 일치)¶
배열 필드에 IN [...]를 사용하면 배열에 오른쪽 목록의 임의 요소가 하나라도 포함됨(교집합이 비어 있지 않음)을 의미합니다. NOT IN [...]는 배열에 오른쪽 목록의 어떤 요소도 포함되지 않음을 의미합니다.
// 배열에 지정된 값이 포함되어 있는지 확인
{df_label IN ['web']} // true, df_label에 'web'이 포함되어 있기 때문
{df_label IN ['mobile']} // false, df_label에 'mobile'이 포함되어 있지 않기 때문
// 여러 값을 전달할 때: 그중 하나라도 포함되면 true(논리 OR)
{df_label IN ['web', 'mobile']} // true, 'web'이 포함되어 있기 때문
// 배열에 목록의 어떤 값도 포함되지 않았는지 확인
{df_label NOT IN ['mobile', 'dev']} // true, 'mobile'도 'dev'도 포함되어 있지 않기 때문
{df_label NOT IN ['web', 'mobile']} // false, 'web'이 포함되어 있기 때문
배열이 여러 지정 태그를 동시에 포함해야 하는 경우(논리 AND) 여러 IN 조건을 AND(또는 쉼표)로 조합할 수 있습니다:
// 'prod' 태그가 있는 호스트 오브젝트 목록 조회
O::HOST:(host, cpu_usage, mem_used_percent, df_label) {df_label IN ['prod']} LIMIT 20
// 'web'과 'prod' 두 태그가 모두 있는 호스트 오브젝트 목록 조회
O::HOST:(host, cpu_usage, mem_used_percent, df_label) {df_label IN ['web'], df_label IN ['prod']} LIMIT 20
호환 구문(권장하지 않음)¶
다음 = / != 구문은 역사적 호환성을 위해 유지되며 새 쿼리에서는 권장하지 않습니다(배열 필드에서 =는 오른쪽의 모든 요소 포함, !=는 오른쪽의 어떤 요소도 포함하지 않음을 의미하며, 일반 스칼라 필드의 동등 의미와 달라 혼동하기 쉽습니다):
// 이전 구문: 단일 값 포함 확인(등호 연산자의 오버로드 의미)
{df_label = 'web'} // true, df_label에 'web'이 포함되어 있기 때문
{df_label != 'mobile'} // true, df_label에 'mobile'이 포함되어 있지 않기 때문
함수 필터링¶
부울 값을 반환하는 모든 함수는 필터 조건으로 사용할 수 있습니다.
// 문자열 일치 및 와일드카드 일치
L::*:(message) { match(message, 'error') } [15m] LIMIT 20
L::*:(message) { wildcard(message, '*timeout*') } [15m] LIMIT 20
// 소요 시간이 1초를 초과하고 timeout 키워드가 포함된 트레이스 조회
T::*:(service, resource, duration, message) {
duration > 1000000000 AND
match(message, 'timeout')
} [15m] LIMIT 20
// error_type 필드가 존재하는 로그 조회
L::*:(service, status, message) { error_type = exists() } [15m] LIMIT 20
전체 텍스트 검색 및 토큰화 규칙¶
WHERE 절에서 search(...) 또는 query_string(...)을 사용하여 전체 텍스트 검색을 수행할 때, 시스템은 먼저 원시 텍스트와 쿼리 조건을 독립적인 토큰(Token)으로 분할한 후 토큰 기준으로 빠르게 일치시킵니다. 토큰화 규칙을 이해하면 하나의 쿼리가 어떤 데이터를 매칭하는지 정확히 판단하고, 기호나 부분 문자열을 정확히 일치시켜야 할 때 적절한 함수를 선택하는 데 도움이 됩니다.
1. 핵심 분할 규칙¶
토크나이저는 텍스트의 문자를 다음 세 가지 규칙에 따라 처리합니다(기본적으로 대소문자를 구분하지 않음):
| 문자 유형 | 분할 규칙 | 예시(원시 텍스트 → 분할된 토큰) |
|---|---|---|
| 영문자와 숫자 | 연속된 영문자(a-z, A-Z)와 숫자(0-9)는 동일한 토큰으로 병합되고 모두 소문자로 변환됩니다 |
Error → errorhttp2 → http2v1_2 → v1, 2 |
| 중국어 문자 | 일반적인 중국어 단어 또는 단일 문자로 분할하여 독립 토큰으로 만듭니다 | 连接超时 → 连接, 超时数据库异常 → 数据库, 异常 |
| 공백 및 구두점 | 공백, 탭, 줄바꿈 및 모든 일반 구두점은 구분자로 작용하여 토큰화 시 양쪽을 분리하며, 자체는 독립 토큰이 되지 않습니다 | user_name → user, nameapi.example.com → api, example, comhost-01:8080 → host, 01, 8080 |
일반 구분자와 분할 효과는 다음과 같습니다:
| 기호 범주 | 포함 문자 | 일반적인 시나리오 예시(원시 텍스트 → 토큰화 결과) |
|---|---|---|
| 공백 문자 | 공백, \t, \n |
error timeout → error, timeout |
| 연결 기호 및 밑줄 | _, - |
user_name → user, namekube-system → kube, system |
| 점과 콜론 | ., : |
192.168.1.1:8080 → 192, 168, 1, 1, 8080app.service:prod → app, service, prod |
| 경로 및 URL 기호 | /, ?, =, &, # |
/api/v1/users?id=42 → api, v1, users, id, 42 |
| 이메일 및 기타 구두점 | @, ,, ;, ', ", (, ), [, ], {, } 등 |
admin@example.com → admin, example, com |
2. 일반적인 텍스트 토큰화 예시¶
- URL 주소:
https://api.example.com/v1/users?id=123&env=prod_01→ 분할:https,api,example,com,v1,users,id,123,env,prod,01 - 이메일 및 호스트 이름:
user_admin@mail-server.example.com→ 분할:user,admin,mail,server,example,com - 중영문 혼합 로그:
[ERROR] order_service: 订单支付失败, code=500→ 분할:error,order,service,订单,支付,失败,code,500
3. 키워드 일치 vs 구문 일치¶
쿼리 조건이 여러 토큰으로 분할될 때 작성 방식에 따라 토큰 조합 방식이 달라집니다:
| 일치 모드 | 구문 예시 | 실제 일치 로직 | 매칭되는 텍스트 | 매칭되지 않는 텍스트 |
|---|---|---|---|---|
| 키워드 일치(기본) | search("connection timeout")query_string("connection timeout") |
대상 텍스트가 모든 토큰을 동시에 포함(AND 관계), 순서와 거리 무제한 |
"connection timeout""timeout: connection reset" |
"connection"만 포함하고 "timeout"은 포함하지 않는 텍스트 |
| 구문 일치(인접 및 동일 순서) | search("#\"build error\"")query_string("\"build error\"") |
각 토큰이 순서대로 인접하여 나타나야 함(토큰 사이에는 공백 또는 구두점만 허용) | "build error""build: error" |
"build succeeded, parse error"(중간에 다른 토큰이 있음)"error during build"(순서 반대) |
참고:
.,_,-,@,/등의 구두점은 토큰화 시 모두 구분자로 간주되므로, 구문 일치는 토큰이 순서대로 인접하는지만 검증하며 토큰 사이의 구체적인 구두점 종류는 구분하지 않습니다. 예를 들어search("#\"user_name\"")또는query_string("\"user_name\"")는user_name뿐만 아니라user-name또는user.name도 매칭합니다.
4. 텍스트 일치 함수 선택 가이드¶
| 쿼리 요구 사항 | 권장 작성법 | 이유 설명 |
|---|---|---|
| 전체 단어 또는 구문 검색(대소문자 무시) | search("error timeout")search("#\"connection reset\"") |
토큰 인덱스를 직접 활용하여 쿼리 속도가 가장 빠름 |
| 부울 조합 검색(A 또는 B 포함, C 미포함) | query_string("(error OR warn) AND NOT timeout") |
AND, OR, NOT 및 괄호 그룹화 지원 |
구두점이 포함된 부분 문자열을 엄격히 일치(예: user_name과 user-name 구분 또는 /api/v1/login 정확히 찾기) |
match(message, "user_name")match(message, "/api/v1/login") |
match는 원시 문자 부분 문자열을 문자 단위 포함으로 일치하므로 _, /, . 토큰화로 인해 기호 차이가 무시되지 않음 |
단어 내부 조각 일치(예: cept로 Exception 매칭) |
match(message, "cept")wildcard(message, "*cept*") |
토큰 검색은 완전한 토큰 단위이므로 search("cept")는 Exception을 매칭하지 않음. 부분 문자열 또는 와일드카드 일치 필요 |
| 대소문자 구분 또는 복잡한 형식 일치(예: 4자리 숫자 오류 코드) | re(message, "ERR-\\d{4}") |
re / regexp는 완전한 정규식을 지원하며 대소문자를 구분함 |
// 1. 전체 텍스트 토큰 검색: error와 timeout을 동시에 포함(대소문자 및 단어 순서 무시)
L::*:(service, message) {search("error timeout")} [15m] LIMIT 20
// 2. 구문 순서 검색: build와 error가 순서대로 인접하여 나타나야 함
L::*:(service, message) {search("#\"build error\"")} [15m] LIMIT 20
// 3. 엄격한 부분 문자열 일치: 밑줄이 포함된 "user_name"을 정확히 일치하며 "user-name"을 잘못 매칭하지 않음
L::*:(service, message) {match(message, "user_name")} [15m] LIMIT 20
// 4. 조합 논리 검색: error 또는 warn을 포함하고 healthcheck는 포함하지 않음
L::*:(service, message) {query_string("(error OR warn) AND NOT healthcheck")} [15m] LIMIT 20
WHERE 서브쿼리¶
WHERE 서브쿼리는 DQL에서 네임스페이스 간 동적 필터링을 구현하는 강력한 기능으로, 하나의 쿼리 결과를 다른 쿼리의 IN / NOT IN 필터 조건으로 사용할 수 있습니다.
쿼리 특징¶
- 동적 필터링: 필터 조건이 고정된 값이 아니라 내부 서브쿼리를 통해 동적으로 계산됩니다
- 네임스페이스 혼합: 네임스페이스 간 연관 쿼리를 지원합니다(예: 먼저
O::HOST오브젝트에서 특정 호스트를 조회한 후M::cpu에서 해당 호스트의 메트릭을 조회하거나, 먼저L로그에서 오류가 발생한trace_id를 조회한 후T트레이스에서 호출 상세를 조회) - 단일 열 프로젝션: 내부 서브쿼리는 단일 차원 필드만 선택할 수 있으며(예:
:(host)), 결과는 자동으로 중복 제거되어 배열로 수집되어 외부IN또는NOT IN에 사용됩니다
실행 흐름¶
네임스페이스 간 WHERE 서브쿼리의 일반적인 예시(Linux 호스트의 평균 CPU 사용률 조회):
실행 과정:
-
서브쿼리 실행:
O::HOST:(host) {os = 'linux'}- 인프라스트럭처 호스트 오브젝트
O::HOST조회 - 운영 체제
os = 'linux'인 호스트 필터링 - 중복 제거된 호스트 이름 목록 반환:
['host-01', 'host-02', ...]
- 인프라스트럭처 호스트 오브젝트
-
메인 쿼리 실행:
M::cpu:(avg(usage_total)) {host IN [...]} [1h] BY hostcpu메저먼트 데이터 조회- 서브쿼리가 반환한 Linux 호스트만 집계
- 호스트별로 평균 CPU 사용률 계산
사용 예시¶
// 오브젝트와 메트릭 연관: 클라우드 공급자가 aliyun인 호스트의 CPU 사용률 조회
M::cpu:(avg(usage_total)) { host IN (O::HOST:(host) {cloud_provider = 'aliyun'}) } [1h] BY host
// 오브젝트와 메트릭 연관: 특정 태그가 있는 호스트의 메모리 사용률 조회
M::mem:(avg(used_percent)) { host IN (O::HOST:(host) {df_label IN ['prod']}) } [1h] BY host
// 트레이스와 로그 연관: 최근 1시간 동안 트레이스 오류가 발생한 서비스의 오류 로그 수 조회
L::*:(count(*)) { service IN (T::*:(service) {status = 'error'} [1h]) } [1h] BY service, status
// 이력 전체 기간 Top-N 필터링: 먼저 1시간 내 평균 CPU가 가장 높은 Top 5 호스트를 찾은 후, 해당 호스트의 5분 시계열 추세선을 그림
M::cpu:(avg(usage_total) AS avg_cpu) {
host IN (
M::(M::cpu:(avg(usage_total) AS c) [1h::1h] BY host SORDER BY c DESC SLIMIT 5):(host) [1h::1h]
)
} [1h::5m] BY host
그룹화(group-by-clause)¶
그룹화는 데이터 분석의 핵심 기능으로, 데이터를 지정된 차원으로 그룹화하여 집계하는 데 사용됩니다.
기본 구문¶
그룹화 유형¶
필드 그룹화¶
// 단일 필드 그룹화: 호스트별로 CPU 사용률 집계
M::cpu:(avg(usage_total)) [1h] BY host
// 다중 필드 그룹화: 호스트 및 디스크 장치별로 디스크 사용률 집계
M::disk:(max(used_percent)) [1h] BY host, device
// 로그 다차원 그룹화: 서비스 및 로그 상태별로 수 집계
L::*:(count(*)) [1h] BY service, status
표현식 그룹화¶
// 수학 표현식 그룹화: 소요 시간(초) 구간별로 트레이스 수 집계
T::*:(count(*)) [1h] BY floor(duration / 1000000000) AS duration_sec_bucket
함수 그룹화¶
// Drain 클러스터링 알고리즘: 유사한 로그를 자동으로 템플릿으로 분류하고 빈도 집계
L::*:(count(*)) [1h] BY drain(message, 0.7) AS template
// 정규식 추출 그룹화: 로그 본문에서 오류 코드를 추출하여 그룹화 집계
L::*:(count(*)) [1h] BY regexp_extract(message, 'error_code: (\\d+)', 1) AS error_code
그룹화 결과 처리¶
쿼리에 그룹화와 시간 윈도우가 동시에 포함되면 2차원 데이터 구조가 생성됩니다. Group By는 시간 윈도우와 함께 사용할 수 있으며, 이러한 쿼리 결과는 2차원 배열이 됩니다. 이 2차원 배열의 첫 번째 차원은 그룹화 키로 구분된 여러 그룹 자체이고, 두 번째 차원은 단일 그룹 내의 여러 시간 구간 데이터입니다.
2차원 데이터 구조 예시:
쿼리: M::cpu:(max(usage_total)) [1h::10m] BY host
쿼리 결과 구조:
{
"series": [
{
"columns": ["time", "max(usage_total)"],
"name": "cpu",
"tags": {"host": "web-server-01"},
"values": [
[1721059200000, 78.5],
[1721058600000, 82.3],
[1721058000000, 75.8],
[1721057400000, 88.2]
]
},
{
"columns": ["time", "max(usage_total)"],
"name": "cpu",
"tags": {"host": "web-server-02"},
"values": [
[1721059200000, 45.2],
[1721058600000, 52.8],
[1721058000000, 48.5],
[1721057400000, 61.3]
]
},
{
"columns": ["time", "max(usage_total)"],
"name": "cpu",
"tags": {"host": "web-server-03"},
"values": [
[1721059200000, 92.1],
[1721058600000, 95.7],
[1721058000000, 89.4],
[1721057400000, 97.6]
]
}
]
}
이 2차원 배열을 다시 가공하려면:
- 이 2차원 배열의 결과를 필터링하려면 Having 절을 사용합니다
- 2차원 배열의 단일 그룹 내 데이터를 정렬하거나 페이지네이션하려면 order by, limit, offset 계열 문을 사용합니다
- 2차원 배열의 그룹 자체를 정렬하거나 페이지네이션하려면 sorder by, slimit, soffset 계열 문을 사용합니다
2차원 데이터 구조에 대한 자세한 설명과 정렬 및 페이지네이션 기능은 정렬 및 페이지네이션을 참고하십시오.
Having 절(having-clause)¶
Having 절은 그룹 집계 후 결과를 필터링하는 데 사용되며, WHERE 절과 유사하지만 집계된 데이터에 적용됩니다.
기본 구문¶
WHERE와의 차이¶
WHERE와 HAVING은 모두 데이터를 필터링하는 절이지만, 쿼리 실행의 서로 다른 단계에서 작동하며 처리하는 필터 조건도 다릅니다.
실행 시점의 차이¶
-
WHERE 절:
- 그룹 집계 전에 실행
- 원시 데이터 행에 적용
- 조건을 충족하지 않는 데이터 행을 필터링하여 후속 처리 데이터 양 감소
-
HAVING 절:
- 그룹 집계 후에 실행
- 집계된 결과에 적용
- 집계 함수의 별칭 또는 결과를 기반으로 필터링
적용 시나리오¶
HAVING 절은 집계 결과를 필터링하는 데 적합합니다:
// 평균 CPU 사용률이 80%를 초과하는 고부하 호스트 필터링
M::cpu:(avg(usage_total) AS avg_usage) [1h] BY host HAVING avg_usage > 80
// 오류 로그 수가 100개를 초과하는 서비스 필터링
L::*:(count(*) AS err_count) {status = 'error'} [1h] BY service HAVING err_count > 100
// 오류율이 1%를 초과하고 총 요청 수가 1000보다 큰 APM 서비스 필터링
T::*:(
count(*) AS total,
count(CASE WHEN status = 'error' THEN 1 ELSE nil END) AS errors
) [1h] BY service
HAVING errors / total > 0.01 AND total > 1000
// 평균 소요 시간이 높고 변동 범위가 큰 인터페이스 필터링
T::*:(
avg(duration) AS avg_time,
max(duration) AS max_time,
min(duration) AS min_time
) [1h] BY resource
HAVING avg_time > 100000000 AND (max_time - min_time) > 500000000
정렬 및 페이지네이션¶
DQL의 정렬 및 페이지네이션은 매우 중요하고 독특한 기능으로, 시계열 데이터의 특성에 맞춰 그룹 내 정렬과 그룹 간 정렬의 이중 정렬 메커니즘을 설계했습니다. 이러한 설계 덕분에 DQL은 복잡한 다차원 시계열 데이터 분석 요구를 효율적으로 처리할 수 있습니다.
DQL의 데이터 구조 이해¶
정렬 및 페이지네이션을 자세히 살펴보기 전에 DQL 쿼리 결과의 2차원 데이터 구조를 먼저 이해해 보겠습니다. 쿼리에 그룹화(BY)와 시간 윈도우가 동시에 포함되면 2차원 배열이 생성됩니다:
- 첫 번째 차원(그룹 차원): 그룹화 키로 구분된 여러 그룹
- 두 번째 차원(시간 차원): 각 그룹 내에서 시간 윈도우별로 집계된 데이터
2차원 데이터 구조에 대한 자세한 설명과 JSON 형식 예시는 그룹화 결과 처리를 참고하십시오. 이 2차원 구조는 DQL 정렬 및 페이지네이션 기능의 기반이며, 이 구조를 이해하는 것은 DQL의 정렬 메커니즘을 이해하는 데 중요합니다.
그룹 내 정렬 및 페이지네이션(ORDER BY, LIMIT, OFFSET)¶
그룹 내 정렬 및 페이지네이션은 2차원 구조의 두 번째 차원, 즉 각 그룹 내부의 데이터(또는 그룹화되지 않은 상세 쿼리의 행 데이터)에 적용됩니다. 이 정렬은 각 그룹 내에서 독립적으로 실행되며 다른 그룹의 데이터에는 영향을 주지 않습니다.
기본 구문¶
실행 메커니즘¶
그룹 내 정렬 실행 과정:
- 그룹 처리: 각 그룹에 대해 독립적으로 정렬 작업 수행
- 정렬 기준: 시간 필드, 집계 함수 결과 별칭 또는 원시 필드 사용 가능
- 페이지네이션 제한: LIMIT는 각 그룹에서 반환되는 데이터 행 수를 제한하며, 명시적으로 지정한 값은 양의 정수여야 합니다.
- 오프셋 처리: OFFSET은 각 그룹의 처음 N개 행 데이터를 건너뜁니다
사용 예시¶
기본 시간 정렬¶
// 시간 내림차순 정렬, 각 호스트의 최신 데이터 표시
M::cpu:(max(usage_total)) [1h::10m] BY host ORDER BY time DESC
// 시간 오름차순 정렬, 이력 추세 표시
M::cpu:(max(usage_total)) [1h::10m] BY host ORDER BY time ASC
실행 결과(ORDER BY time DESC):
{
"series": [
{
"columns": ["time", "max(usage_total)"],
"name": "cpu",
"tags": {"host": "web-server-01"},
"values": [
[1721059200000, 78.5],
[1721058600000, 82.3],
[1721058000000, 75.8],
[1721057400000, 88.2],
[1721056800000, 72.1],
[1721056200000, 69.4]
]
},
{
"columns": ["time", "max(usage_total)"],
"name": "cpu",
"tags": {"host": "web-server-02"},
"values": [
[1721059200000, 45.2],
[1721058600000, 52.8],
[1721058000000, 48.5],
[1721057400000, 61.3],
[1721056800000, 55.7],
[1721056200000, 58.9]
]
}
]
}
숫자 기반 정렬¶
// CPU 사용률 내림차순 정렬, 각 호스트의 피크 시간대 찾기
M::cpu:(max(usage_total) AS max_usage_total) [1h::10m] BY host ORDER BY max_usage_total DESC
// 상세 쿼리: 소요 시간 내림차순으로 가장 느린 10개 트레이스 Span 조회
T::*:(service, resource, duration, trace_id) [15m] ORDER BY duration DESC LIMIT 10
그룹 내 페이지네이션¶
// 각 호스트에서 최신 데이터 포인트 3개만 표시
M::cpu:(max(usage_total)) [1h::10m] BY host ORDER BY time DESC LIMIT 3
// 최신 데이터 포인트 2개를 건너뛰고 다음 3개 표시
M::cpu:(max(usage_total)) [1h::10m] BY host ORDER BY time DESC LIMIT 3 OFFSET 2
실행 결과(LIMIT 3):
{
"series": [
{
"columns": ["time", "max(usage_total)"],
"name": "cpu",
"tags": {"host": "web-server-01"},
"values": [
[1721059200000, 78.5],
[1721058600000, 82.3],
[1721058000000, 75.8]
]
},
{
"columns": ["time", "max(usage_total)"],
"name": "cpu",
"tags": {"host": "web-server-02"},
"values": [
[1721059200000, 45.2],
[1721058600000, 52.8],
[1721058000000, 48.5]
]
}
]
}
그룹 간 정렬 및 페이지네이션(SORDER BY, SLIMIT, SOFFSET)¶
그룹 간 정렬 및 페이지네이션은 DQL의 특징적인 기능으로, 2차원 구조의 첫 번째 차원, 즉 그룹(Series) 자체를 정렬하고 Top-N을 선택하는 데 적용됩니다.
쿼리에서 BY를 사용하지 않으면 결과는 일반적으로 하나의 그룹만 갖습니다. 이때 SORDER BY는 정렬상 일반적으로 눈에 띄는 효과가 없지만, SLIMIT / SOFFSET는 여전히 "그룹 수" 의미로 작동합니다(즉, 해당 단일 그룹을 대상으로 함).
기본 구문¶
실행 메커니즘 및 핵심 의미¶
그룹 간 정렬 실행 과정:
- 각 그룹의 정렬 대표값 결정:
- 단일 윈도우 집계 쿼리(간격 없음, 예:
[1h]): 각 그룹에는 집계 결과 행이 1개만 있으므로SORDER BY <프로젝션 별칭>은 해당 집계값으로 그룹을 직접 정렬합니다. - 다중 시점 시계열 쿼리(간격 있음, 예:
[1h::5m]): 각 그룹에는 여러 시간 버킷이 있습니다.SORDER BY <프로젝션 별칭>은 해당 그룹의 마지막 시간 버킷 값(last)으로 정렬합니다.SORDER BY sum(<프로젝션 별칭>)/avg(<프로젝션 별칭>)/max(<프로젝션 별칭>)는 해당 프로젝션 열을 전체 쿼리 기간의 모든 시간 버킷에서 2차 집계한 후 정렬합니다.
- 단일 윈도우 집계 쿼리(간격 없음, 예:
- 그룹 정렬: 각 그룹의 대표값에 따라 모든 그룹을 오름차순 또는 내림차순으로 정렬합니다.
- 그룹 페이지네이션:
SLIMIT는 반환되는 그룹 수를 제한하며(명시적으로 지정한 값은 양의 정수여야 함),SOFFSET는 처음 N개 그룹을 건너뜁니다.
중요 팁(
SORDER BY작성 권장 규범): 1. 항상 Select 집계 표현식에 별칭을 지정하고SORDER BY에서 해당 별칭을 참조하십시오(예:M::cpu:(avg(usage_total) AS avg_usage) [1h] BY host SORDER BY avg_usage DESC SLIMIT 5).SORDER BY에 별칭이 없는 집계 또는 원시 필드를 직접 작성하지 마십시오(예:SORDER BY count(*),SORDER BY avg(usage_total)).SORDER BY는 프로젝션 이후에 실행되므로 이 시점에는 원시 열이 존재하지 않으며 푸시다운할 수도 없습니다. 2. 간격이 있는 시계열 쿼리에서 정렬 방식을 어떻게 선택합니까? - 최신 시간 버킷 기준 정렬:SORDER BY avg_usage DESC를 직접 작성합니다. - 전체 기간의 합계/평균/피크 기준 정렬: 프로젝션 별칭에 집계 함수를 적용합니다. 예:M::cpu:(avg(usage_total) AS avg_usage) [1h::5m] BY host SORDER BY avg(avg_usage) DESC SLIMIT 5(또는WHERE ... IN (서브쿼리)를 사용하여 단일 버킷 윈도우[1h::1h]에서 Top-N 차원을 먼저 선택).
사용 예시¶
단일 윈도우 상위 목록(전체 기간 집계값 기준 정렬)¶
// 지난 1시간 평균 CPU 사용률이 가장 높은 5개 호스트 집계
M::cpu:(avg(usage_total) AS avg_usage) [1h] BY host SORDER BY avg_usage DESC SLIMIT 5
// 지난 1시간 평균 응답 소요 시간이 가장 짧은 10개 APM 서비스 집계
T::*:(avg(duration) AS avg_duration) [1h] BY service SORDER BY avg_duration ASC SLIMIT 10
// 지난 1시간 오류 로그가 가장 많은 5개 서비스 집계
L::*:(count(*) AS error_count) {status = 'error'} [1h] BY service SORDER BY error_count DESC SLIMIT 5
다중 시점 시계열 쿼리(최신 시간 버킷 기준 정렬)¶
// 지난 1시간(10분마다 1포인트) 각 호스트의 피크 CPU를 조회하고, 최신 시간 버킷의 피크 내림차순으로 상위 10개 호스트 선택
M::cpu:(max(usage_total) AS max_usage) [1h::10m] BY host SORDER BY max_usage DESC SLIMIT 10
// 지난 24시간(1시간마다 1포인트) 각 호스트의 최저 메모리 사용률을 조회하고, 최신 시간 버킷 기준 최저 5개 호스트 선택
M::mem:(min(used_percent) AS min_mem) [24h::1h] BY host SORDER BY min_mem ASC SLIMIT 5
실행 결과 예시(SLIMIT 2):
{
"series": [
{
"columns": ["time", "avg_usage"],
"name": "cpu",
"tags": {"host": "web-server-03"},
"values": [
[1721059200000, 92.1],
[1721058600000, 95.7],
[1721058000000, 89.4]
]
},
{
"columns": ["time", "avg_usage"],
"name": "cpu",
"tags": {"host": "web-server-01"},
"values": [
[1721059200000, 78.5],
[1721058600000, 82.3],
[1721058000000, 75.8]
]
}
]
}
이중 정렬 및 페이지네이션 조합 사용¶
실제 애플리케이션에서는 그룹 내 정렬과 그룹 간 정렬을 함께 사용하여 복잡한 데이터 표시 요구를 구현하는 경우가 많습니다. 이 조합은 그룹 순서와 그룹 내 데이터 순서를 동시에 제어할 수 있습니다.
실행 순서¶
이중 정렬 실행 순서:
- 그룹 간 정렬: 먼저 모든 그룹을 정렬하고 페이지네이션합니다(
SORDER BY+SLIMIT) - 그룹 내 정렬: 선택된 그룹에 대해 내부 정렬 및 페이지네이션을 수행합니다(
ORDER BY+LIMIT)
사용 예시¶
모니터링 대시보드 시나리오¶
// CPU 사용률이 가장 높은 10개 호스트를 찾고, 각 호스트에서 최신 5개 시점만 반환
M::cpu:(avg(usage_total) AS avg_usage) [1h::10m] BY host
ORDER BY time DESC LIMIT 5
SORDER BY avg_usage DESC SLIMIT 10
실행 결과:
{
"series": [
{
"columns": ["time", "avg_usage"],
"name": "cpu",
"tags": {"host": "web-server-03"},
"values": [
[1721059200000, 92.1],
[1721058600000, 95.7],
[1721058000000, 89.4],
[1721057400000, 97.6],
[1721056800000, 87.3]
]
},
{
"columns": ["time", "avg_usage"],
"name": "cpu",
"tags": {"host": "web-server-01"},
"values": [
[1721059200000, 78.5],
[1721058600000, 82.3],
[1721058000000, 75.8],
[1721057400000, 88.2],
[1721056800000, 72.1]
]
}
]
}
일반적인 쿼리 시나리오 실전(바로 복사하여 실행 가능)¶
이 섹션은 일상적인 운영 모니터링, 로그 문제 해결, APM 트레이스 분석, RUM 사용자 방문 및 알림 이벤트 집계의 고빈도 쿼리 템플릿을 정리합니다. 모든 예시는 플랫폼 기본 수집 메저먼트와 표준 필드를 기반으로 작성되었으며, 워크스페이스의 "빠른 쿼리 / DQL 쿼리"에 복사하면 바로 실행할 수 있습니다.
시나리오 1: 인프라스트럭처 모니터링(호스트 CPU / 메모리 / 디스크 / 네트워크)¶
- 데이터 전제: DataKit이 설치되어 있고 기본 호스트 수집기(
cpu,mem,disk,net,system및 오브젝트O::HOST)가 활성화되어 있습니다. - 예상 결과: 호스트 또는 장치별 리소스 사용률 순위, 시계열 추세 또는 온라인 호스트 목록을 반환합니다.
// 1.1 지난 1시간 평균 CPU 사용률이 가장 높은 Top 10 호스트 조회(단일 값 순위)
M::cpu:(avg(usage_total) AS avg_cpu, max(usage_total) AS max_cpu) [1h] BY host SORDER BY avg_cpu DESC SLIMIT 10
// 1.2 메모리 사용률이 80%를 초과하는 호스트의 시계열 추세 조회(5분마다 1포인트)
M::mem:(avg(used_percent) AS mem_pct) [1h::5m] BY host HAVING mem_pct > 80 SORDER BY mem_pct DESC SLIMIT 20
// 1.3 각 호스트 디스크 파티션 사용률 및 남은 공간 조회(단위를 GB로 변환)
M::disk:(last(used_percent) AS disk_pct, last(free) / 1024 / 1024 / 1024 AS free_gb) [15m] BY host, device HAVING disk_pct > 75 SORDER BY disk_pct DESC SLIMIT 20
// 1.4 각 호스트 네트워크 카드 수신 및 송신 처리 속도 계산(Counter 메트릭은 rate를 사용하여 바이트/초로 변환)
M::net:(sum(bytes_recv) AS recv_bps, sum(bytes_sent) AS sent_bps) [1h::1m:rate] BY host SORDER BY recv_bps DESC SLIMIT 10
// 1.5 최근 10분 이내 온라인 상태인 Linux 호스트 자산 목록 및 핵심 부하 메트릭 조회
O::HOST:(host, os, arch, cpu_usage, mem_used_percent, disk_used_percent, load) {os = 'linux', last_update_time > now() - 10m} ORDER BY cpu_usage DESC LIMIT 20
시나리오 2: 로그 검색 및 문제 해결(Logging)¶
- 데이터 전제: 로그 수집이 활성화되어 있습니다(
L네임스페이스, 공통 필드message,status,service,source,host포함). - 예상 결과: 오류 로그 추세, 고빈도 오류 서비스, 로그 클러스터링 템플릿 또는 컨텍스트 마스킹 추출 결과를 반환합니다.
// 2.1 최근 15분 동안 "timeout" 또는 "connection refused"가 포함된 오류 로그 상세 검색
L::*:(source, service, host, status, message) {status IN ['error', 'critical'], query_string(message, "timeout OR \"connection refused\"")} [15m] ORDER BY time DESC LIMIT 50
// 2.2 최근 1시간 서비스별 로그 쓰기 QPS(초당 로그 수) 집계
L::*:(count(*) / 1i AS log_qps) [1h::1m] BY service SORDER BY log_qps DESC SLIMIT 10
// 2.3 각 서비스의 오류 로그 수와 전체 로그 수를 집계하고, 오류 로그가 10개를 초과하는 서비스 필터링
L::*:(
count(*) AS total_logs,
count(CASE WHEN status = 'error' OR status = 'critical' THEN 1 ELSE nil END) AS error_logs
) [1h] BY service HAVING error_logs > 10 SORDER BY error_logs DESC SLIMIT 20
// 2.4 Drain 알고리즘을 사용하여 최근 1시간 오류 로그를 자동 클러스터링하고 고빈도 오류 패턴을 빠르게 찾기
L::*:(count(*) AS cnt, any(service) AS sample_service) {status = 'error'} [1h] BY drain(message, 0.7) AS log_template SORDER BY cnt DESC SLIMIT 20
시나리오 3: APM 애플리케이션 성능 및 트레이스 분석(Tracing)¶
- 데이터 전제: APM 분산 추적이 연동되어 있습니다(
T네임스페이스, 표준 필드service,resource,duration,status,span_type,trace_id포함). - 예상 결과: 서비스 처리량, 오류율, P50/P95/P99 응답 지연 및 느린 호출 상세를 반환합니다.
// 3.1 각 서비스 엔트리 요청(span_type = 'entry')의 P50 / P95 / P99 응답 지연(단위: 나노초) 집계
T::*:(
p50(duration) AS p50_ns,
p95(duration) AS p95_ns,
p99(duration) AS p99_ns
) {span_type = 'entry'} [1h] BY service SORDER BY p99_ns DESC SLIMIT 15
// 3.2 각 서비스의 총 요청 수, 오류 수 및 오류율 백분율 집계
T::*:(
count(*) AS total_req,
count(CASE WHEN status = 'error' THEN 1 ELSE nil END) AS err_req,
(count(CASE WHEN status = 'error' THEN 1 ELSE nil END) / count(*)) * 100 AS err_rate_pct
) {span_type = 'entry'} [1h] BY service SORDER BY err_req DESC SLIMIT 15
// 3.3 단일 인터페이스의 소요 시간 분포 히스토그램 및 분위수 분석(histogram_auto)
T::*:(histogram_auto(duration)) {span_type = 'entry'} [1h] BY service SLIMIT 10
// 3.4 최근 15분 동안 소요 시간이 가장 긴 Top 20 예외 호출 체인 상세 검색
T::*:(service, resource, duration, http_status_code, trace_id, span_id) {status = 'error'} [15m] ORDER BY duration DESC LIMIT 20
시나리오 4: RUM 사용자 방문 경험 분석(Real User Monitoring)¶
- 데이터 전제: 프론트엔드 또는 모바일 RUM 수집이 연동되어 있습니다(
R네임스페이스, 데이터 소스view,error,resource포함). - 예상 결과: 페이지 PV/UV, 최초 화면 로딩 소요 시간 및 프론트엔드 JS 오류 순위를 반환합니다.
// 4.1 지난 24시간 각 페이지의 조회 수(PV), 순방문자 수(UV) 및 평균 로딩 시간 집계
R::view:(
count(*) AS pv,
count_distinct(userid) AS uv,
avg(loading_time) AS avg_load_time
) [24h] BY view_path SORDER BY pv DESC SLIMIT 20
// 4.2 지난 1시간 프론트엔드 오류가 가장 많은 오류 유형과 예시 메시지 집계
R::error:(count(*) AS err_cnt, any(error_message) AS sample_msg) [1h] BY app_id, error_type SORDER BY err_cnt DESC SLIMIT 15
시나리오 5: 전년 동기 대비 / 전기 대비 분석 및 미복구 알림 조회¶
- 데이터 전제: 워크스페이스에 과거 동기간 데이터(
SHIFT비교용)가 있거나 모니터 알림이 활성화되어 있습니다(E/UE네임스페이스). - 예상 결과: 현재 윈도우와 어제/지난주 동기간의 비교 결과 또는 현재 미복구 알림 통계를 반환합니다.
// 5.1 로그 트래픽 주간 대비 분석: 지난 1시간과 7일 전 동기간의 서비스별 로그량 및 증가 배수 비교
L::*:(
service,
count(*) AS current_logs,
count(*) SHIFT 7d AS last_week_logs,
CASE
WHEN (count(*) SHIFT 7d) = nil OR (count(*) SHIFT 7d) = 0 THEN nil
ELSE count(*) / (count(*) SHIFT 7d)
END AS wow_ratio
) [1h] BY service SLIMIT 15
// 5.2 현재 미복구 알림 이벤트(UE 네임스페이스)를 알림 등급 및 모니터별로 그룹화하여 집계
UE::monitor:(count(*) AS active_events, any(df_title) AS sample_title) [24h] BY df_status, df_monitor_checker_name SORDER BY active_events DESC SLIMIT 20
DQL의 정렬, 페이지네이션 및 조합 분석 기능을 익히면 강력한 모니터링 대시보드, 성능 분석 도구 및 비즈니스 인사이트 시스템을 구축할 수 있습니다.
주의
그룹 내 정렬과 그룹 간 정렬의 조합을 합리적으로 사용하면 데이터 분석의 효율성과 효과를 크게 향상시킬 수 있습니다.