Table of Contents
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 soportadas
| Función | Descripción |
|---|---|
| avg_foreach | Devuelve el valor promedio para cada item. |
| 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 de clave de item definido por el <número de parámetro> parámetro. |
| 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 los valores para cada item. |
Sintaxis de la función
Las funciones foreach admiten dos parámetros comunes: filtro de item (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 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:
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/*/keyson 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:
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 item. Por ejemplo, si el valor "bucket" en myItem[aaa,0.2] es '0.2', entonces su posición es 2.
El valor por defecto 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 items (debe ir entre comillas dobles).
operadoressoportados:
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/minúsculas)
bitand - AND a nivel de bits
regexp - coincidencia sensible a mayúsculas/minúsculas de la expresión regular dada enpatrón
iregexp - coincidencia insensible a mayúsculas/minúsculas de la expresión regular dada enpatrón - patrón es el patrón requerido (los argumentos de tipo string 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ó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/minúsculas se hereda de la configuración de la expresión regular global. Para el propósito de la coincidencia regexp, los valores float siempre se representarán con 4 dígitos decimales después del '.'. 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 el 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.