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 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 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 parámetro <número de 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 de filtro de métricas
El filtro de métricas:
consta de cuatro partes, donde:
- host - nombre del anfitrión
- key - clave de métrica (sin parámetros)
- parameters - parámetros clave de la métrica
- conditions: condiciones basadas en grupo de equipos y/o etiqueta de métrica (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 del 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 condiciones
La expresión de condiciones admite:
- operandos:
- group - grupo de equipos
- tag - etiqueta de la 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:
()
La cita de 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 de cualquier equipo. |
/*/key?[group="ABC" and tag="tagname:value"] |
Coincide con la misma métrica de cualquier equipo del grupo ABC que tenga etiquetas 'tagname:value'. |
/*/key[a,*,c]?[(group="ABC" and tag="Etiqueta1") or (group="DEF" and (tag="Etiqueta2" or 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 los 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.
Si se cambia la clave de la 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 equipos de los grupos de equipos anidados con sus métricas.
Periodo de tiempo
El segundo parámetro permite especificar el período de tiempo para la agregación. El período de tiempo sólo puede expresarse como tiempo, la cantidad de valores (con el prefijo #) no es compatible.
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).
El servidor ignora el período de tiempo si se pasa con la función last_foreach y por lo tanto se puede omitir:
El período de tiempo no es compatible con la función exists_foreach.
Parámetros adicionales
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'.
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 | ignorar | retornar promedio | ignorar | ignorar | ignorar | ignorar |
| bucket_rate_foreach | ignorar | tasa de retorno del depósito | ignorar | ignorar | ignorar | ignorar |
| count_foreach | ignorar | retornar recuento | 0 | ignorar | ignorar | ignorar |
| exists_foreach | ignorar | 1 | 1 | ignorar | 1 | n/a |
| last_foreach | ignorar | retornar último | ignorar | ignorar | ignorar | ignorar |
| max_foreach | ignorar | retornar max | ignorar | ignorar | ignorar | ignorar |
| min_foreach | ignorar | retornar min | ignorar | ignorar | ignorar | ignorar |
| sum_foreach | ignorar | retornar suma | ignorar | ignorar | ignorar | ignorar |
Si la métrica se ignora, no se agrega nada a la agregación.