公式運算子及函數

公式編輯器中所使用之公式運算子及函數的參照（包括範例）。

衍生屬性值是根據相同資料來源中的常數及其他屬性值，對表示式求值的結果。表示式文法是正常的數學表示式 - 運算元運算子運算元，括號用於分組。您可以使用一般數學運算子，將數值屬性與其他數值屬性或常數結合：+ - * / 和 %，其將左運算元乘以 100 並除以右運算元。使用 + 可以將字串屬性與其他字串屬性或常數結合在一起。您亦可以使用下列說明的函數。函數以下列格式輸入：function_name(argument_1, argument_2, argument_3)。

屬性以其名稱代表 (於「資料來源」資訊樹狀結構中顯示的名稱相同）。整數常數會指定為數字。字串常數會以引號括住。

您可以在公式中使用下列函數：

abs

傳回數字的絕對值

atof

將字串轉換為浮點數值

atoi

將字串轉換為整數值。它的運作方式與一般 C atoi 的運作方式相同：它在第一個非十進位字元處停止。

average

傳回單一值，是一組值的平均值。這組值來自函數的引數。可提供分別位於個別引數中的數個個別值 (例如屬性名稱或常數)。或 last 函數可以是此函數的唯一引數 (以計算最近屬性值的平均值)。

使用中的此函數的範例為：

average (Attr_A, AttrB, Attr_C)

average (last (Attr_A, 10))

ceiling

傳回不小於引數的最小整數。

例如，如果 attribute_a = 12.4，則 ceiling(attribute_a) 會傳回值 13。如果 attribute_a = -12.4，則 ceiling(attribute_a) 會傳回值 -12。

delta

屬性最新值與該屬性先前所收集值之間的差異。 delta 的單一引數必須是 last 函數，其會取得屬性的現行值及先前值。一般使用可能類似如下：

delta (last(OtherAttribute, 2))

如需使用前一個函數中的哪些屬性值來計算 delta 的相關資訊，請參閱間隔特定計算。此函數僅適用於衍生屬性，而不適用於屬性群組過濾器。

floor

傳回不大於引數的最大整數。

例如，如果 attribute_a = 12.4，則 floor(attribute_a) 會傳回值 12。如果 attribute_a = -12.4，則 floor(attribute_a) 會傳回值 -13。

getenv

傳回所提供環境的值或「配置變數」的值。

ipAddressToName

將 IP 位址轉換為主機名稱。此函數需要一個引數、帶點十進位表示法的 IP 位址字串。如果無法解析位址，則會傳回 IP 位址。

itoa

將整數轉換為字串。當您想要將數值連成字串時，此函數非常有用。衍生的字串 + 函數只使用兩個字串引數。

last

傳回值清單，以供 min、max、average、stddev、rate 及 delta 函數使用。它具有兩個引數：要收集的屬性，以及計算中要使用的值數目。如果需要的屬性是字串屬性的整數值，則第一個引數可以包含 atoi 函數，例如 atoi(numericalStringAttribute)。第二個引數必須是數值。它可以作為常數寫在程式中，或它可以是 atoi(getenv("ENV_VAR")) 表示式的結果。但它不能參照屬性值。

使用中的此函數的範例為：

average (last (Attr_A, 10))

last (Attribute_A, ${K01_NUM_COLLECTIONS}))

限制：您只能在特定公式中使用 last 函數一次。

matches

傳回布林值 true 或 false，指出正規表示式是否符合值。它採用兩個引數，字串來源及正規表示式，字串將與正規表示式結果進行比較。此函數對於過濾屬性群組有協助。

max

傳回一組值當中，最大的單一值。這組值來自函數的引數。可提供分別位於個別引數中的數個個別值 (例如屬性名稱或常數)。或 last 函數可以是此函數的唯一引數 (以計算最近屬性值的最大值)。

min

傳回一組值當中，最小的單一值。這組值來自函數的引數。可提供分別位於個別引數中的數個個別值 (例如屬性名稱或常數)。或 last 函數可以是此函數的唯一引數 (以計算最近屬性值的最小值)。

nameToIpAddress

將主機名稱轉換為 IP 位址。此函數需要一個引數，即主機名稱字串。如果無法解析位址，則會傳回主機名稱。

NetWareTimeToTivoliTimestamp

將 Novell NetWare 十六進位時間值轉換為 Tivoli® Monitoring 時間戳記。此函數需要一個引數，即特殊 NetWare 十六進位時間值。屬性類型為時間戳記。

rate

屬性最新值與該屬性先前所收集值之間的變更率（每秒）。 rate 的單一引數必須是 last 函數，其會取得屬性的現行值及先前值。一般使用可能類似如下：

rate (last(OtherAttribute, 2))

