Foreach関数

概要

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

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

foreach 関数は、計算アイテム の式でのみサポートされます。 通常のアイテムキーでは呼び出せず、トリガー式を直接作成するためにも使用できません。 トリガー式では、計算アイテムのキーを参照することで使用できます。

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

サポートされる関数

Function Description
avg_foreach 各アイテムの平均値を返します。
bucket_rate_foreach histogram_quantile() 関数で使用するのに適した、(バケットの上限, レート値) のペアを返します。ここで "bucket upper bound" は、<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 に対して "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 マッチングでは、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 無視 合計値を返す 無視 無視 無視 無視

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