본문으로 건너뛰기

MXQL 문법 가이드

형식​

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

<명령어> <오퍼랜드>

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

  1. 오퍼랜드가 없는 경우

    TAGLOAD

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

    CATEGORY app_counter

  3. 문자열 배열

    SELECT [ time, pcode ]

  4. JSON 문자열 타입

    FILTER { key : tx_count, value : 5}
Sample MXQL query
CATEGORY app_counter
TAGLOAD
SELECT [ time, pcode ]
FILTER { key : tx_count, value : 5}

테스트 환경​

홈 화면 > 프로젝트 선택 > 사이트맵 > 실험실 > MXQL 데이터 조회 메뉴에서 MXQL 쿼리를 테스트할 수 있습니다.

MXQL 데이터 조회

노트

메트릭스에는 태그와 필드가 구분되어 있지만 MXQL 데이터 조회 메뉴에서는 태그와 필드의 구분 없이 표현합니다.

단계별 구성​

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

  1. 메트릭스 선택: 어떤 에이전트에서 수집한 어떤 메트릭스를 사용할지 선택하세요.

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

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

Example
# 메트릭스 선택 단계
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개만 통과

다음은 메트릭스 가공 단계를 모두 통과한 메트릭스 예시입니다.

예시

주석​

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

Example
# 데이터 조회 설정
CATEGORY app_counter

# 데이터 조회
TAGLOAD

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

MetricValue(복합값)​

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

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

timetx_count
2021/06/24 13:40:001
2021/06/24 13:40:102
2021/06/24 13:40:203
2021/06/24 13:40:304
2021/06/24 13:40:405
2021/06/24 13:40:506

위 데이터를 30초 간격으로 GROUP의 merge 옵션을 진행하면 다음과 같은 형태로 데이터를 변형할 수 있습니다.

timetx_count
2021/06/24 13:40:00 ~ 2021/06/24 13:40:201,2,3에 대한 MetricValue
2021/06/24 13:40:30 ~ 2021/06/24 13:40:504,5,6에 대한 MetricValue

데이터를 MetricValue로 변환하면 총 6가지 옵션을 사용할 수 있습니다.

옵션기능
sumMetricValue에 포함된 값을 더합니다.
minMetricValue에 포함된 값 중 최소값을 구합니다.
maxMetricValue에 포함된 값 중 최대값을 구합니다.
lastMetricValue에 포함된 값 중 마지막에 추가된 값을 구합니다.
avgMetricValue에 포함된 값의 평균을 구합니다.
cntMetricValue에 포함된 값의 갯수를 구합니다.

MetricValue 옵션은 UPDATE 명령어를 통해 이용할 수 있습니다.

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 타입의 데이터 이용 방법​

  • 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 }

  • 수집서버에 데이터를 저장할 때부터 모든 필드에는 MetricValue 형식으로 저장된 카테고리가 있습니다. 사이트맵 > 분석 > 메트릭스 조회 > 카테고리 옵션에는 기본, 5분, 1시간 단위로 선택할 수 있는 카테고리를 확인할 수 있습니다. 여기서 5분 또는 1시간을 선택할 수 있는 카테고리가 MetricValue 형식으로 저장된 카테고리입니다.

    MetricValue 형식으로 설정할 수 있는 카테고리 목록

    5분 또는 1시간을 선택할 수 있는 카테고리의 이름에 {m5} 또는 {h1}을 조합하면 GROUP 명령어의 merge 옵션을 적용하지 않고 바로 UPDATE 명령어의 sum 옵션을 적용할 수 있습니다.

    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 쿼리는 다음과 같습니다.

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

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

/app/act_tx/act_tx_oid

다음 문서에서 사용 가능한 쿼리를 확인할 수 있습니다.

참고자료​

바인드 변수(파라미터)​

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

SKIP $skip_value
SKIP [$skip_value]
SKIP {value:$skip_value}

key로 바인드 변수를 전달할 수 없습니다.

SKIP {$option:10}

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

바인드 변수 설정 예시

노트

바인드 변수의 이름은 대소문자 알파벳만 가능합니다. 숫자 및 특수문자는 바인드 변수의 이름에 포함할 수 없습니다.

데이터 로딩방식​

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

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

대부분의 카테고리는 TAGLOAD를 사용합니다. 다음 문서에 포함된 카테고리의 데이터를 사용할 경우에만 FLEXLOAD를 사용합니다.

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

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

노트

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