如需使用前一個函數中的哪些屬性值來計算 rate 的相關資訊，請參閱間隔特定計算。此函數僅適用於衍生屬性，而不適用於屬性群組過濾器。

replaceFirst

將第一個符合正規表示式的子字串替換成取代字串。此函數帶三個引數。第一個引數：輸入字串。第二個引數：正規表示式，用來比對輸入字串中的子字串。第三個引數：取代字串。請參閱（ICU 正規表示式），以取得有關取代字串中允許的正規表示式和替代值的詳細資料。

replaceAll

將所有符合正規表示式的子字串替換成取代字串。此函數帶三個引數。第一個引數：輸入字串。第二個引數：正規表示式，用來比對輸入字串中的子字串。第三個引數：取代字串。請參閱（ICU 正規表示式），以取得有關取代字串中允許的正規表示式和替代值的詳細資料。

round

在數學上，將數值四捨五入為最接近的整數。

sqrt

傳回數值的平方根

stddev

傳回單一值，此值是一組值的標準差。這組值來自函數的引數。可提供分別位於個別引數中的數個個別值 (例如屬性名稱或常數)。或 last 函數可以是此函數的唯一引數 (以計算最近屬性值的標準偏差)。

StringToTivoliTimestamp

將日期與時間字串轉換為 Tivoli Monitoring 時間戳記。此函數需要兩個引數。第一個引數是時間戳記的開放式字串表示法。第二個引數是格式字串，該字串可識別如何剖析時間戳記的開放式字串表示法。 (表 1) 說明有效的格式參數。屬性類型為時間戳記。

表 1. StringToTivoliTimestamp 的有效格式參數
符號	意義	格式	範例
`y`	年	`yy` `yyyy`	`96` `1996`
`M`	月註：僅支援英文月字串。	`M` 或 `MM` `MMM` `MMMM`	`09` `Sept` `九月`
`d`	`天`	`d` `dd`	`2` `02`
`E`	星期幾註：僅支援英文星期幾字串。	`EE` `EEE` `EEEE`	`星期六` `Sat` `星期六`
`h`	AM 或 PM (1-12) 制的小時	`hh`	`07`
`H`	一天中的小時 (0-23)	`HH`	`00`
`m`	一小時中的分鐘數	`mm`	`04`
`s`	一分鐘中的秒數	`ss`	`05`
`S`	毫秒	`S` `SS` `SSS`	`2` `24` `245`
`a`	AM 或 PM 標記	`a` 或 `aa`	`am`
全部其他 ASCII 字元	跳過此字元	`-`（連字號）（空格） `/` （正斜線） `:`（冒號） `*`（星號） `,`（逗點）

表 2提供時間戳記之字串表示法的範例及用來剖析它們的格式字串。

表 2. StringToTivoliTimestamp 範例. 列出及解釋時間戳記字串表示法數個範例的表格。
時間戳記的字串表示法	格式字串
`96.07.10, 15:08:56`	`yy.MM.dd ** HH:mm:ss`
`Wed, August 10, 2010 12:08 pm`	`EEE, MMMM dd, yyyy hh:mm a`
`Thu 21/01/2010 14:10:33.17`	`EEE dd/MM/yyyy HH:mm:ss.SS`

總計

傳回單一值，此值是一組值的總和。這組值來自函數的引數。可提供分別位於個別引數中的數個個別值 (例如屬性名稱或常數)。或 last 函數可以是此函數的唯一引數 (以計算最近屬性值的總和)。

TivoliLogTimeToTivoliTimestamp

將 Tivoli 日誌檔時間戳記轉換為 Tivoli Monitoring 時間戳記。此函數需要一個引數，即來自 Tivoli 日誌檔的字串時間戳記。屬性類型為時間戳記。

tokenize

記號化字串的一個記號。此函數需要三個引數。第一個引數是分割為記號的字串。第二個引數可在字串加入一或多個字元，以便區隔記號。來自此引數的全部字元的所有出現次數，可用來識別和區隔第一個引數中記號。第三個引數是記號的索引，可返回此函數的結果。第一個記號是索引 0，第二個記號是索引 1，以此類推。此引數也可以是字串 LAST 以便返回前個記號。

UTCtoGMT

將世界標準時間 (UTC) 轉換為 GMT Tivoli Monitoring 時間戳記。此函數需要一個引數，即整數 time_t 值。屬性類型為時間戳記。

UTCtoLocalTime

將世界標準時間 (UTC) 轉換為當地 Tivoli Monitoring 時間戳記。此函數需要一個引數，即整數 time_t 值。屬性類型為時間戳記。

下列函數不採用任何引數，且傳回數字。

count

