Monitoring Query Language (MQL)リファレンス

Monitoring Query Language (MQL)式の構文を理解し、MQL式の間隔、統計および述語演算子の有効な値を確認します。

MQLの編集の詳細は、問合せのMQL式の編集を参照してください。過去1時間などの特定の時間範囲を取得するには、「問合せのデフォルト以外の時間範囲の選択」を参照してください。

MQL構文

MQL構文は、モニタリング・サービスに公開されているメトリックを問い合せるための式を制御します。MQL式は問合せ(アラーム問合せを含む)を定義します。MQLは集計データを処理します。

次の図は、必要なコンポーネントと一般的なオプション・コンポーネントを示しています。

ノート

一部のコンポーネントは、MQL式に複数回出現できます。たとえば、2つのグループ化関数を使用できます(groupBy()、統計、grouping()の順など)。問合せをネストすることもできます。

1つの問合せに複数の問合せを結合することもできます。

コンソールのアラームの場合、absent()統計が「演算子」の下にリストされます。不在アラームの作成を参照してください。

コンソールでのabsent()の詳細

コンソールでabsent()統計を選択するには、次のページ固有の手順を参照してください。

「アラームの作成」または「アラームの編集」ページ: 基本モードで、「トリガー・ルール」の下の「演算子」から「不在」を選択します。拡張モード(「アドバンスト・モードに切り替え」を選択)で、MQL式を更新します。
「メトリック・エクスプローラ」ページ: 「拡張モード」を選択してMQLを使用します。
「サービス・メトリック」ページ: 「メトリック・エクスプローラ」で問合せをオープンし、「拡張モード」を選択してMQLを使用します。

構文図の読込みの詳細は、構文図を読むを参照してください。

MQL式に有効な値

MQL式の間隔演算子、統計演算子および述語演算子の有効な値を確認します。

間隔

ノート

間隔とともに、レゾリューションおよび時間範囲を考慮します。

間隔でサポートされる値は、メトリック問合せで指定された時間範囲によって異なります(アラーム問合せには適用されません)。時間範囲が小さくなるほど、多くの間隔値がサポートされます。たとえば、時間範囲に1時間を選択すると、すべての間隔値がサポートされます。時間範囲に90日を選択した場合、1時間から1日の間の間隔値のみがサポートされます。

メトリックが発行される頻度に基づいてアラーム間隔を選択します。たとえば、5分ごとに発行されるメトリックには、5分以上のアラーム間隔が必要です。ほとんどのメトリックは1分ごとに発行されるため、任意のアラーム間隔がサポートされます。特定のメトリックに対して有効なアラーム間隔を決定するには、関連するサービスのメトリック参照を確認します。

例: 1分間隔(1m)

CpuUtilization[1m].mean()

MQL式の有効な間隔は次のとおりです: 1m-60m、1h-24h、1d

手順については、問合せの間隔の選択を参照してください。

ノート

メトリック問合せの場合、選択した間隔によってリクエストのデフォルトのレゾリューションが駆動され、これによって返されるデータの最大時間範囲が決定されます。

アラームの問合せの場合、指定した間隔はリクエストのレゾリューションに影響しません。アラーム問合せリクエストのレゾリューションで有効な値は、1mのみです。アラーム問合せに使用されるレゾリューションのパラメータの詳細は、アラームを参照してください。

問合せで戻される最大時間範囲

メトリック問合せで返される最大時間範囲は、レゾリューションによって異なります。メトリック問合せの場合、デフォルトでは、レゾリューションは問合せ間隔と同じです。

最大時間範囲は、指定された終了時間に関係なく現在の時間を使用して計算されます。コンソール(基本モード)で選択できる各間隔で返される最大時間範囲は、次のとおりです。

間隔	デフォルトのレゾリューション(メトリック問合せ)	戻される最大時間範囲
1分自動(「サービス・メトリック」ページ)*、選択した期間が6時間以下の場合	1分	7日
5分自動(「サービス・メトリック」ページ)*、選択した期間が6時間を超え36時間未満の場合	5分	30日
1時間自動(「サービス・メトリック」ページ)*、選択した期間が36時間を超える場合	1時間	90日
1日	1日	90日

* 「間隔」に「自動」(「サービス・メトリック」ページのみ)を選択すると返される最大時間範囲は、自動間隔の選択によって決まります。自動間隔の選択は、選択した期間に基づきます。

間隔とは異なるデフォルト以外の解像度を指定するには、問合せに対するデフォルト以外の解像度の選択を参照してください。

