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 - ホストグループおよび/またはアイテムタグに基づく条件（式）.

スペースは条件式の内部でのみ使用できます。

ワイルドカードの使用

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

条件式

条件式では次をサポートします。

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

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

例

複雑なフィルターでは、アイテムキー、ホストグループ、タグを参照できます。以下の例を参照してください。

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

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

時間期間

第2パラメーターでは、集計の時間期間を指定できます。
時間期間は時間としてのみ表現でき、値の個数（# を前置した形式）はサポートされていません。

このパラメーターでは、便宜上 サポートされている単位記号 を使用できます。たとえば、300s（300秒）の代わりに 5m（5分）、86400s（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 に対して "bitwise AND" を計算し、その結果を number_to_compare_with と比較します。
  "bitwise AND" の結果が number_to_compare_with と等しい場合、その値はカウントされます。
  number_to_compare_with と mask が等しい場合は、mask だけを指定すればよく（/ は不要です）。
• 3つ目のパラメータとして regexp または iregexp を指定した場合、4つ目の pattern パラメータには、通常の正規表現または global 正規表現（@ で始まる）を指定できます。
  global 正規表現の場合、大文字小文字の区別は global 正規表現の設定を継承します。
  regexp の照合では、浮動小数点値は常に . の後に 4 桁の数字で表されます。
  また、大きな数値では、10進数表現（データベースに保存）と2進数表現（Zabbix サーバーで使用）の差異により、4桁目の小数点以下の桁に影響が出る場合があります。

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

空き状況に応じた動作

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

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