View a markdown version of this page

クエリ式の書き込み - Amazon Managed Grafana
式について式の書き込み特殊なケース

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

クエリ式の書き込み

このドキュメントのトピックは、Grafana バージョン 9.x をサポートする Grafana ワークスペース向けです。

Grafana バージョン 12.x をサポートする Grafana ワークスペースについては、「」を参照してくださいGrafana バージョン 12 での作業。

Grafana バージョン 10.x をサポートする Grafana ワークスペースについては、「Grafana バージョン 10 での作業」を参照してください。

Grafana バージョン 8.x をサポートする Grafana ワークスペースについては、「Grafana バージョン 8 での作業」を参照してください。

サーバー側の式を使用すると、演算やその他のオペレーションでクエリから返されるデータを操作できます。式は新しいデータを作成し、データソースから返されるデータを操作しません。

式について

サーバー側の式を使用すると、演算やその他のオペレーションでクエリから返されるデータを操作できます。式は新しいデータを作成し、式のデータを許容できる入力にするためにマイナーなデータ再構築を行う以外は、データソースから返されるデータを操作しません。

式の使用

式は主に Grafana アラートによって使用されます。処理はサーバー側で行われるため、式はブラウザセッションなしで動作できます。ただし、式はバックエンドデータソースや視覚化でも使用できます。

注記

式は、レガシーダッシュボードアラートでは機能しません。

式は、異なるデータソースからのクエリを組み合わせて有効にするか、データソースで使用できない演算を提供することで、データソースを補強することを目的としています。

注記

可能であれば、データソース内でデータ処理を行う必要があります。ストレージから Grafana サーバーにデータをコピーして処理することは非効率であるため、式は軽量データ処理を対象としています。

式は、時系列または数値データを返すデータソースクエリで機能します。また、多次元データでも動作します。例えば、複数の系列を返すクエリでは、各系列がラベルまたはタグで識別されます。

個々の式は 1 つ以上のクエリまたはその他の式を入力として受け取り、結果にデータを追加します。個々の式またはクエリは、RefID と呼ばれる名前付き識別子 (例: デフォルト文字 A または B) である変数で表されます。

個々の式または別の式にあるデータソースクエリの出力を参照するには、この識別子を変数として使用します。

式のタイプ

式は 2 種類のデータで動作します。

  • 時系列のコレクション。

  • 数値のコレクション (各数値は項目)。

各コレクションは、単一のデータソースクエリまたは式から返され、RefID で表されます。各コレクションはセットであり、セット内の各項目は、ラベルまたはキーと値のペアとして保存されるディメンションによって一意に識別されます。

データソースクエリ

サーバー側の式は、バックエンドデータソースのデータソースクエリのみをサポートします。データは一般に、時系列データにラベル付けされているものと見なされます。将来的には、式がエラーをより適切に処理できるように、クエリの戻り値の型 (数値または時系列) データのアサーションを追加する予定でした。

データソースクエリは、式とともに使用されると、式エンジンによって実行されます。これを行うと、データはデータフレームごとに 1 つの時系列または 1 つの数値に再構成されます。例えば、テーブルビューの 1 つのフレームで複数の系列を返すデータソースを使用する場合、式で実行したときに異なるように見えることがあります。

現在、データフレームを使用する場合にサポートされる時系列以外の形式 (数値) は、時間、文字列の列、1 つの数値列のないデータフレームを返すテーブルレスポンスのみです。

Loc ホスト Avg_CPU

MIA

A

1

NYC

B

2

上記の例では、式で動作する数値を生成します。文字列の列はラベルになり、数値列は対応する値になります。例えば、{"Loc": "MIA", "Host": "A"} の値は 1 です。

オペレーション

式には math、reduce、リサンプリング演算を使用できます。

数値演算

Math は、時系列または数値データに関する自由形式の数式です。Math 演算子では、数値と時系列を入力として受け取り、異なる数値と時系列に変更します。

