1 Funciones Foreach

Descripción general

Las funciones foreach se utilizan en cálculos agregados para devolver un valor agregado por cada item que se selecciona mediante el filtro de item utilizado. Se devuelve un array de valores.

Las funciones foreach solo son compatibles dentro de items calculados como parte de fórmulas de cálculo agregado. No se pueden invocar en claves de item simples ni en expresiones de trigger fuera de este contexto.

Por ejemplo, la función avg_foreach devolverá un array de valores, donde cada valor es el valor histórico promedio del item seleccionado, durante el intervalo de tiempo especificado.

El filtro de item forma parte de la sintaxis utilizada por las funciones foreach. El uso de comodines es compatible en el filtro de item, por lo que los items requeridos se pueden seleccionar con bastante flexibilidad.

Funciones soportadas

Función Descripción
avg_foreach Devuelve el valor promedio para cada item.
bucket_rate_foreach Devuelve pares (límite superior del bucket, valor de la tasa) adecuados para su uso en la función histogram_quantile(), donde "límite superior del bucket" es el valor del parámetro de clave de item definido por el <número de parámetro> parámetro.
count_foreach Devuelve el número de valores para cada item.
exists_foreach Devuelve '1' para cada item habilitado.
last_foreach Devuelve el último valor para cada item.
max_foreach Devuelve el valor máximo para cada item.
min_foreach Devuelve el valor mínimo para cada item.
sum_foreach Devuelve la suma de los valores para cada item.

Sintaxis de la función

Las funciones Foreach admiten dos parámetros comunes: item filter (consulte los detalles a continuación) y time period:

foreach_function(item filter,time period)

Por ejemplo:

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

devolverá el promedio de cinco minutos de cada item mysql.qps en el grupo de servidores MySQL.

Tenga en cuenta que algunas funciones admiten parámetros adicionales.

Sintaxis del filtro de item

El filtro de item:

/host/key[parameters]?[conditions]

consta de cuatro partes, donde:
host - nombre del host;
key - clave del item (sin parámetros);
parameters - parámetros de la clave del item;
conditions - condiciones basadas en grupos de host y/o etiquetas de item (como expresión).

Los espacios solo se permiten dentro de la expresión de condiciones.

Uso de comodines

  • Se puede usar un comodín para reemplazar el nombre del host, la clave del item o un parámetro individual de la clave del item.
  • Debe especificarse sin comodín el host o la clave del item. Por lo tanto, /host/* y /*/key son filtros válidos, pero /*/* no es válido.
  • El comodín no se puede usar para una parte del nombre del host, la clave del item ni un parámetro de la clave del item.
  • El comodín no coincide con más de un solo parámetro de la clave del item. Por lo tanto, se debe especificar un comodín para cada parámetro por separado (es decir, key[abc,*,*]).

Expresión de condiciones

La expresión de condiciones admite:

  • Operandos:
    group - grupo de host;
    tag - etiqueta de item;
    "<text>" - constante de cadena, con el carácter de escape \ para escapar " y \.
  • Operadores de comparación de cadenas sensibles a mayúsculas y minúsculas: =, <>
  • Operadores lógicos: and, or, not
  • Agrupación con paréntesis: ( )

Es obligatorio entrecomillar las constantes de cadena. Solo se admite la comparación completa de cadenas sensible a mayúsculas y minúsculas.

Al especificar etiquetas en el filtro (es decir, tag="tagname:value"), los dos puntos ":" se usan como delimitador. Todo lo que aparece después se considera el valor de la etiqueta. Por lo tanto, actualmente no se admite especificar un nombre de etiqueta que contenga ":".

Ejemplos

Se puede usar un filtro complejo, que haga referencia a la clave del item, el grupo de host y las etiquetas, como se ilustra en los ejemplos:

Syntax example Description
/host/key[abc,*] Coincide con items similares en este host.
/*/key Coincide con el mismo item de cualquier host.
/*/key?[group="ABC" and tag="tagname:value"] Coincide con el mismo item de cualquier host del grupo ABC que tenga etiquetas 'tagname:value'.
/*/key[a,*,c]?[(group="ABC" and tag="Tag1") or (group="DEF" and (tag="Tag2" or tag="Tag3:value"))] Coincide con items similares de cualquier host del grupo ABC o DEF con las etiquetas correspondientes.