返されるデータの例1: 現在の時間までの1分間隔およびレゾリューションで、1月8日10:00に送信されました。レゾリューションまたは終了時間の指定がないため、デフォルトで1mの間隔値がレゾリューションに設定され、終了時間が現在の時間(2023-01-08T10:00:00.789Z)に設定されます。このリクエストは、最大7日間のメトリック・データを返します。この7日の期間内で可能な最初のデータ・ポイントは、1月1日の10:00 (2023-01-01T10:00:00.789Z)です。
返されるデータの例2: 2日前までの5分間隔と1分のレゾリューションで、1月8日10:00に送信されました。レゾリューションによって最大時間範囲が決定されるため、最大7日間のメトリック・データ・ポイントが戻されます。指定した終了時間は1月6日の10:00 (2023-01-06T10:00:00.789Z)でしたが、この7日の期間内で可能な最初のデータ・ポイントは1月1日の10:00 (2023-01-01T10:00:00.789Z)になります。したがって、この例では、5日間のメトリック・データ・ポイントのみを戻すことができます。

統計

統計は、指定された間隔でRAWデータ・ポイントのセットに適用される集計関数です。

例: 平均統計

CpuUtilization[1m].mean()

手順については、問合せの統計の選択を参照してください。

次に有効な統計を示します。

統計(MQL式)	統計オプション(コンソールの基本モード)	説明
`absent()`	(不在演算子を参照)	不在述語。メトリックが間隔全体に存在しない場合は、true (1)を返します。間隔中にメトリックが存在する場合は、false (0)を返します。不在検出期間後に無視され、値は生成されません。デフォルトの休暇欠勤検出期間は2時間です。休暇欠勤アラームを作成または更新するときに、この期間をカスタマイズできます。アラーム問合せの休暇欠勤検出期間のカスタマイズを参照してください。有効な値の範囲は、1分(`1m`)から3日(`3d`または`72h`)です。数値および単位(分、時間または日の場合は`m`、`h`または`d`)を使用して、休暇欠勤検出期間の時間を指定します。この統計は、基本的な問合せと不在アラームで使用します。問合せでの述語の指定を参照してください。
`avg()`	(使用できません)	指定された間隔中の合計を件数で割った値を返します。`mean()`と同じです。
`count()`	数	指定された間隔内に受信した観測データの数を返します。
`first()`	(使用できません)	間隔ごとに、指定された間隔内で最も古いタイムスタンプを持つ値を返します。
`increment()`	(使用できません)	間隔ごとの変更を返します。
`last()`	(使用できません)	間隔ごとに、指定された間隔内で最新のタイムスタンプを持つ値を返します。
`max()`	最大	指定した間隔中に観測された最大値を返します。
`mean()`	平均	指定された間隔中の合計を件数で割った値を返します。
`min()`	最小	指定した間隔中に観測された最小値を返します。
`percentile(p)`	P50 P90 P95 P99 P99.9 (「サービス・メトリック」ページのみ)	指定された間隔で、指定されたパーセンタイル(SDK、CLIまたはAPIを使用している場合は`p`)の推定値を返します。有効な値は0.0より大きく1.0未満です。たとえば、`percentile(0.8)`は、80パーセンタイルの値を返します。
`rate()`	速度	変更の間隔ごとの平均レートを返します。単位は秒です。
`sum()`	合計	間隔ごとに合計されたすべての値を返します。

述語演算子

述語コンポーネントは、メトリック・ストリームから指定された値のみを保持します。述語演算子を使用して、しきい値または不在を定義します。

例1: 平均CPU使用率の80%より大きい

CpuUtilization[1m].mean() > 80

例2: 平均CPU使用率が60から80パーセントの間

CpuUtilization[1m].mean() in (60, 80)

例3: エラーの場合は1より大きい

ServiceConnectorHubErrors[1m].count() > 1

例4: 90百分位数CPU使用率が85を超える(可用性ドメインの選択とプールごとのグループ化)

CpuUtilization[1m]{availabilityDomain = "VeBZ:PHX-AD-1"}.groupBy(poolId).percentile(0.9) > 85

例5: 最小CPU使用率が20以上("ol8"または"ol7"のいずれかを選択)

CpuUtilization[1m]{resourceDisplayName =~ "ol8|ol7"}.min() >= 20

例6: 最小CPU使用率が30以上(instance-2023- で始まるインスタンス名の選択)

CpuUtilization[1m]{resourceDisplayName =~ "instance-2023-*"}.min() >= 30

例7: 「Absence of CPU Utilization Metrics for Specified Resource、 set to 20 hours for absence detection period」

CpuUtilization[1m]{resourceId = "<resource_identifier>"}.groupBy(resourceId).absent(20)

absent()の説明: 間隔全体でメトリックが存在しない場合、true (1)を返します。間隔中にメトリックが存在する場合は、false (0)を返します。不在検出期間後に無視され、値は生成されません。

手順については、問合せでの述語の指定を参照してください。

次に有効な演算子を示します。

