MXQL 문법 가이드

형식

MXQL은 각 라인마다 <명령어>와 <오퍼랜드>로 구성되며, 띄어쓰기로 구분됩니다.

<명령어> <오퍼랜드>

<명령어>는 한 단어의 예약어로 되어있습니다. <명령어>는 대문자로 입력하며, <오퍼랜드>는 소문자로 입력합니다. <명령어>마다 입력 가능한 <오퍼랜드>의 형식이 정해져있습니다. <오퍼랜드>에는 4가지 타입의 값이 올 수 있습니다.

  1. 오퍼랜드가 없는 경우

    TAGLOAD
  2. 문자열(숫자 혹은 단어)

    CATEGORY app_counter
  3. 문자열 배열

    SELECT [ time, pcode ]
  4. JSON문자열 타입

    FILTER { key : tx_count, value : 5}
샘플 MXQL 쿼리
CATEGORY app_counter
TAGLOAD
SELECT [ time, pcode ]
FILTER { key : tx_count, value : 5}

테스트 환경

MXQL 쿼리는 '프로젝트 선택 > 사이트맵 > 실험실 > MXQL 데이터 조회’에서 테스트해보실 수 있습니다.

메트릭스에는 태그와 필드가 구분되어 있지만, 'MXQL 데이터 조회’에서는 태그와 필드의 구분 없이 표현됩니다.
mxql 7
Figure 1. MXQL 데이터 조회(app_category에 저장된 모든 태그와 필드를 조회하는 쿼리)

단계별 구성

MXQL은 단계별 구성을 가지고 있습니다. 각 단계별로 사용할 수 있는 <명령어>의 종류가 정해져있으며, 각 단계의 이름과 특징은 아래와 같습니다.

  1. 메트릭스 선택 : 어떤 에이전트에서 수집된 어떤 메트릭스를 사용할지 선택합니다.

  2. 메트릭스 로딩 : 이전 단계에서 설정한 값들을 사용해서 메트릭스를 불러옵니다. 대부분의 경우 TAGLOAD를 사용하며, 특수한 경우에만 FLEXLOAD를 사용합니다.

  3. 메트릭스 가공 : 이전 단계에서 불러온 메트릭스에 대해서 단계별로 가공을 수행합니다.

단계별 구성 예시
# 메트릭스 선택 단계
CATEGORY app_counter -- 카테고리 선택

# 메트릭스 로딩 단계
TAGLOAD -- 데이터 1000개 조회

# 메트릭스 가공 단계
SELECT [time, oid, active_tx_count, tx_count, tx_error] -- 1000개 데이터의 5개 필드만 다음 단계로 전달
FILTER {expr : "tx_count > 40"}        -- 데이터 1000개 중 100개만 통과
FILTER {expr : "active_tx_count > 10"} -- 데이터 100개 중 10개만 통과
FILTER {expr : "tx_error < 3"}        -- 데이터 10개 중 3개만 통과
mxql metrics calculate example
Figure 2. 메트릭스 가공 단계를 모두 통과한 메트릭스 예시

주석

"#" 또는 "--"으로 시작하는 문장은 무시됩니다.

# 데이터 조회 설정
CATEGORY app_counter

# 데이터 조회
TAGLOAD

# 데이터 가공
SELECT [ time, pcode ]
FILTER { key : tx_count, value : 5}

MetricValue(복합값)

MetricValue(복합값)은 메트릭스 가공 단계에서 자주 사용되는 연산을 편리하게 지원하는 MXQL의 자료구조입니다. 메트릭스 가공 단계의 GROUP, UPDATE 명령어는 메트릭스가 MetricValue 형태로 저장되어 있을 때만 사용할 수 있습니다.

예를 들어 아래와 같은 데이터가 있다고 가정해보겠습니다.

Table 1. 샘플 데이터

time

tx_count

2021/06/24 13:40:00

1

2021/06/24 13:40:10

2

2021/06/24 13:40:20

3

2021/06/24 13:40:30

4

2021/06/24 13:40:40

5

2021/06/24 13:40:50

6

만약 위 데이터에 대해서 30초 간격으로 GROUP의 merge 옵션을 진행하면 아래와 같은 형태로 데이터가 변형됩니다.

Table 2. 그룹화된 샘플 데이터

time

tx_count

2021/06/24 13:40:00 ~ 2021/06/24 13:40:20

1,2,3에 대한 MetricValue

2021/06/24 13:40:30 ~ 2021/06/24 13:40:50

4,5,6에 대한 MetricValue

데이터가 MetricValue로 변환되면 총 6가지 옵션을 사용할 수 있게됩니다.

Table 3. MetricValue 옵션 종류

옵션

기능

sum

MetricValue에 포함된 값을 더합니다.

min

MetricValue에 포함된 값 중 최소값을 구합니다.

max

MetricValue에 포함된 값 중 최대값을 구합니다.

