Foreach関数

概要

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

Foreach関数は、計算アイテム内で集計計算式の一部としてのみサポートされています。 このコンテキスト外で、通常のアイテムキーやトリガー式で呼び出すことはできません。

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

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

サポートされている関数

関数 説明
avg_foreach 各アイテムの平均値を返します。
bucket_rate_foreach histogram_quantile()関数で使用するのに適したペア(バケットの上限、レート値)を返します。ここで「バケットの上限」は、<parameter number> パラメータで定義されたアイテムキーのパラメータの値です。
count_foreach 各アイテムの値の数を返します。
exists_foreach 有効な各アイテムに対して「1」を返します。
last_foreach 各アイテムの最新値を返します。
max_foreach 各アイテムの最大値を返します。
min_foreach 各アイテムの最小値を返します。
sum_foreach 各アイテムの値の合計を返します。

関数の構文

Foreach関数は、2つの共通パラメータ、アイテムフィルター（詳細は下記参照）と時間をサポートします。

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
  • 括弧によるグループ化: ( )

文字列定数の引用は必須です。大文字小文字を区別した完全一致のみがサポートされます。

フィルターでタグを指定する場合（例：tag="tagname:value"）、コロン「:」は区切り文字として使用されます。 それ以降はすべてタグ値と見なされます。したがって、現時点では「:」を含むタグ名の指定はサポートされていません。

例

アイテムキー、ホストグループ、タグを参照する複雑なフィルターを使用することができます。例を示します。

構文例 説明
/host/key[abc,*] このホスト上の類似アイテムに一致します。
/*/key 任意のホストの同じアイテムに一致します。
/*/key?[group="ABC" and tag="tagname:value"] ABCグループに属し、'tagname:value'タグを持つ任意のホストの同じアイテムに一致します。
/*/key[a,*,c]?[(group="ABC" and tag="Tag1") or (group="DEF" and (tag="Tag2" or tag="Tag3:value"))] ABCまたはDEFグループに属し、それぞれのタグを持つ任意のホストの類似アイテムに一致します。

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

参照アイテムのアイテムキーを変更した場合、フィルターも手動で更新する必要があります。

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

期間

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はアイテム値の条件演算子です（ダブルクォーテーションで囲む必要があります）。サポートされているoperator:
    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パラメータは通常の正規表現またはグローバル（'@'で始まる）正規表現にできます。グローバル正規表現の場合、大文字小文字の区別はグローバル正規表現の設定から継承されます。正規表現マッチングの目的で、float値は常に'.'の後に4桁の小数で表現されます。また、大きな数値の場合、10進数（データベースに保存）と2進数（Zabbixサーバーで使用）表現の違いにより、4番目の小数点以下の桁に影響する場合があります。

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

可用性による動作

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

関数 無効なホスト データがあるが利用できないホスト データがない利用できないホスト 無効なアイテム 未サポートのアイテム データ取得エラー(SQL)
avg_foreach 無視 平均値を返す 無視 無視 無視 無視
bucket_rate_foreach 無視 バケットレートを返す 無視 無視 無視 無視
count_foreach 無視 カウントを返す 0 無視 無視 無視
exists_foreach 無視 1 1 無視 1 n/a
last_foreach 無視 最新値を返す 無視 無視 無視 無視
max_foreach 無視 最大値を返す 無視 無視 無視 無視
min_foreach 無視 最小値を返す 無視 無視 無視 無視
sum_foreach 無視 合計値を返す 無視 無視 無視 無視

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