1 Foreach 関数

概要

foreach関数は、使用されるアイテムフィルターによって選択された各アイテムに対して1つの集計値を返すために、集計計算で使用されます。値の配列が返されます。

たとえば、avg_foreach 関数は値の配列を返します。各値は、指定された時間間隔における、選択されたアイテムの履歴値の平均です。

item filter は、foreach関数で使用される構文の一部です。 アイテムフィルターではワイルドカードの使用がサポートされているため、必要なアイテムを非常に柔軟に選択できます。

サポートされている関数

関数の構文

foreach関数は、2つの共通パラメータ item filter（詳細は以下を参照）と time period をサポートします。

foreach_function(item filter,time period)

例:

avg_foreach(/*/mysql.qps?[group="MySQL Servers"],5m)

は、MySQLサーバーグループ内の各 'mysql.qps' アイテムの5分間の平均値を返します。

一部の関数は追加のパラメータもサポートすることに注意してください。

アイテムフィルター構文

アイテムフィルター:

/host/key[parameters]?[conditions]

は4つの部分で構成されます。

• host - ホスト名
• key - アイテムキー（パラメータを除く）
• parameters - アイテムキーのパラメータ
• conditions - ホストグループおよび/またはアイテムタグに基づく条件（式として指定）

スペースを使用できるのは、conditions 式の内部のみです。

ワイルドカードの使用

• ワイルドカードは、ホスト名、アイテムキー、または個々のアイテムキーパラメータの置き換えに使用できます。
• host または item key のいずれか一方は、ワイルドカードなしで指定する必要があります。したがって、/host/* と /*/key は有効なフィルターですが、/*/* は無効です。
• ワイルドカードは、ホスト名、アイテムキー、アイテムキーパラメータの一部に対して使用することはできません。
• ワイルドカードは、複数のアイテムキーパラメータには一致しません。したがって、各パラメータごとに個別にワイルドカードを指定する必要があります（例: key[abc,*,*]）。

条件式

条件式では、以下をサポートしています。

• オペランド:
  • group - ホストグループ
  • tag - アイテムタグ
  • "<text>" - 文字列定数。" および \ をエスケープするためのエスケープ文字 \ を使用します
• 大文字と小文字を区別する文字列比較演算子: =, <>
• 論理演算子: and, or, not
• 括弧によるグループ化: ( )

文字列定数の引用符は必須です。サポートされるのは、大文字と小文字を区別する完全一致の文字列比較のみです。

例

以下の例のように、アイテムキー、ホストグループ、タグを参照する複雑なフィルターを使用できます。

参照されるすべてのアイテムは、存在し、データを収集している必要があります。
計算に含まれるのは、有効なホスト上の有効なアイテムのみです。
未サポート状態のアイテムは含まれません。

親ホストグループを指定すると、その親グループと、配下にネストされたすべてのホストグループおよびそれらのアイテムが含まれます。

期間

2番目のパラメータでは、集計の期間を指定できます。 期間は時間としてのみ指定でき、値の数（# を接頭辞として付ける形式）はサポートされていません。

利便性のため、このパラメータではサポートされている単位記号を使用できます。 例えば、'300s'（300秒）の代わりに '5m'（5分）、または '86400'（86400秒）の代わりに '1d'（1日）を使用できます。

last_foreach 関数では、期間は省略可能なパラメータです（Zabbix 7.0 以降でサポート）。

last_foreach(/*/key?[group="host group"])

exists_foreach 関数では期間はサポートされていません。

追加パラメータ

bucket_rate_foreach

bucket_rate_foreach 関数では、3つ目のオプションパラメータがサポートされています。

bucket_rate_foreach(item filter,time period,<parameter number>)

ここで、<parameter number> はアイテムキー内の "bucket" 値の位置です。 例えば、myItem[aaa,0.2] の "bucket" 値が '0.2' の場合、その位置は 2 です。

<parameter number> のデフォルト値は '1' です。

count_foreach

count_foreach 関数では、3つ目および4つ目のオプションパラメータがサポートされています。

count_foreach(item filter,time period,<operator>,<pattern>)

ここで:

• operator はアイテム値に対する条件演算子です（必ずダブルクォートで囲む必要があります）。サポートされる operators:
  eq - 等しい
  ne - 等しくない
  gt - より大きい
  ge - 以上
  lt - より小さい
  le - 以下
  like - パターンを含む場合に一致（大文字・小文字を区別）
  bitand - ビット単位AND
  regexp - pattern で指定された正規表現との大文字・小文字を区別する一致
  iregexp - pattern で指定された正規表現との大文字・小文字を区別しない一致
  
• pattern は必要なパターンです（文字列引数はダブルクォートで囲む必要があります）。3つ目のパラメータで operator が指定されている場合にサポートされます。

コメント:

• オプションパラメータ operator または pattern は、カンマの後に空のまま残すことはできず、省略する場合は完全に省略する必要があります。
• 3つ目のパラメータとして bitand を使用する場合、4つ目の pattern パラメータは '/' で区切られた2つの数値、number_to_compare_with/mask として指定できます。count_foreach() は値と mask の「ビット単位AND」を計算し、その結果を number_to_compare_with と比較します。「ビット単位AND」の結果が number_to_compare_with と等しい場合、その値がカウントされます。
  number_to_compare_with と mask が等しい場合は、mask のみを指定すればよく（'/' は不要です）。
• 3つ目のパラメータとして regexp または iregexp を使用する場合、4つ目の pattern パラメータには通常の正規表現または グローバル（'@' で始まる）正規表現を指定できます。グローバル正規表現の場合、大文字・小文字の区別はグローバル正規表現の設定を継承します。regexp マッチングのために、浮動小数点値は常に '.' の後に小数点以下4桁で表現されます。また、大きな数値では10進表現（データベースに保存される値）と2進表現（Zabbix server で使用される値）の違いが、小数点以下4桁目に影響する可能性がある点にも注意してください。

foreach 関数の使用方法に関する詳細および例については、集計計算 を参照してください。

空き状況に応じた動作

次の表は、ホスト/アイテムおよびヒストリデータの可用性が制限されている場合に各関数がどのように動作するかを示しています。

アイテムが無視された場合、集計には何も追加されません。