Foreach-Funktionen werden in aggregierten Berechnungen verwendet, um für jeden Datenpunkt, der durch den verwendeten Datenpunkt-Filter ausgewählt wird, einen aggregierten Wert zurückzugeben. Es wird ein Array von Werten zurückgegeben.

Foreach-Funktionen werden nur innerhalb von berechneten Datenpunkten als Teil von Formeln für aggregierte Berechnungen unterstützt. Sie können in diesem Kontext nicht in einfachen Datenpunktschlüsseln oder Auslöser-Ausdrücken außerhalb dieses Kontexts aufgerufen werden.

Zum Beispiel gibt die Funktion avg_foreach ein Array von Werten zurück, wobei jeder Wert der durchschnittliche Verlaufswert des ausgewählten Datenpunkts während des angegebenen Zeitintervalls ist.

Der Datenpunkt-Filter ist Teil der von Foreach-Funktionen verwendeten Syntax. Die Verwendung von Platzhaltern wird im Datenpunkt-Filter unterstützt, sodass die erforderlichen Datenpunkte sehr flexibel ausgewählt werden können.

Unterstützte Funktionen

Function	Beschreibung
avg_foreach	Gibt den Durchschnittswert für jeden Datenpunkt zurück.
bucket_rate_foreach	Gibt Paare (obere Bucket-Grenze, Ratenwert) zurück, die für die Verwendung in der Funktion histogram_quantile() geeignet sind, wobei die „obere Bucket-Grenze“ der Wert des Schlüsselsparameters des Datenpunkts ist, der durch den Parameter <parameter number> definiert wird.
count_foreach	Gibt die Anzahl der Werte für jeden Datenpunkt zurück.
exists_foreach	Gibt für jeden aktivierten Datenpunkt „1“ zurück.
last_foreach	Gibt den letzten Wert für jeden Datenpunkt zurück.
max_foreach	Gibt den Maximalwert für jeden Datenpunkt zurück.
min_foreach	Gibt den Minimalwert für jeden Datenpunkt zurück.
sum_foreach	Gibt die Summe der Werte für jeden Datenpunkt zurück.

Funktionssyntax

Foreach-Funktionen unterstützen zwei gemeinsame Parameter: Datenpunkt-Filter (siehe Details unten) und Zeitperiode:

foreach_function(item filter,time period)

Zum Beispiel:

