Documentation
Table of Contents
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 soportadas
| 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":
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:
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/*/keyson 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:
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:
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:
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 enpatrón
iregexp - coincidencia insensible a mayúsculas de la expresión regular dada enpatró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 pueden omitirse completamente.
- Con bitand como tercer parámetro, el cuarto parámetro
patrónpuede 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ónpuede ser una expresión regular ordinaria o global (que comienza con '@'). En el caso de expresiones regulares globales, la sensibilidad a mayúsculas se hereda de la configuración global de expresiones regulares. 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.