他のクエリまたは式からのデータは、$A などのドル記号のプレフィックスが付いた RefID で参照されます。変数の名前にスペースがある場合は、${my variable} のような中括弧構文を使用できます。

数値定数は、10 進数 (2.24)、8 進数 (072 のような先頭がゼロ)、または 16 進数 (0x2A のような先頭が 0x) にすることができます。指数と記号もサポートされています (例: -0.8e-2)。

演算子

算術演算子 (+、二項および単項 -、*、/、%、指数 **)、リレーショナル演算子 (<、>、==、!=、>=、<=)、論理演算子 (&&、||、および単項 !) がサポートされています。

データに対する演算処理は、数値データか時系列データかによって異なります。

$A + $B や $A || $B などの二項演算では、データのタイプに応じて、演算子は次の方法で適用されます。

  • $A と $B の両方が数値の場合、2 つの数値の間で演算が実行されます。

  • 1 つの変数が数値で、もう 1 つの変数が時系列の場合、時系列の各ポイントの値と数値との間の演算が実行されます。

  • $A と $B の両方が時系列データである場合、2 つの系列の各値間の演算は、$A と $B の両方に存在するタイムスタンプごとに実行されます。Resample 演算を使用してタイムスタンプを並べることができます。

まとめ

  • 数値 OP 数値 = 数値

  • 数値 OP 系列 = 系列

  • 系列 OP 系列 = 系列

式は 1 つの変数で表される複数の系列または数値で動作するため、二項演算は 2 つの変数間の統合 (結合) も実行します。これは、個々の系列または数値に関連付けられた識別ラベルに基づいて行われます。

したがって、$A にある {host=web01} のようなラベルを持つ数値と、同じラベルを持つ $B に別の数値がある場合、各変数内のこれら 2 つの項目間で演算が実行され、結果は同じラベルを共有します。この統合の動作のルールは次のとおりです。

  • ラベルのない項目は、すべてに結合されます。

  • $A と $B の両方に 1 つの項目 (1 つの系列、または 1 つの数値) しか含まれていない場合、それらは結合されます。

  • ラベルが正確な数値演算である場合、それらは結合されます。

  • ラベルが他のサブセットである場合、例えば、$A の項目には {host=A,dc=MIA} ラベルが付けられ、$B の項目には {host=A} ラベルが付けられると結合されます。

  • 項目ごとに異なるタグキーがある $A などの変数内では、結合動作は不定です。

リレーショナル演算子と論理演算子は、偽の場合は 0、真の場合は 1 を返します。

数値演算関数

ほとんどの関数は独自の式の演算にありますが、数値演算関数には、数学演算子や数学記号に似た関数がいくつかあります。関数が数値または系列のいずれかを取ることができる場合、引数と同じタイプが返されます。系列の場合、系列内の各ポイントの値に対して演算が実行されます。

abs

abs は、引数の絶対値を返します。これは、数値または系列です。例えば、abs(-1)、abs($A) などです。

is_inf

is_inf は数値または系列を取得し、Inf 値 (負または正) の 1 と他の値の 0 を返します。例えば、is_inf($A) などです。

注記

例えば、負の無限大を具体的にチェックする必要がある場合は、$A == infn() のような比較を行うことができます。

is_nan

is_nan は数値または系列を取得し、NaN 値の 1 と他の値の 0 を返します。例えば、is_nan($A) などです。この関数は、NaN が NaN と等しくないために存在します。

[is_null]

is_null は数値または系列を取得し、null 値の 1 と他の値の 0 を返します。例えば、is_null($A) などです。

is_number

is_number は数値または系列を取得し、すべての実数値の 1 と他の値 (null、Inf+、Inf-、および NaN) の 0 を返します。例えば、is_number($A) などです。

log

Log は、引数の自然対数を返します。これは、数値または系列です。値が 0 未満の場合、NaN が返されます。例えば、log(-1)、log($A) などです。

[inf、infn、nan、null]