last

MetricValue에 포함된 값 중 마지막에 추가된 값을 구합니다.

avg

MetricValue에 포함된 값의 평균을 구합니다.

cnt

MetricValue에 포함된 값의 갯수를 구합니다.

MetricValue 옵션은 UPDATE <명령어>를 통해서 사용할 수 있습니다.

CATEGORY app_counter
TAGLOAD
SELECT [ time, okindName, okind, apdex_satisfied, apdex_tolerated, apdex_total]
-- GROUP <명령어>의 merge 옵션을 통해 MetricValue로 변환할 field를 설정
GROUP { timeunit:5000, pk:okind, last:okindName, merge:[apdex_satisfied, apdex_tolerated, apdex_total] }
-- UPDATE <명령어>를 통해 sum 옵션을 적용
UPDATE { key:[apdex_satisfied, apdex_tolerated, apdex_total], value:sum }

MetricValue 타입의 데이터를 사용하기 위한 방법 2가지

  1. GROUP 명령어의 merge 옵션에 필드를 지정합니다.

    CATEGORY app_counter
    TAGLOAD
    SELECT [ time, okindName, okind, apdex_satisfied, apdex_tolerated, apdex_total]
    -- GROUP <명령어>의 merge 옵션을 통해 MetricValue로 변환할 field를 설정
    GROUP { timeunit:5000, pk:okind, last:okindName, merge:[apdex_satisfied, apdex_tolerated, apdex_total] }
    -- UPDATE <명령어>를 통해 sum 옵션을 적용
    UPDATE { key:[apdex_satisfied, apdex_tolerated, apdex_total], value:sum }
  2. 수집서버에 데이터가 저장될 때부터 모든 필드가 MetricValue 형식으로 저장된 카테고리가 있습니다. '사이트맵 > 분석 > 메트릭스 조회 > 카테고리 조회’에서는 기본, 5분,1시간 옵션을 선택할 수 있는 카테고리를 확인할 수 있습니다. 여기서 5분 또는 1시간 옵션을 선택할 수 있는 카테고리가 MetricValue 형식으로 저장된 카테고리입니다.

    mxql 3
    Figure 3. MetricValued 타입으로 지정할 수 있는 카테고리 목록

    5분 또는 1시간 옵션을 선택할 수 있는 CATEGORY의 이름에 {m5} 또는 {h1}가 붙히면, GROUP <명령어>의 merge 옵션을 적용하지 않고 바로 UPDATE <명령어>의 sum 옵션을 적용 할 수 있습니다.

    -- 모든 필드가 MetricValue타입으로 저장된 app_counter{m5} 카테고리를 사용
    CATEGORY app_counter{m5}
    TAGLOAD
    SELECT [time, pname, host_ip, pid, httpc_count]
    -- GROUP 명령어를 적용하지 않아도 이미 데이터가 MetricValue 타입이기 때문에 UPDATE 명령어를 적용할 수 있습니다.
    UPDATE { key : httpc_count, value : avg }

MetricValue 타입의 기본 연산은 avg

MetricValue타입 필드의 기본 출력 형태는 avg입니다. 즉, MetricValue 타입의 필드는 별도의 옵션이 지정되지 않으면 avg가 적용됩니다. 아래의 두 쿼리는 같은 결과를 가집니다.

-- avg를 지정하지 않은 경우
CATEGORY app_counter
TAGLOAD
SELECT [time, pcode,pname, tps]
GROUP  {timeunit:5000, pk:pcode, last: pname, merge:tps}
-- avg를 지정한 경우
CATEGORY app_counter
TAGLOAD
SELECT [time, pcode,pname, tps]
GROUP  {timeunit:5000, pk:pcode, last: pname, merge:tps}
UPDATE {key:tps, value:avg}

사전 정의 MXQL 쿼리문

MXQL 쿼리를 직접 작성하지 않고, 사전에 정의된 MXQL 쿼리파일의 경로를 지정하여 MXQL를 수행할 수 있습니다.

예를 들어 '에이전트별 액티브TX 건수, <구간별> 건수, 최근15초’를 구하는 아래와 같은 MXQL 쿼리는 아래와 같습니다.

-- 에이전트별 액티브TX 건수, <구간별> 건수, 최근15초
HEADER {  act0$:I, act3$:I, act8$:I, act$:I}
TIME-RANGE {duration:15s, etime:$etime}
OIDSET {oid:$oid, okind:$okind, onode:$onode}
CATEGORY app_counter

TAGLOAD {backward:true}

SELECT [oid, oname, active_tx_0, active_tx_3, active_tx_8, active_tx_count, pcode]
FIRST-ONLY {key:oid}
RENAME {src:active_tx_0,  dst:act0}
RENAME {src:active_tx_3,  dst:act3}
RENAME {src:active_tx_8,  dst:act8}
RENAME {src:active_tx_count,  dst:act}
CREATE {key:_id_, from:oid}
CREATE {key:_name_, from:oname}