演算子(MQL式)	「演算子」オプション(コンソールの基本モード)	コメント
`>`	次より大きい
`>=`	次以上
`==`	次と等しい
`=~`	(使用できません)	Fuzzy Matching
`!=`	(使用できません)	次と等しくない。
`<`	次より小さい
`<=`	次以下
`in`	範囲内(指定値を含む)	指定された2つの値を含む。
`not in`	範囲外(指定値を含む)	指定された2つの値を含む。
(absent()統計を参照)	不在	不在述語。メトリックが間隔全体に存在しない場合は、true (1)を返します。間隔中にメトリックが存在する場合は、false (0)を返します。不在検出期間後に無視され、値は生成されません。デフォルトの休暇欠勤検出期間は2時間です。休暇欠勤アラームを作成または更新するときに、この期間をカスタマイズできます。アラーム問合せの休暇欠勤検出期間のカスタマイズを参照してください。有効な値の範囲は、1分(`1m`)から3日(`3d`または`72h`)です。数値および単位(分、時間または日の場合は`m`、`h`または`d`)を使用して、休暇欠勤検出期間の時間を指定します。この統計は、基本的な問合せと不在アラームで使用します。問合せでの述語の指定を参照してください。

アラーム手順については、しきい値アラームの作成および不在アラームの作成を参照してください。

算術演算子

MQL式では、次の算術演算子がサポートされています。

演算子	説明
`+`	追加
`-`	減算
`*`	乗算
`/`	値
`%`	モジュロ(除算およびリターン残り)

問合せの結合

&& (AND)および|| (OR)演算子を使用して、問合せを結合します。複数の結合問合せは、単一の問合せとして機能します。

ノート

&& (AND)および|| (OR)演算子は、問合せ間でのみ使用できます。ディメンション・セット間では使用しないでください。たとえば、次の問合せは無効です: CpuUtilization[1m]{faultDomain =~ "FAULT-DOMAIN-1|FAULT-DOMAIN-2" || resourceDisplayName = "test"}.mean()

結合演算子	説明
`&&`	AND: 問合せの結合。両方のオペランドがtrueの場合にtrueを返します。それ以外の場合はfalseを戻します。
`\|\|`	OR: 問合せの結合。いずれかのオペランドがtrueの場合、または両方のオペランドがtrueの場合にtrueを返します。それ以外の場合はfalseを戻します。

例1: ORを使用した問合せの結合CPU使用率データ・ポイントがフォルト・ドメイン1または2にある場合、またはメモリー使用率データ・ポイントがフォルト・ドメイン1または2にある場合はtrueを返します。

CpuUtilization[1m]{faultDomain =~ "FAULT-DOMAIN-1|FAULT-DOMAIN-2"}.mean() || MemoryUtilization[1m]{faultDomain =~ "FAULT-DOMAIN-1|FAULT-DOMAIN-2"}.mean()

例2: ANDを使用したアラーム問合せの結合両方の問合せがtrueの場合にのみアラームをトリガー(起動状態への移行): 少なくとも1つのエラーが存在し、平均エラーが半分より大きい場合。

ServiceConnectorHubErrors[1m].count() > 1 && ServiceConnectorHubErrors[1m].mean() > 0.5

例3: ANDを使用したアラーム問合せの結合両方の問合せがtrueの場合にのみアラーム(起動状態への移行)をトリガーします。小さい読取り(0から8KB)の場合、リクエストの50パーセンタイルが100を超え、平均レイテンシが0.01未満です。

FileSystemReadRequestsBySize[5m]{resourceType = "filesystem", size = "0B_to_8KiB"}.percentile(.50) > 100 && FileSystemReadAverageLatencybySize[5m]{resourceType = "filesystem", size = "0B_to_8KiB"}.mean() > 0.01

ファジー・マッチ

MQL式のディメンション値に対する近似(ファジー)一致を指定します。

ディメンション名に複数の値を指定する場合は、あいまい一致を使用します。

一連の値の前に等号(=)のかわりに、次の比較演算子を使用します。

比較演算子	説明
`=~` (等号の後にチルダが続く)	ほぼ同じ。ファジー・マッチングの使用

ファジー・マッチングの場合、値のセットをname = "val*"またはname = "value1|value2"のように引用符で囲みます

次の文字の1つ以上を使用して、値のセットを更新します。

値のファジー・マッチング文字	説明
`*` (asterisk)	ゼロから多数の文字を示すワイルドカード。
`\|`(pipe)	ディメンション値のORオペランド。

2つの使用可能なリソース名("ol8"または"ol7")のあいまい一致を示す例:

CpuUtilization[1m]{resourceDisplayName =~ "ol8|ol7"}.min() >= 20

「instance-2023- 」というフレーズを含むリソース名のあいまい一致を示す例:

CpuUtilization[1m]{resourceDisplayName =~ "instance-2023-*"}.min() >= 30

3つのディメンション値セット(myshapeシェイプを使用するフォルト・ドメイン1のテスト・コンピュート・インスタンス)に対するファジー・マッチングを示す例:

CpuUtilization [1m]{faultDomain =~ "FAULT-DOMAIN-1", resourceDisplayName =~ "test*", shape =~ "myshape"}.mean()

Oracle Cloud Infrastructureドキュメント