inf、infn、nan、null 関数はすべて、名前の単一の値を返します。これらは主にテスト用です。例えば、null() などです。

round

Round は、丸められた整数値を返します。例えば、round(3.123)、round($A) です。

ceil

Ceil は、数値を最も近い整数値に切り上げます。例えば、ceil(3.123) は 4 を返します。

floor

Floor は、数値を最も近い整数値に切り下げます。例えば、floor(3.123 は 3 を返します。

[削減]

Reduce は、クエリまたは式から返される 1 つ以上の時系列を取得し、各系列を 1 つの数値に変換します。時系列のラベルは、それぞれ出力される削減された数値のラベルとして保持されます。

[フィールド]

  • [関数] – 使用する削減関数

  • [入力] – リサンプリングする変数 (refID (A など))

  • [モード] – 系列に数値以外の値が含まれている場合、削減関数の制御動作を許可します (null、NaN 、+-Inf)

削減関数

Count

Count は、各系列内のポイント数を返します。

Mean

Mean は、各系列のすべての値の合計を、その系列のポイント数で割った値を返します。strict モードでは、系列内の値が null または nan の場合、または系列が空の場合、NaN が返されます。

[最小 と 最大]

最小 と 最大は、系列内の最小値または最大値をそれぞれ返します。strict モードでは、系列内の値が null または nan の場合、または系列が空の場合、NaN が返されます。

Sum

Sum は、系列のすべての値の合計を返します。系列の長さがゼロの場合、合計は 0 になります。strict モードでは、系列内の値に NaN または Null がある場合、NaN が返されます。

Last

Last は、系列内の最後の数値を返します。系列に値がない場合は、NaN を返します。

制限モード

Strict

Strict モードでは、入力系列はそのまま処理されます。系列内の値が数値以外の場合 (null、NaN、または +-Inf)、NaN が返されます。

Drop Non-Numeric

このモードでは、入力系列内のすべての非数値 (null、NaN、または +-Inf) は、制限関数を実行する前に除外されます。

Replace Non-Numeric

このモードでは、数値以外の値はすべて事前定義された値に置き換えられます。

[リサンプリング]

リサンプリングでは、各時系列のタイムスタンプが一貫した時間間隔になるように変更されます。主なユースケースは、同じタイムスタンプを共有しない時系列をリサンプリングして、それらの間で演算を実行できるようにすることです。これは、2 つの系列をそれぞれリサンプリングし、リサンプリングされた変数を参照する Math 演算で行うことができます。

[フィールド]

  • [入力] – リサンプリングする時系列データの変数 (refID (A など))

  • [リサンプリング先] – リサンプリング先となる期間は、例えば、10s. 単位は s 秒、m 分、h 時間、d 日、w 週、y 年です。

  • [ダウンサンプリング] – ウィンドウサンプルごとに複数のデータポイントがある場合に使用する制限関数。動作の詳細については、「制限関数」を参照してください。

  • [アップサンプリング] – データポイントがないウィンドウサンプルを埋めるために使用するメソッド。

    • pad で最後の既知の値に置換

    • backfill で次の既知の値に置換

    • fillna で空のサンプルウィンドウを NaN に置換

式の書き込み

データソースがサポートしている場合、Grafana は [式] ボタンを表示し、クエリエディタリストに既存の式を表示します。

式を記述するには

  1. パネルを開きます。

  2. クエリの下で、[式] を選択します。

  3. [演算] フィールドで、書き込む式のタイプを選択します。

  4. 式を書き込みます。

  5. [適用] を選択します。

特殊なケース

クエリされたデータソースが系列や数値を返さない場合、式エンジンは NoData を返します。例えば、式によってマージされた 2 つのデータソースクエリがリクエストに含まれている場合、NoData が少なくとも 1 つのデータソースクエリによって返された場合、クエリ全体で返される結果は NoData になります。Grafana アラートが NoData 結果を処理する方法の詳細については、「データがない場合やエラーが発生した場合の対処」を参照してください。