1 Funciones Foreach

Descripción general

Las funciones Foreach se utilizan en cálculos agregados para devolver un valor agregado para cada métrica seleccionada por el filtro de métricas usado. Se devuelve una matriz de valores.

Por ejemplo, la función avg_foreach devolverá una matriz de valores, donde cada valor es el valor histórico promedio de la métrica seleccionada, durante el intervalo de tiempo especificado.

El [filtro de métrica] (#item-filter-syntax) es parte de la sintaxis utilizada por las funciones foreach. El filtro de métrica admite el uso de comodines, por lo que las métricas necesarias se pueden seleccionar de forma bastante flexible.

Funciones admitidas

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

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

Un tercer parámetro opcional es compatible con la función bucket_rate_foreach:

bucket_rate_foreach(filtro de métricas,período de tiempo,<número de parámetro>)

donde <número de parámetro> es la posición del valor del "depósito" en la clave de la métrica. Por ejemplo, si el valor del "depósito" en myItem[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

El tercer y cuarto parámetro opcional son compatibles con la función count_foreach:

count_foreach(filtro de métricas,período de tiempo,<operador>,<patrón>)

Dónde:

  • operador es el operador condicional para los valores de las métricas (debe estar entre comillas dobles). Operadores admitidos:
    eq - igual
    ne - no igual
    gt - mayor
    ge - mayor o igual
    lt - menos<br >le - menor o igual
    like - coincide si contiene patrón (distingue entre mayúsculas y minúsculas)
    bitand - AND bit a bit
    regexp - coincide entre mayúsculas y minúsculas de la expresión regular dada en pattern
    iregexp - coincidencia que no distingue entre mayúsculas y minúsculas de la expresión regular dada en pattern
  • patrón es el patrón requerido (los argumentos de cadena deben estar entre comillas dobles); compatible si se especifica operador en el tercer parámetro.

Comentarios:

  • Los parámetros opcionales operador o patrón no se pueden dejar vacíos después de una coma, solo se pueden omitir por completo.
  • Con bitand como tercer parámetro, el cuarto parámetro patrón se puede especificar como dos números, separados por '/': número_para_comparar_con/máscara. count() calcula "Y bit a bit" a partir del valor y la máscara y compara el resultado con número_a_comparar_con. Si el resultado de "Y 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 ordinaria o global (comenzando 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 los efectos de la coincidencia de expresiones regulares, los valores flotantes siempre se representarán con 4 dígitos decimales después de '.'. También tenga en cuenta 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 el 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.