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 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":
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
Un tercer parámetro opcional es compatible con la función bucket_rate_foreach:
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:
Dónde:
- operador es el operador condicional para los valores de las métricas (debe estar entre comillas dobles).
Operadoresadmitidos:
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 enpattern
iregexp - coincidencia que no distingue entre mayúsculas y minúsculas de la expresión regular dada enpattern - 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ónse 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
patternpuede 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.