1 Foreach 関数

概要

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

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

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

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

例

アイテムキー、ホストグループ、タグを参照する複雑なフィルタを使用することができ、以下の例で示されています:

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

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

期間

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は必要なパターン（文字列引数はダブルクォートで囲む必要があります）；operatorが3番目のパラメータで指定されている場合にサポートされます。

コメント:

• オプションパラメータ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関数の使用に関する詳細および例については、集計計算を参照してください。

可用性による動作

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

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