Foreach関数

概要

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

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

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

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

サポートされている関数

Function Description
avg_foreach 各アイテムの平均値を返します。
bucket_rate_foreach histogram_quantile() 関数での使用に適した (バケットの上限値、レート値) のペアを返します。ここで、「バケットの上限値」は、<parameter number> parameter で定義されたアイテムキーのパラメータの値です。
count_foreach 各アイテムの値の数を返します。
exists_foreach 有効な各アイテムに対して '1' を返します。
last_foreach 各アイテムの最新の値を返します。
max_foreach 各アイテムの最大値を返します。
min_foreach 各アイテムの最小値を返します。
sum_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
  • 括弧によるグループ化: ( )

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

フィルターでタグを指定する場合（例：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 はアイテム値に対する条件演算子です（必ず二重引用符で囲む必要があります）。サポートされている 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 パラメータには通常の正規表現または global（'@' で始まる）正規表現を指定できます。グローバル正規表現の場合、大文字・小文字の区別はグローバル正規表現の設定を継承します。regexp マッチングのために、浮動小数点値は常に '.' の後に小数点以下4桁で表現されます。また、大きな数値では、10進表現（データベースに保存）と2進表現（Zabbix server で使用）の違いが小数点以下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 無視 合計値を返す 無視 無視 無視 無視

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