avg_foreach(/*/mysql.qps?[group="MySQL Servers"],5m)

gibt den Fünf-Minuten-Durchschnitt jedes Datenpunkts 'mysql.qps' in der MySQL-Servergruppe zurück.

Beachten Sie, dass einige Funktionen zusätzliche Parameter unterstützen.

Syntax des Datenpunktfilters

Der Datenpunktfilter:

/host/key[parameters]?[conditions]

besteht aus vier Teilen, wobei:

host - Host-Name
key - Datenpunktschlüssel (ohne Parameter)
parameters - Datenpunktschlüsselparameter
conditions - auf Host-Gruppen und/oder Datenpunkt-Tags basierende Bedingungen (als Ausdruck)

Leerzeichen sind nur innerhalb des Bedingungsausdrucks zulässig.

Verwendung von Platzhaltern

Ein Platzhalter kann verwendet werden, um den Host-Namen, den Datenpunktschlüssel oder einen einzelnen Datenpunktschlüsselparameter zu ersetzen.
Entweder der Host oder der Datenpunktschlüssel muss ohne Platzhalter angegeben werden. Daher sind /host/* und /*/key gültige Filter, aber /*/* ist ungültig.
Ein Platzhalter kann nicht für einen Teil des Host-Namens, des Datenpunktschlüssels oder des Datenpunktschlüsselparameters verwendet werden.
Ein Platzhalter entspricht nicht mehr als einem einzelnen Datenpunktschlüsselparameter. Daher muss für jeden Parameter separat ein Platzhalter angegeben werden (d. h. key[abc,*,*]).

Bedingungsausdruck

Der Bedingungsausdruck unterstützt:

Operanden:
- group - Host-Gruppe
- tag - Datenpunkt-Tag
- "<text>" - Zeichenkettenkonstante, wobei das Escape-Zeichen \ verwendet wird, um " und \ zu maskieren
Operatoren für die Groß-/Kleinschreibung beachtende Zeichenkettenvergleiche: =, <>
logische Operatoren: and, or, not
Gruppierung mit Klammern: ( )

Die Anführungszeichen für Zeichenkettenkonstanten sind obligatorisch. Es wird nur ein vollständiger, die Groß-/Kleinschreibung beachtender Zeichenkettenvergleich unterstützt.

Bei der Angabe von Tags im Filter (d. h. tag="tagname:value") wird der Doppelpunkt ":" als Trennzeichen verwendet. Alles danach wird als Tag-Wert betrachtet. Daher wird die Angabe eines Tag-Namens, der ":" enthält, derzeit nicht unterstützt.

Beispiele

Es kann ein komplexer Filter verwendet werden, der sich auf den Datenpunktschlüssel, die Host-Gruppe und Tags bezieht, wie in den Beispielen dargestellt:

Syntax example	Description
`/host/key[abc,*]`	Entspricht ähnlichen Datenpunkten auf diesem Host.
`/*/key`	Entspricht demselben Datenpunkt auf jedem Host.
`/*/key?[group="ABC" and tag="tagname:value"]`	Entspricht demselben Datenpunkt auf jedem Host aus der Gruppe ABC mit den Tags 'tagname:value'.
`//key[a,,c]?[(group="ABC" and tag="Tag1") or (group="DEF" and (tag="Tag2" or tag="Tag3:value"))]`	Entspricht ähnlichen Datenpunkten auf jedem Host aus der Gruppe ABC oder DEF mit den entsprechenden Tags.

Alle referenzierten Datenpunkte müssen existieren und Daten erfassen. Nur aktivierte Datenpunkte auf aktivierten Hosts werden in die Berechnungen einbezogen. Datenpunkte im nicht unterstützten Zustand werden nicht einbezogen.

Wenn der Datenpunktschlüssel eines referenzierten Datenpunkts geändert wird, muss der Filter manuell aktualisiert werden.

Die Angabe einer übergeordneten Host-Gruppe schließt die übergeordnete Gruppe und alle verschachtelten Host-Gruppen mit ihren Datenpunkten ein.

Zeitperiode

Der zweite Parameter ermöglicht die Angabe der Zeitperiode für die Aggregation. Die Zeitperiode kann nur als Zeitangabe ausgedrückt werden; die Anzahl der Werte (mit # vorangestellt) wird nicht unterstützt.

Unterstützte Einheitensymbole können in diesem Parameter der Einfachheit halber verwendet werden, zum Beispiel „5m“ (fünf Minuten) statt „300s“ (300 Sekunden) oder „1d“ (ein Tag) statt „86400“ (86400 Sekunden).

Für die Funktion last_foreach ist die Zeitperiode ein optionaler Parameter (unterstützt seit Zabbix 7.0), der weggelassen werden kann:

last_foreach(/*/key?[group="host group"])

Die Zeitperiode wird von der Funktion exists_foreach nicht unterstützt.

Zusätzliche Parameter

bucket_rate_foreach

Ein dritter optionaler Parameter wird von der Funktion bucket_rate_foreach unterstützt:

bucket_rate_foreach(item filter,time period,<parameter number>)

wobei <parameter number> die Position des „bucket“-Werts im Datenpunktschlüssel ist. Wenn beispielsweise der „bucket“-Wert in myItem[aaa,0.2] „0.2“ ist, dann ist seine Position 2.

Der Standardwert von <parameter number> ist „1“.

count_foreach

Die Funktion count_foreach unterstützt einen dritten und vierten optionalen Parameter:

count_foreach(item filter,time period,<operator>,<pattern>)

Dabei gilt:

operator ist der bedingte Operator für Datenpunktwerte (muss in doppelte Anführungszeichen gesetzt werden). Unterstützte operators:
eq - gleich
ne - ungleich
gt - größer
ge - größer oder gleich
lt - kleiner
le - kleiner oder gleich
like - stimmt überein, wenn das Muster enthalten ist (Groß-/Kleinschreibung wird beachtet)
bitand - bitweises UND
regexp - Übereinstimmung unter Beachtung der Groß-/Kleinschreibung mit dem in pattern angegebenen regulären Ausdruck
iregexp - Übereinstimmung ohne Beachtung der Groß-/Kleinschreibung mit dem in pattern angegebenen regulären Ausdruck
pattern ist das erforderliche Muster (String-Argumente müssen in doppelte Anführungszeichen gesetzt werden); wird unterstützt, wenn operator im dritten Parameter angegeben ist.

Kommentare:

Optionale Parameter operator oder pattern können nach einem Komma nicht leer gelassen, sondern nur vollständig weggelassen werden.
Wenn bitand als dritter Parameter verwendet wird, kann der vierte Parameter pattern als zwei durch „/“ getrennte Zahlen angegeben werden: number_to_compare_with/mask. count_foreach() berechnet aus dem Wert und der mask ein „bitweises UND“ und vergleicht das Ergebnis mit number_to_compare_with. Wenn das Ergebnis des „bitweisen UND“ gleich number_to_compare_with ist, wird der Wert gezählt.
Wenn number_to_compare_with und mask gleich sind, muss nur die mask angegeben werden (ohne „/“).
Wenn regexp oder iregexp als dritter Parameter verwendet wird, kann der vierte Parameter pattern ein gewöhnlicher oder globaler (mit „@“ beginnender) regulärer Ausdruck sein. Bei globalen regulären Ausdrücken wird die Groß-/Kleinschreibung aus den Einstellungen des globalen regulären Ausdrucks übernommen. Für den Zweck des regexp-Abgleichs werden Float-Werte immer mit 4 Dezimalstellen nach dem „.“ dargestellt. Beachten Sie außerdem, dass bei großen Zahlen Unterschiede zwischen der dezimalen (in der Datenbank gespeicherten) und der binären (vom Zabbix Server verwendeten) Darstellung die 4. Dezimalstelle beeinflussen können.

Weitere Details und Beispiele zur Verwendung von foreach-Funktionen finden Sie unter Aggregatberechnungen.

Verhalten in Abhängigkeit von der Verfügbarkeit

Die folgende Tabelle veranschaulicht, wie sich jede Funktion bei eingeschränkter Verfügbarkeit von Host-/Datenpunkt- und Verlaufsdaten verhält.

Function	Deaktivierter Host	Nicht verfügbarer Host mit Daten	Nicht verfügbarer Host ohne Daten	Deaktivierter Datenpunkt	Nicht unterstützter Datenpunkt	Fehler beim Datenabruf (SQL)
avg_foreach	ignorieren	Durchschnitt zurückgeben	ignorieren	ignorieren	ignorieren	ignorieren
bucket_rate_foreach	ignorieren	Bucket-Rate zurückgeben	ignorieren	ignorieren	ignorieren	ignorieren
count_foreach	ignorieren	Anzahl zurückgeben	0	ignorieren	ignorieren	ignorieren
exists_foreach	ignorieren	1	1	ignorieren	1	n/v
last_foreach	ignorieren	Letzten Wert zurückgeben	ignorieren	ignorieren	ignorieren	ignorieren
max_foreach	ignorieren	Maximum zurückgeben	ignorieren	ignorieren	ignorieren	ignorieren
min_foreach	ignorieren	Minimum zurückgeben	ignorieren	ignorieren	ignorieren	ignorieren
sum_foreach	ignorieren	Summe zurückgeben	ignorieren	ignorieren	ignorieren	ignorieren

Wenn der Datenpunkt ignoriert wird, wird der Aggregation nichts hinzugefügt.

What’s next?

2 Bitweise Funktionen

Docs

Foreach-Funktionen

Übersicht