在 DataPrime 查詢中使用查詢參數

IBM® Cloud Logs DataPrime $p 變數可讓您在 DataPrime 查詢中加入自訂儀表板和時間相關參數的變數。

此功能可將變數外部化，就像直接寫入查詢一樣。 透過允許使用者定義輸入和上下文資料處理，可提高篩選、計算和視覺化的彈性。

$p 如何運作？

  • $p 代表可在 widget、查詢和外部篩選器（例如儀表板時間選擇器）中使用的查詢參數。

  • $p 可進行動態過濾和其他動作，而不需要手動修改查詢。

  • 使用者可以在儀表板中傳遞和操作這些參數。

定義查詢參數

設定自訂儀表板以及在日誌檢視中建立查詢時，可以使用 $p 變數。

自訂儀表板

在自訂儀表板中建立變數後，使用者選擇的變數值就會反映為 DataPrime 查詢中的查詢參數，使用 $p.<variable_name>。

自訂儀表板中的變數會被視為字串或多重字串值，這表示無法直接定義數字變數。 數值變數可在查詢中使用，例如 filter duration > $p.minDuration。

日誌

在日誌檢視中，您可以使用 $p.timeRange.* 在 DataPrime 查詢中進行時間計算，$p，讓您可以從 UI 時間選擇器所決定的時間視窗中取得資料來源。

時間相關參數

與時間相關的參數會自動建立。 您可以在自訂儀表板和日誌檢視中使用 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 吻合的記錄。

使用者可以使用自訂儀表板使用者介面動態修改此值。

使用多重選擇變數

多重選擇變數可讓使用者在單一參數中傳遞多個潛在值。

處理「任何值」選擇

當使用者選擇「任何值」時，系統會將其視為 null，意即忽略篩選條件。

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

如果使用者為 $p.clusters 選擇「任何值」，它會被視為 null，移除篩選條件。 否則，篩選程式會確保 $d.clusterId 存在於 $p.clusters 的選定值範圍內。

靜態值清單

建立 minDurationSeconds 變數，其中包含靜態的值清單 (例如：1、5、10、30、60)。 這些值會以字串形式處理，但可以在查詢中以數字形式使用，如下所示：

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。

篩選特定時間範圍內的日誌

這會過濾指定時間範圍內的記錄，同時確保持續時間欄位大於或等於 $p.minDuration。

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

四捨五入到最接近的小時

此範例先將時間範圍調整為最接近的整小時，然後再根據持續時間篩選記錄。 任何時間計算都可以使用 $p.timeRange.*。

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

結合上周相同時段的資料

使用 join 指令，以下查詢會連接並比較每個子系統從今天開始的日誌數量，以及剛好一周前的日誌數量。

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