INJECT default

만약 위 쿼리가 수집서버에 등록되어 있다면 다음과 같이 적는 것만으로 같은 데이터를 조회할 수 있습니다. 지정한 경로에 저장된 서버의 파일의 내용을 읽어서 호출해주는 방식입니다.

--  사전 정의된 파일의 path를 입력합니다.
/app/act_tx/act_tx_oid

SaaS 서비스에서 제공하는 사전에 정의된 MXQL 쿼리 목록에서 사용 가능한 쿼리를 확인할 수 있습니다.

참고자료

바인드 변수(파라미터)

MXQL에서는 바인드 변수를 사용할 수있습니다. 바인드 변수는 '$'시작해야 합니다. 또한 value에 해당하는 부분만 사용할 수 있습니다.

SKIP $skip_value
SKIP [$skip_value]
SKIP {value:$skip_value}
-- 불가능한 경우(key로 바인드 변수를 전달할 수 없습니다.)
SKIP {$option:10}

쿼리에서 바인드 변수를 사용했으면 MXQL을 실행할 때 입력할 값을 전달해야 합니다.

mxql 1
Figure 4. 바인드 변수 설정 예시
바인드 변수의 이름은 대소문자 알파멧만 가능합니다. 숫자 및 특수문자는 바인드 변수의 이름에 포함될 수 없습니다.

데이터 로딩방식

MXQL에서 조회할 수 있는 데이터는 메트릭스의 형식에 따라서 크게 두 가지로 나눌 수 있습니다.

  1. 메트릭스의 데이터가 태그와 필드에 나누어서 저장된 데이터 ( TAGLOAD를 사용해서 로드할 수 있는 데이터)

  2. 메트릭스에 모든 데이터가 필드에 저장된 데이터 (FLEXLOAD를 사용해서 로드할 수 있는 데이터)

대부분의 카테고리는 TAGLOAD를 사용합니다. [FLEXLOAD를 사용해야하는 카테고리 목록]에 포함된 카테고리의 데이터를 사용할 때에만 FLEXLOAD를 사용합니다.

SaaS 서비스에서 제공하는 사전에 정의된 MXQL 쿼리 목록

mxql 쿼리를 직접 작성하지 않고 path로 지정할 수 있는 기능의 주된 목적은, 복잡한 쿼리를 간편하게 호출하기 위함이 아니라, 관리자가 직접 본인의 의도대로 쿼리를 작성하고 이를 사용하는데 있습니다. 따라서 이미 Yard에 어떤 쿼리들이 포함되어 있는지 확인하고 사용하기보다 직접 쿼리를 등록하는 방향으로 활용해야 합니다.( JOIN <명령어>를 사용해야하는 경우는 mxql 쿼리를 사용하는 경우 중에서도 특별한 경우이기 때문에 관리자가 직접 쿼리를 등록하고 해당 파일의 path를 사용하도록 되어 있습니다. )

NOTE : yard.conf의 mxql_root에 설정한 경로 아래에 등록하고 싶은 쿼리를 파일을 저장할 수 있습니다. (default ./mxql)

에이전트별 액티브TX 건수, 건수, 최근15초

  • 경로 : /app/act_tx/act_tx_oid

  • 쿼리 :

    HEADER {  act0$:I, act3$:I, act8$:I, act$:I}
    
    TIME-RANGE {duration:15s, etime:$etime}
    
    OIDSET {oid:$oid, okind:$okind, onode:$onode}
    
    CATEGORY app_counter
    
    TAGLOAD {backward:true}
    
    SELECT [oid, oname, active_tx_0, active_tx_3, active_tx_8, active_tx_count]
    FIRST-ONLY {key:oid}
    RENAME {src:active_tx_0,  dst:act0}
    RENAME {src:active_tx_3,  dst:act3}
    RENAME {src:active_tx_8,  dst:act8}
    RENAME {src:active_tx_count,  dst:act}
    
    CREATE {key:_id_, from:oid}
    CREATE {key:_name_, from:oname}

에이전트 별 상세정보 + 에이전트별 액티브TX 건수, 건수, 최근15초

  • 경로 : /app/act_tx/agent_with_tx

  • 쿼리 :

    CATEGORY agent_list
    
    OIDSET {oid:$oid, okind:$okind, onode:$onode}
    
    FLEXLOAD
    
    JOIN {query:'/app/act_tx/act_tx_oid', pk:oid, field:[act0,act3,act8, act] }
    
    UPDATE {key:act0, notnull:0}
    UPDATE {key:act3, notnull:0}
    UPDATE {key:act8, notnull:0}
    UPDATE {key:act, notnull:0}
    
    RENAME {src:[act0, act3, act8, act],  dst:[normal, slow, verySlow, total]}
    
    INJECT default