1 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 son compatibles 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 manera bastante flexible.

Funciones compatibles

Función Descripción
avg_foreach Devuelve el valor promedio para cada elemento.
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 clave del elemento definido por el <número de parámetro> parámetro.
count_foreach Devuelve el número de valores para cada elemento.
exists_foreach Devuelve '1' para cada elemento habilitado.
last_foreach Devuelve el último valor para cada elemento.
max_foreach Devuelve el valor máximo para cada elemento.
min_foreach Devuelve el valor mínimo para cada elemento.
sum_foreach Devuelve la suma de los valores para cada elemento.

Sintaxis de la función

Las funciones Foreach admiten dos parámetros comunes: "filtro de métricas" (ver detalles a continuación) y "período de tiempo":

foreach_function(filtro de métrica,período de tiempo)

Por ejemplo:

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

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

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

Sintaxis del filtro de métrica

El filtro de métricas:

/host/key[parameters]?[conditions]

consta de cuatro partes, donde:

  • host - nombre del equipo
  • key - clave de la métrica (sin parámetros)
  • parameters - parámetros de la clave de la métrica
  • conditions: condiciones basadas en grupo de equipos y/o etiqueta de métricas (como expresión)

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

Uso de comodines

  • Se puede utilizar un comodín para reemplazar el nombre del equipo, la clave de la métrica o un parámetro de clave de métrica individual.
  • Se debe especificar la clave del equipo o de la métrica sin comodines. Entonces /host/* y /*/key son filtros válidos, pero /*/* no es válido.
  • El comodín no se puede utilizar para una parte del nombre de equipo, clave de métrica o parámetro de clave de métrica.
  • El comodín no coincide con más de un parámetro clave de métrica. Por lo tanto, se debe especificar un comodín para cada parámetro en la separación (es decir, key[abc,*,*]).

Expresión de las condiciones

La expresión de las condiciones admite:

  • operandos:
    • group - grupo de equipos
    • tag - etiqueta de métrica
    • "<text>" - constante de cadena, con el carácter de escape \ para escapar de " y \
  • operadores de comparación de cadenas que distinguen entre mayúsculas y minúsculas: =, <>
  • operadores lógicos: and, or, not
  • agrupación entre paréntesis: ( )

Incluir entre comillas las constantes de cadena es obligatoria. Solo se admite la comparación de cadenas completas que distingue entre mayúsculas y minúsculas.

Al especificar etiquetas en el filtro (es decir, tag="tagname:value"), los dos puntos ":" se utilizan 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

Se puede utilizar un filtro complejo, que haga referencia a la clave de la métrica, al grupo de equipos y etiquetas, como lo ilustran los ejemplos:

Ejemplo de sintaxis Descripción
/host/key[abc,*] Coincide con métricas similares en este equipo.
/*/key Coincide con la misma métrica en cualquier equipo.
/*/key?[group="ABC" and tag="tagname:value"] Coincide con la misma métrica en cualquier equipo del grupo ABC que tenga etiquetas 'tagname:value'.
/*/key[a,*,c]?[(group="ABC" y tag="Etiqueta1") or (group="DEF" and (tag="Etiqueta2" o tag="Etiqueta3:valor" ))] Coincide con métricas similares de cualquier equipo del grupo ABC o DEF con las etiquetas respectivas.

Todas las métricas a las que se hace referencia deben existir y recopilar datos. Sólo las métricas habilitadas en los equipos habilitados se incluyen en los cálculos. Las métricas en estado no soportado no están incluidas.

Si se cambia la clave de métrica de una métrica referenciada, el filtro debe actualizarse manualmente.

La especificación de un grupo de equipos principal incluye el grupo principal y todos los
grupos de equipos anidados con sus métricas correspondientes.

Periodo de tiempo

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

Los símbolos de unidad admitidos se pueden utilizar en este parámetro por conveniencia, 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 se puede omitir:

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(filtro de elemento,periodo de tiempo,<número de parámetro>)

donde <número de parámetro> es la posición del valor "bucket" en la clave del elemento. Por ejemplo, si el valor "bucket" en miElemento[aaa,0.2] es '0.2', entonces su posición es 2.

El valor predeterminado de <número de parámetro> es '1'.

count_foreach

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

count_foreach(filtro de elemento,periodo de tiempo,<operador>,<patrón>)

Donde:

  • operador es el operador condicional para los valores de los elementos (debe ir entre comillas dobles). operadores soportados:
    eq - igual
    ne - no igual
    gt - mayor
    ge - mayor o igual
    lt - menor
    le - menor o igual
    like - coincide si contiene el patrón (sensible a mayúsculas)
    bitand - AND a nivel de bits
    regexp - coincidencia sensible a mayúsculas de la expresión regular dada en patrón
    iregexp - coincidencia insensible a mayúsculas de la expresión regular dada en patrón
  • patrón es el patrón requerido (los argumentos de cadena deben ir entre comillas dobles); se admite si operador se especifica en el tercer parámetro.

Comentarios:

  • Los parámetros opcionales operador o patrón no pueden dejarse vacíos después de una coma, solo omitirse completamente.
  • Con bitand como tercer parámetro, el cuarto parámetro patrón puede especificarse como dos números, separados por '/': número_a_comparar_con/máscara. count_foreach() calcula el "AND a nivel de bits" entre el valor y la máscara y compara el resultado con número_a_comparar_con. Si el resultado del "AND a nivel de bits" es igual a número_a_comparar_con, el valor se cuenta.
    Si número_a_comparar_con y máscara son iguales, solo es necesario especificar la máscara (sin '/').
  • Con regexp o iregexp como tercer parámetro, el cuarto parámetro patrón puede ser una expresión regular ordinaria o global (comenzando con '@'). En el caso de expresiones regulares globales, la sensibilidad a mayúsculas se hereda de la configuración de expresiones regulares globales. Para el propósito de la coincidencia 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 en la representación decimal (almacenada en la base de datos) y binaria (utilizada por el servidor Zabbix) puede afectar al cuarto dígito decimal.

Consulte cálculos agregados para obtener más detalles y ejemplos sobre el uso de 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.