Table of Contents
1 Funciones Foreach
Visión general
Las funciones foreach se utilizan en cálculos agregados para devolver un valor agregado para cada métrica que es seleccionada por el filtro de métricas utilizado. Se devuelve un array de valores.
Por ejemplo, la función avg_foreach devolverá un array de valores, donde cada valor es el valor promedio del historial de la métrica seleccionada, durante el intervalo de tiempo especificado.
El filtro de métricas es parte de la sintaxis utilizada por las funciones foreach. Se admite el uso de comodines en el filtro de métricas, por lo que las métricas requeridas pueden seleccionarse de manera bastante flexible.
Funciones soportadas
| Función | Descripción |
|---|---|
| avg_foreach | Devuelve el valor promedio para cada métrica. |
| bucket_rate_foreach | Devuelve pares (límite superior del bucket, valor de 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 métrica definido 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 para 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 para 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 periodo de tiempo:
Por ejemplo:
avg_foreach(/*/mysql.qps?[group="MySQL Servers"],5m)
devolverá la media de cinco minutos de cada métrica 'mysql.qps' en el grupo de equipos MySQL.
Tenga en cuenta que algunas funciones admiten parámetros adicionales.
Sintaxis del filtro de métricas
El filtro de métricas:
consta de cuatro partes, donde:
- equipo - nombre del equipo
- clave - clave de la métrica (sin parámetros)
- parámetros - parámetros de la clave de la métrica
- condiciones - condiciones basadas en grupo de equipos y/o etiquetas de métricas (como expresión)
Los espacios solo se permiten dentro de la expresión de condiciones.
Uso de comodines
- El comodín puede usarse para reemplazar el nombre del equipo, la clave de la métrica o un parámetro individual de la clave de la métrica.
- O bien el equipo o la clave de la métrica deben especificarse sin comodín. Así,
/equipo/*y/*/claveson filtros válidos, pero/*/*no es válido. - El comodín no puede usarse para una parte del nombre del equipo, la clave de la métrica o el parámetro de la clave de la métrica.
- El comodín no coincide con más de un parámetro de la clave de la métrica. Por lo tanto, debe especificarse un comodín para cada parámetro por separado (es decir,
clave[abc,*,*]).
Expresión de condiciones
La expresión de condiciones admite:
- operandos:
- group - grupo de equipos
- tag - etiqueta de la métrica
"<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. Solo se admite la comparación de cadenas completas y sensible a mayúsculas y minúsculas.
Al especificar etiquetas en el filtro (es decir, tag="nombreetiqueta:valor"), 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 ":" en él.
Ejemplos
Se puede utilizar un filtro complejo, haciendo referencia a la clave de la métrica, grupo de equipos y etiquetas, como se ilustra en los ejemplos:
| Ejemplo de sintaxis | Descripción |
|---|---|
/equipo/clave[abc,*] |
Coincide con métricas similares en este equipo. |
/*/clave |
Coincide con la misma métrica de cualquier equipo. |
/*/clave?[group="ABC" and tag="nombreetiqueta:valor"] |
Coincide con la misma métrica de cualquier equipo del grupo ABC que tenga etiquetas 'nombreetiqueta:valor'. |
/*/clave[a,*,c]?[(group="ABC" and tag="Tag1") or (group="DEF" and (tag="Tag2" or tag="Tag3:valor"))] |
Coincide con métricas similares de cualquier equipo del grupo ABC o DEF con las etiquetas respectivas. |
Todas las métricas referenciadas deben existir y recopilar datos. Solo las métricas habilitadas en equipos habilitados se incluyen en los cálculos. Las métricas en estado no soportado no se incluyen.
Si se cambia la clave de la métrica de una métrica referenciada, el filtro debe actualizarse manualmente.
Especificar un grupo de equipos principal incluye el grupo principal y todos los grupos de equipos anidados con sus métricas.
Período 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 soportados 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 (soportado 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 de la métrica. Por ejemplo, si el valor "bucket" en miMétrica[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 las métricas (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)
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 tipo 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ónpuede especificarse como dos números, separados por '/': número_a_comparar/mascara. count_foreach() calcula el "AND a nivel de bits" entre el valor y la mascara y compara el resultado con número_a_comparar. Si el resultado del "AND a nivel de bits" es igual a número_a_comparar, el valor se cuenta.
Si número_a_comparar y mascara son iguales, solo es necesario especificar la mascara (sin '/'). - Con regexp o iregexp como tercer parámetro, el cuarto parámetro
patrónpuede 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 la expresión regular global. Para el propósito de la coincidencia regexp, los valores flotantes 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 al cuarto dígito decimal.
Consulte cálculos agregados para más detalles y ejemplos sobre el uso de funciones foreach.
Comportamiento según la disponibilidad
La siguiente tabla ilustra cómo se comporta cada función en casos de disponibilidad limitada del equipo/métrica y de los datos históricos.
| Función | Equipo deshabilitado | Equipo no disponible con datos | Equipo no disponible sin datos | Métrica deshabilitada | Métrica no soportada | Error al recuperar datos (SQL) |
|---|---|---|---|---|---|---|
| avg_foreach | ignorar | devolver promedio | ignorar | ignorar | ignorar | ignorar |
| bucket_rate_foreach | ignorar | devolver bucket rate | ignorar | ignorar | ignorar | ignorar |
| count_foreach | ignorar | devolver recuento | 0 | ignorar | ignorar | ignorar |
| exists_foreach | ignorar | 1 | 1 | ignorar | 1 | n/a |
| last_foreach | ignorar | devolver último | ignorar | ignorar | ignorar | ignorar |
| max_foreach | ignorar | devolver máximo | ignorar | ignorar | ignorar | ignorar |
| min_foreach | ignorar | devolver mínimo | ignorar | ignorar | ignorar | ignorar |
| sum_foreach | ignorar | devolver suma | ignorar | ignorar | ignorar | ignorar |
Si la métrica es ignorada, no se añade nada a la agregación.