保留第一次呼叫時以 1 開始的計數器，後續的每次呼叫都增加 1。如果您將其用於也使用 last 的表示式中，則它會符合 last() 儲存的元素數目，但僅限在 last() 達到上限之前。在該點上，last() 會開始針對每一個新值而刪除最舊值，從而保持相同的值總數，而 count() 會一直增加。

cumulativeSum

傳回流程控制摘要事件所代表之重複事件的引數值總和。如果它是資料來源中的單一事件，則傳回引數。它帶有單一數值引數。此函數僅適用於開啟了事件過濾與摘要功能的事件屬性群組。

eventThreshold

傳回針對產生事件之屬性群組所配置的臨界值。這是一個數字，帶有三個列舉：

SEND_ALL (-3)
SEND_FIRST (-2)
SEND_NONE (-1)

括弧中的數字為原始值。然而，Agent Builder 定義列舉，因此依預設在 Tivoli Enterprise Portal 上或 IBM® Cloud Application Performance Management 主控台中可看到文字版本。如果您指定實際的數值臨界值，且並非三個預先定義選項的其中一個，則此函數會傳回該數字。值為 > 0 的整數。此函數僅適用於開啟了事件過濾與摘要功能的事件屬性群組。

isSummaryEvent

如果它是資料來源中的單一事件，會傳回 0；如果事件是流程控制摘要事件，則傳回 1。如果您使用函數的預設屬性，則顯示的值為事件和摘要事件。如果您手動建立屬性，則顯示的值為 0 和 1，除非您將名稱定義為列舉。此函數僅適用於開啟了事件過濾與摘要功能的事件屬性群組。

occurrenceCount

流程控制摘要事件所代表的相符事件數；如果它是資料來源中的單一事件，則為 1。（流程控制摘要事件包含第一個事件）。此函數僅適用於開啟了事件過濾與摘要功能的事件屬性群組。

summaryInterval

傳回針對產生事件之屬性群組所配置的摘要間隔（以秒為單位）。此函數僅適用於開啟了事件過濾與摘要功能的事件屬性群組。

範例

使用公式運算子及函數建立衍生屬性與過濾屬性的範例

範例 1 - 衍生的屬性

如果您具有定義下列屬性類型的資料來源：

名稱	字串
`xBytes`	數值
`yBytes`	數值
`虛擬大小`	數值

您可以定義：

屬性 totalBytes 為 xBytes 及 yBytes 的總和。輸入公式 xBytes + yBytes。
屬性 yPercent 為位元組總數中 yBytes 的百分比，定義的方式：yBytes % (xBytes + yBytes) 或 yBytes % totalBytes。

範例 2 - 衍生的屬性

該公式會傳回虛擬大小屬性最近所收集值的最大值。所收集的樣本數目是轉換為數值（透過 atoi）的配置變數值 K4P_COLLECTIONS_PER_HISTORY_INTERVAL（透過 getenv 存取）：


max(last(Virtual_Size,atoi(getenv("K4P_COLLECTIONS_PER_HISTORY_INTERVAL"))))

範例 3 - 衍生的屬性

該公式會傳回 xBytes 及 yBytes 屬性值平方和的平方根：

sqrt(xBytes * xBytes + yBtyes * yBytes)

範例 4 - 衍生的屬性

該公式會傳回屬性群組最近 20 個樣本的 xBytes 屬性平均值。如果自代理程式啟動以來收集的樣本數少於 20 個，則會傳回所有樣本的 xBytes 屬性平均值：

average(last(xBytes,20))

範例 5 - 過濾的屬性

您具有傳回以下內容的資料來源：

Name    Type  Size  Used  Free 
Memory  MEM      8     4     4
Disk1   DISK   300   200   100
Disk2   DISK   500   100   400

您僅對磁碟使用情形感興趣。解決方案是建立過濾器來限制傳回的資料。要限制傳回的資料，可以建立傳回布林值 true 或 false 的簡式過濾器，如下所示

磁碟過濾器：

Type=="DISK"

現在，當過濾器 Type=="DISK" 為 true 時，屬性群組會只傳回磁碟使用情形資料，例如：

Name    Type   Size  Used  Free 
Disk1   DISK   300   200   100
Disk2   DISK   500   100   400

範例 6 - 過濾的屬性

您具有傳回以下內容的資料來源：

Name   Size  Used  Free 
Memory    8     4     4
Disk1   300   200   100
Disk2   500   100   400

傳回的資料與前一個範例相似，然而這次沒有呈現 Type 屬性。在這裡，您可以使用相符函數來尋找名稱屬性值符合後接數值之 "Disk" 的任何資料列。

磁碟過濾器：

matches(Name, "Disk[0-9]*")

現在，當過濾器符合屬性 Name 中後接數值的字串 "Disk" 時，只會傳回磁碟使用情形資料列：

Name   Size  Used  Free 
Disk1   300   200   100
Disk2   500   100   400