Funciones foreach

Descripción general

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

Las funciones foreach solo se admiten dentro de los items calculados como parte de las 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 promedio del historial del item seleccionado, durante el intervalo de tiempo especificado.

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

Funciones compatibles

Function Descripción
avg_foreach Devuelve el valor promedio para cada item.
bucket_rate_foreach Devuelve pares (límite superior del bucket, valor de tasa) adecuados para su uso en la función histogram_quantile(), donde el "límite superior del bucket" es el valor del parámetro de clave del item definido por el parámetro <parameter number>.
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 valores para cada item.

Sintaxis de la función

Las funciones foreach admiten dos parámetros comunes: filtro de item (consulte los detalles a continuación) y período de tiempo:

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 el grupo de host y/o etiquetas de item (como expresión)

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

Uso de comodines

  • El comodín puede utilizarse para reemplazar el nombre del host, la clave del item o un parámetro individual de la clave del item.
  • O bien el host o la clave del item deben especificarse sin comodín. Así, /host/* y /*/key son filtros válidos, pero /*/* no es válido.
  • El comodín no puede utilizarse para una parte del nombre del host, la clave del item o el parámetro de la clave del item.
  • El comodín no coincide con más de un parámetro de la clave del item. Por lo tanto, debe especificarse 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
    • "<texto>" - 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: ( )

La cita de constantes de cadena es obligatoria. Sólo se admite la comparación de cadenas completas y sensibles a mayúsculas y minúsculas.

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

Ejemplos

Puede utilizarse un filtro complejo, haciendo referencia a la clave del item, al grupo de host y a las etiquetas, como ilustran los ejemplos:

Ejemplo de sintaxis Descripción
/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 recoger datos. Sólo se incluyen en los cálculos los items habilitados en hosts habilitados. No se incluyen los items en estado no soportado.

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

La especificación de un grupo de host principal incluye el grupo principal y todos los grupos de host anidados con sus items.

Periodo 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, la cantidad de valores (prefijada con #) no es compatible.

Se pueden utilizar símbolos de unidad admitidos en este parámetro para mayor 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). operators admitidos:
    eq - igual
    ne - distinto
    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 a nivel de bits
    regexp - coincidencia sensible a mayúsculas y minúsculas de la expresión regular indicada en pattern
    iregexp - coincidencia no sensible a mayúsculas y minúsculas de la expresión regular indicada en pattern
  • pattern es el patrón requerido (los argumentos de cadena deben ir entre comillas dobles); se admite si operator se especifica 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 a nivel de bits" entre el valor y la mask y compara el resultado con number_to_compare_with. Si el resultado del "AND a nivel de bits" 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 las expresiones regulares globales, la distinción entre mayúsculas y minúsculas se hereda de la configuración de la expresión regular global. Para fines de coincidencia con regexp, los valores de coma flotante 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 Zabbix server) 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 la disponibilidad

La siguiente tabla ilustra cómo se comporta cada función en casos de disponibilidad limitada del host/item y de los datos históricos.

Función Host deshabilitado Host no disponible con datos Host no disponible sin datos Item deshabilitado Item no soportado Error de recuperación de datos (SQL)
avg_foreach ignorar devolver avg ignorar ignorar ignorar ignorar
bucket_rate_foreach ignorar devolver bucket rate ignorar ignorar ignorar ignorar
count_foreach ignorar devolver count 0 ignorar ignorar ignorar
exists_foreach ignorar 1 1 ignorar 1 n/a
last_foreach ignorar devolver last ignorar ignorar ignorar ignorar
max_foreach ignorar devolver max ignorar ignorar ignorar ignorar
min_foreach ignorar devolver min ignorar ignorar ignorar ignorar
sum_foreach ignorar devolver sum ignorar ignorar ignorar ignorar

Si el item es ignorado, no se añade nada a la agregación.