MXQL文法ガイド

形式

MXQLは、各行ごとにコマンドとオペランドで構成され、スペースで区切られています。

<コマンド> <オペランド>

コマンドは、１つの単語からなる予約語です。コマンドは大文字で入力し、オペランドは小文字で入力します。コマンドごとに入力可能なオペランドの形式は決まっています。オペランドには4種類のタイプの値があります。

オペランドがない場合
```
TAGLOAD
```
文字列(数字または単語)
```
CATEGORY app_counter
```
文字列配列
```
SELECT [ time, pcode ]
```
JSON文字列型
```
FILTER { key : tx_count, value : 5}
```

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

テスト環境

ホーム画面 > プロジェクト選択 > サイトマップ > Labs > MXQL DataメニューからMXQLクエリをテストできます。

MXQLデータ参照

ノート

メトリクスにはタグとフィールドが区分されますが、MXQLデータ照会メニューでは、タグとフィールドを区別せずにメトリックが表示されます。

段階別構成

MXQLは、段階的な設定があります。各ステップで使用できるコマンドには特定の種類があり、各ステップの名前と特性はは次のとおりです。

メトリクスの選択：使用するエージェントによって収集されるメトリクスを選択します。
メトリクス読み込み：前の段階で設定した値を使用してメトリクスを読み込みます。ほとんどの場合はTAGLOADを使用し、特別な場合は、FLEXLOADを使用します。FLEXLOADを使用する必要がある場合は、次の文書を参照してください。
メトリック加工：前の段階でインポートされたメトリクスに対して、段階的に処理を実行します。

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(複合値)

Metric Value(複合値)は、メトリクス処理ステップで良く使用される操作を便利にサポートするMXQLのデータ構造です。メトリクス処理ステップのGROUP、UPDATEコマンドは、メトリクスがMetricValue形式で保存されている場合のみ使用できます。

例えば、次のようなデータがあるとします。

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	５
2021/06/24 13:40:50	6

データを30秒間隔でGROUPのmergeオプションを継続すると、次の形式でデータを変換することができます。

time	tx_count
2021/06/24 13:40:00 ~ 2021/06/24 13:40:20	1、2、3に対するMetric Value
2021/06/24 13:40:30 ~ 2021/06/24 13:40:50	4、5、6に対するMetric Value

データをMetricValueに変換する場合、合計6つのオプションが使用できます。

オプション	機能
sum	MetricValueに含まれる、値を追加します。
min	MetricValueに保存されている最小値を検索します。
max	MetricValueに含まれる、最大値を検索します。
last	MetricValueに含まれる、最後の値を取得します。
avg	MetricValueに含まれる値の平均を求めます。
cnt	MetricValueに含まれる値の数を検索します。

MetricValueオプションは、UPDATE コマンドで使用することができます。

UPDATE
CATEGORY app_counter
TAGLOAD
SELECT [ time, okindName, okind, apdex_satisfied, apdex_tolerated, apdex_total]
-- GROUPコマンドのmergeオプションを使用してMetric Valueに変換する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オプションを使用してMetric Valueに変換する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形式で保存されたカテゴリです。

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が適用します。次の2つのクエリの結果は同じです。

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で照会できるデータは、メトリクスの形式に応じて、2つのタイプに分けることができます。

メトリクスのデータをタグとフィールドに分けて保存されたデータ(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

形式​

テスト環境​

段階別構成​

コメント​

MetricValue(複合値)​

MetricValueタイプのデータ使用方法​

MetricValue型の基本演算avg​

定義済みのMXQLクエリ文​

参照資料​

バインド変数(パラメータ)​

データの読み込み方式​

SaaSサービスで提供する事前定義されたMXQLクエリの一覧​

エージェント別アクティブTX数、件数、直前15秒間​

エージェント別の詳細情報 & エージェント別アクティブTX数、件数、直前15秒間​

形式