Todos los items referenciados deben existir y recopilar datos. Solo se incluyen en los cálculos los items habilitados en hosts habilitados. Los items en estado no compatible no se incluyen.

Si se cambia la clave del item de un item referenciado, el filtro debe actualizarse manualmente.

Especificar un grupo de host padre incluye el grupo padre y todos los grupos de host anidados con sus items.

Período de tiempo

El segundo parámetro permite especificar el período de tiempo para la agregación. El período de tiempo solo puede expresarse como tiempo; no se admite la cantidad de valores (precedida por #).

Se pueden usar símbolos de unidades admitidos en este parámetro por comodidad, por ejemplo, 5m (cinco minutos) en lugar de 300s (300 segundos) o 1d (un día) en lugar de 86400 (86400 segundos).

Para la función last_foreach, el período de tiempo es un parámetro opcional (compatible desde Zabbix 7.0), que puede omitirse:

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

El período de tiempo no es compatible con la función exists_foreach.

Parámetros adicionales

bucket_rate_foreach

La función bucket_rate_foreach admite un tercer parámetro opcional:

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

donde <parameter number> es la posición del valor "bucket" en la clave del item. Por ejemplo, si el valor "bucket" en myItem[aaa,0.2] es 0.2, entonces su posición es 2.

El valor predeterminado de <parameter number> es 1.

count_foreach

La función count_foreach admite un tercer y un cuarto parámetro opcionales:

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

Donde:

  • operator es el operador condicional para los valores del item (debe ir entre comillas dobles). Operadores compatibles:
    eq - igual a
    ne - distinto de
    gt - mayor que
    ge - mayor o igual que
    lt - menor que
    le - menor o igual que
    like - coincide si contiene el patrón (distingue mayúsculas y minúsculas)
    bitand - AND bit a bit
    regexp - coincide con la expresión regular dada en pattern distinguiendo mayúsculas y minúsculas
    iregexp - coincide con la expresión regular dada en pattern sin distinguir mayúsculas y minúsculas.
  • pattern es el patrón requerido (los argumentos de tipo cadena deben ir entre comillas dobles); se admite si se especifica operator en el tercer parámetro.

Comentarios:

  • Los parámetros opcionales operator o pattern no pueden dejarse vacíos después de una coma; solo pueden omitirse por completo.
  • Con bitand como tercer parámetro, el cuarto parámetro pattern puede especificarse como dos números, separados por '/': number_to_compare_with/mask. count_foreach() calcula el "AND bit a bit" del valor y la mask y compara el resultado con number_to_compare_with. Si el resultado del "AND bit a bit" es igual a number_to_compare_with, el valor se cuenta.
    Si number_to_compare_with y mask son iguales, solo es necesario especificar la mask (sin '/').
  • Con regexp o iregexp como tercer parámetro, el cuarto parámetro pattern puede ser una expresión regular normal o global (que comienza con '@'). En el caso de expresiones regulares globales, la distinción entre mayúsculas y minúsculas se hereda de la configuración de expresiones regulares globales. A efectos de la coincidencia con regexp, los valores flotantes siempre se representarán con 4 dígitos decimales después de '.'. Tenga en cuenta también que, para números grandes, la diferencia entre la representación decimal (almacenada en la base de datos) y la binaria (utilizada por el server de Zabbix) puede afectar al cuarto dígito decimal.

Consulte cálculos agregados para obtener más detalles y ejemplos sobre el uso de las funciones foreach.

Comportamiento según disponibilidad

La siguiente tabla ilustra cómo se comporta cada función en casos de disponibilidad limitada de equipo/métrica y datos históricos.

Función Equipo deshabilitado Equipo no disponible con datos Equipo no disponible sin datos Métrica deshabilitada Métrica no admitida Error de recuperación de datos (SQL)
avg_foreach ignore return avg ignore ignore ignore ignore
bucket_rate_foreach ignore return bucket rate ignore ignore ignore ignore
count_foreach ignore return count 0 ignore ignore ignore
exists_foreach ignore 1 1 ignore 1 n/a
last_foreach ignore return last ignore ignore ignore ignore
max_foreach ignore return max ignore ignore ignore ignore
min_foreach ignore return min ignore ignore ignore ignore
sum_foreach ignore return sum ignore ignore ignore ignore

Si la métrica se ignora, no se agrega nada a la agregación.