DataPrime クエリでクエリ・パラメータを使用する

IBM® Cloud Logs DataPrime $p 変数を使用すると、 DataPrime クエリに変数を組み込んで、カスタムダッシュボードや時間関連のパラメータを作成できます。

この機能は、変数をあたかもクエリに直接記述したかのように外部化します。 これにより、ユーザー定義の入力や文脈に応じたデータの取り扱いが可能になり、フィルタリング、計算、視覚化の柔軟性が高まります。

$p の仕組みは？

  • $p ウィジェット、クエリ、ダッシュボードのタイムピッカーなどの外部フィルタで使用できるクエリパラメータを表します。

  • $p は、手動でクエリを修正することなく、動的なフィルタリングやその他のアクションを可能にします。

  • ユーザーはダッシュボードでこれらのパラメーターを渡したり、操作したりすることができる。

クエリパラメータの定義

カスタムダッシュボードを構成するときや、 ログビューでクエリを作成するときに、 $p 変数を使用できます。

カスタム・ダッシュボード

カスタムダッシュボードで変数が作成されると、ユーザーが選択した変数値は、 $p.<variable_name> を使用して、 DataPrime クエリのクエリパラメータとして反映されます。

カスタム・ダッシュボードの変数は文字列またはマルチ文字列値として扱われるため、数値変数を直接定義することはできません。 数値変数は、例えば filter duration > $p.minDuration のようにクエリで使用することができます。

ログ

ログビューでは、 $p.timeRange.* を使って、 $p を使って、 DataPrime クエリで時間計算を行うことができる。

時間関連パラメータ

時間関連のパラメータは自動的に作成される。 カスタムダッシュボードおよびログビューで timeRange を使用して、UI タイムピッカーで決定されたタイムウィンドウからデータを取得できます。

時間関連のパラメーターは以下の通り：

$p.timeRange.startTime
UIタイムピッカーの開始時間（例えば、 2024-03-06T08:00:00Z ）
$p.timeRange.endTime
UIタイムピッカーの終了時刻 (例: 2024-03-06T12:00:00Z )

クエリ・パラメータの使用例

以下のセクションでは、 $p の使用例を示す。

単一値変数の操作

以下のクエリー例では、 == で示されるように、単一値変数を組み込んでいます。

source logs
| filter cluster_name == $p.cluster

これは、 cluster_name がユーザー定義の単一値変数 $p.cluster にマッチするログをフィルターする。

ユーザーは、カスタムダッシュボードのUIを使用して、この値を動的に変更することができます。

複数選択変数の操作

マルチセレクション変数は、ユーザーが1つのパラメータに複数の潜在的な値を渡すことができます。

任意の値」選択の処理

ユーザーが "any value "を選択した場合、システムはこれを null、フィルターが無視されたものとして扱う。

source logs
| filter $p.clusters == null || $p.clusters.arrayContains($d.clusterId)

もしユーザーが $p.clusters に "any value "を選択した場合、それはnullとして扱われ、フィルターは取り除かれる。 そうでない場合は、 $d.clusterId が $p.clusters の選択された値の範囲内に存在することを確認する。

静的な値のリスト

静的な値のリスト（例えば、1、5、10、30、60）を持つ minDurationSeconds 変数を作成する。 これらの値は文字列として扱われるが、クエリー内では以下のように数値として使用できる：

source logs
| filter duration ≥ $p.minDuration:number

変数を使った動的な groupby フィールドの定義

動的変数を使用することで、 groupby 、ユーザー定義の条件に基づいてクエリを適応させることができ、より柔軟なデータ集計と分析が可能になる。 次のクエリは、 $p.myGroupByVar 変数で指定されたフィールドに基づいてデータをグループ化し、各グループの出現回数をカウントして結果を集計する。

groupby $d[$p.myGroupByVar] calculate count()

これは groupby $p.my_group_by_variable calculate count() とは異なる。 変数は文字列なので、このクエリを実行することは、実質的に groupby 'my_value' calculate count() と同じである。つまり、静的な文字列に対して groupby を実行し、すべての結果を my_value という1つのグループに集約する。

特定の時間範囲内のログをフィルタリングする

これは、期間フィールドが $p.minDuration 以上であることを保証しながら、指定された時間範囲内のログをフィルタリングする。

source logs between $p.timeRange.startTime and $p.timeRange.endTime
| filter duration >= $p.minDuration

四捨五入

この例では、期間に基づいてログをフィルタリングする前に、時間範囲を最も近い1時間に調整する。 時間計算は $p.timeRange.* を使って行うことができる。

source logs between $p.timeRange.startTime/1h and $p.timeRange.endTime/1h+1h
| filter duration >= $p.minDuration

同じ時間枠の先週のデータに加わる

join コマンドを使用して、以下のクエリでサブシステムごとのログ数を結合し、本日からちょうど1週間前のログ数と比較します。

source logs
| groupby $l.subsystemname calculate count() as cnt
| join (source logs timeshifted -7d
        | groupby $l.subsystemname calculate count() as cnt) using subsystemname into a_week_before

この冗長な例は、必要であれば、時間範囲をもっとコントロールする方法を提供する。

source logs
| groupby $l.subsystemname calculate count() as cnt
| join (source logs between $p.timeRange.startTime-7d and $p.timeRange.endTime-7d
        | groupby $l.subsystemname calculate count() as cnt) using subsystemname into a_week_before