Referencia de Monitoring Query Language (MQL)
Comprenda la sintaxis de las expresiones de Monitoring Query Language (MQL) y revise los valores válidos para operadores de intervalo, estadística y predicado en expresiones MQL.
Para obtener información sobre la edición de MQL, consulte Edición de la expresión MQL para una consulta. Para recuperar un rango temporal específico, como la última hora, consulte Selección de un rango temporal no por defecto para una consulta.
Sintaxis de MQL
La sintaxis MQL regula las expresiones para consultar métricas publicadas en el servicio Monitoring. Las expresiones MQL definen consultas (incluidas consultas de alarma). MQL actúa en datos agregados.
En el siguiente diagrama se muestran los componentes obligatorios y los componentes opcionales comunes.
Algunos componentes pueden aparecer en una expresión MQL varias veces. Por ejemplo, puede utilizar dos funciones de agrupación (como en groupBy()
, seguidas de una estadística, seguida de grouping()
). También puede anidar consultas.
También puede unir varias consultas en una sola consulta.
Para alarmas de la consola, la estadística absent()
se muestra en Operador. Consulte Creación de una alarma de ausencia.
Para seleccionar la estadística absent()
en la consola, consulte las siguientes instrucciones específicas de la página.
- Página Crear alarma o Editar alarma: en modo básico, seleccione ausente en Operador en Regla de disparador. En modo avanzado (seleccione Cambiar a modo avanzado), actualice la expresión MQL.
- Página Explorador de métricas: seleccione Modo avanzado para utilizar MQL.
- Página Métricas de servicio: abra la consulta en el Explorador de Métricas y, a continuación, seleccione Modo avanzado para utilizar MQL.
Para obtener información sobre la lectura de diagramas sintácticos, consulte Lectura de diagramas sintácticos.
Valores válidos para expresiones MQL
Revise los valores válidos para los operadores de intervalo, estadística y predicado en las expresiones MQL.
Intervalo
Junto con intervalo, puede usar la resolución y el rango temporal.
Los valores soportados para la intervalo dependen del rango temporal especificado en la consulta de métricas (no aplicable a las consultas de alarma). Se soportan más valores de intervalo para los rangos de tiempo más pequeños. Por ejemplo, si selecciona una hora para el rango de tiempo, se soportan todos los valores de intervalo. Si selecciona 90 días para el rango de tiempo, solo están soportados valores de intervalo entre 1 hora y 1 día.
Seleccione un intervalo en el que se emite la métrica según la frecuencia. Por ejemplo, una métrica que se emite cada cinco minutos requiere un intervalo o superior de alarma de 5 minutos. La mayoría de las métricas se emiten cada minuto, lo que significa que la mayoría de las métricas soportan cualquier intervalo de alarma. Para determinar la existencia de intervalos de alarma válidos para una métrica específica, consulte la referencia de métrica del servicio pertinente.
- Ejemplo: intervalo de un minuto (
1m
) -
CpuUtilization[1m].mean()
A continuación, se muestran intervalos válidos para la expresión MQL: 1m
-60m
, 1h
-24h
, 1d
Para obtener instrucciones, consulte Selección del intervalo para una consulta.
En la consulta de métricas, el intervalo que seleccione controla la resolución por defecto de la solicitud, lo cual determina el intervalo máximo del tiempo de los datos obtenidos.
En las consultas de alarmas, el intervalo especificado no tiene efecto alguno en la resolución de la solicitud. El único valor válido de la resolución para una solicitud de consulta de alarma es 1m
. Para obtener más información acerca del uso del parámetro de resolución en las consultas de alarmas, consulte Alarma.
El intervalo de tiempo máximo devuelto para una consulta de una métrica depende de la resolución. Por defecto, para las consultas de métricas, la resolución se corresponde con el intervalo de consulta.
El intervalo de tiempo máximo se calcula utilizando la hora actual, independientemente de la hora de finalización especificada. A continuación, se muestran los rangos del tiempo máximos devueltos para cada selección del intervalo disponible en la consola (modo básico)
Intervalo | Resolución por defecto (consultas de métricas) | Intervalo de tiempo máximo devuelto |
---|---|---|
1 minuto Automático (página Métricas de servicio)*, cuando el período de tiempo seleccionado sea de 6 horas o menos |
1 minuto | 7 días |
Cinco (5) minutos Automático (página Métricas de Servicio)*, cuando el período de tiempo seleccionado es superior a 6 horas e inferior a 36 horas |
5 minutos | 30 días |
1 hora Automático (página Métricas de Servicio)*, cuando el período de tiempo seleccionado es superior a 36 horas |
1 hora | 90 días |
1 día |
1 día | 90 días |
* El rango máximo de tiempo que se devuelve cuando selecciona Automático en Intervalo (solo en la página Métricas de servicio) viene determinado por la selección automática del intervalo. La selección automática de intervalos se basa en el período de tiempo seleccionado.
Para especificar una resolución que no sea por defecto y que difiera del intervalo, consulte Selección de una resolución que no es por defecto para una consulta.
- Ejemplo 1 para datos devueltos
- Intervalo de una hora y resolución hasta la hora actual, enviado a las 10:00 del 8.° de enero. No se ha especificado valor alguno para la resolución ni para el tiempo de finalización, así que la resolución adopta por defecto el valor del intervalo de
1m
y la hora de finalización se define por defecto en la hora actual (2023-01-08T10:00:00.789Z
). Esta solicitud devuelve un máximo de 7 días de puntos de datos de métrica. El primer punto de datos posible dentro de este período de siete días sería el 1 de enero a las 10:00 (2023-01-01T10:00:00.789Z
). - Ejemplo 2 para datos devueltos
- Intervalo de cinco minutos con una resolución de un minuto hasta hace dos días, enviado a las 10:00 del 8 del enero. Debido a que la resolución controla el intervalo de tiempo máximo, se devuelve un máximo de 7 días de puntos de datos de métrica. Si bien la hora de finalización especificada era el 6 de enero a las 10:00 (
2023-01-06T10:00:00.789Z
), el primer punto de datos posible dentro de este período de siete días sería el 1 de enero a las 10:00 (2023-01-01T10:00:00.789Z
). Por tanto, en este ejemplo solo se pueden devolver 5 días de puntos de datos de métrica.
Estadística
La estadística es la función de agregación que se aplica al juego de puntos del dato sin formato en la intervalo especificada.
- Ejemplo: estadística media
-
CpuUtilization[1m].mean()
Para obtener instrucciones, consulte Selección de la estadística para una consulta.
A continuación se muestran las estadísticas válidas.
Estadística (expresión MQL) | Opción de estadística (modo básico de la consola) | Descripción |
---|---|---|
absent()
|
(consulte el operador absent) |
Predicado de ausencia. Devuelve true (1) si la métrica está ausente para todo el intervalo. Devuelve false (0) si la métrica está presente durante el intervalo. Se ignora después del período de detección de ausencia, sin generar ningún valor. El periodo de detección de ausencias por defecto es de dos horas. Puede personalizar este período al crear o actualizar una alarma de ausencia. Consulte Personalización del período de detección de ausencias para una consulta de alarma. Los valores válidos van de un minuto ( Utilice esta estadística en consultas básicas y en alarmas de ausencia. Consulte Especificación de un predicado en una consulta. |
avg()
|
(no disponible) | Devuelve el valor de Sum dividido entre Count durante el intervalo especificado. Igual que mean() . |
count()
|
Recuento | Devuelve el número de observaciones recibidas en el intervalo especificado. |
first() |
(no disponible) | Para cada intervalo, devuelve el valor con el primer registro de hora en el intervalo especificado. |
increment()
|
(no disponible) | Devuelve el cambio por intervalo. |
last() |
(no disponible) | Para cada intervalo, devuelve el valor con el último registro de hora en el intervalo especificado. |
max()
|
Máximo | Devuelve el valor más alto observado durante el intervalo especificado. |
mean()
|
Media | Devuelve el valor de Sum dividido entre Count durante el intervalo especificado. |
min()
|
Mínimo | Devuelve el valor más bajo observado durante el intervalo especificado. |
percentile(p)
|
P50 P90 P95 P99 P99,9 (solo página Métricas de servicio) |
Devuelve el valor estimado del percentil especificado ( Por ejemplo, |
rate()
|
Tasa | Devuelve la ratio de cambio media por intervalo. La unidad se indica por segundo. |
sum()
|
Suma | Devuelve todos los valores sumados, por intervalo. |
Operadores de predicado
El componente de predicado solo mantiene los valores especificados de los flujos de métricas. Utilice un operador de predicado para definir un umbral o una ausencia.
- Ejemplo 1: uso medio de la CPU superior al 80 %
-
CpuUtilization[1m].mean() > 80
- Ejemplo 2: uso medio de la CPU entre 60 y 80 por ciento
-
CpuUtilization[1m].mean() in (60, 80)
- Ejemplo 3: Mayor que 1 para errores
-
ServiceConnectorHubErrors[1m].count() > 1
- Ejemplo 4: Uso de CPU del percentil 90 mayor que 85 (predicado de dominio de disponibilidad y agrupación por pool)
-
CpuUtilization[1m]{availabilityDomain = "VeBZ:PHX-AD-1"}.groupBy(poolId).percentile(0.9) > 85
- Ejemplo 5: al menos 20 para el uso mínimo de CPU (seleccionando "ol8" o "ol7")
-
CpuUtilization[1m]{resourceDisplayName =~ "ol8|ol7"}.min() >= 20
- Ejemplo 6: al menos 30 para el uso mínimo de CPU (selección de nombres de instancias que comienzan con "instance-2023-")
-
CpuUtilization[1m]{resourceDisplayName =~ "instance-2023-*"}.min() >= 30
- Ejemplo 7: Ausencia de métricas de uso de CPU para el recurso especificado, definida en 20 horas para el período de detección de ausencias
-
CpuUtilization[1m]{resourceId = "<resource_identifier>"}.groupBy(resourceId).absent(20)
Para obtener instrucciones, consulte Especificación de un predicado en una consulta.
A continuación, se muestran los operadores válidos.
Operador (expresión MQL) | Opción de operador (modo básico de la consola) | Comentarios |
---|---|---|
> |
mayor que | |
>= |
mayor o igual que | |
== |
igual que | |
=~ |
(no disponible) | Coincidencia parcial. |
!= |
(no disponible) | Distinto de. |
<
|
menor que | |
<=
|
menor que o igual a | |
in |
entre (incluidos los valores especificados) | Incluidos los dos valores especificados. |
not in |
fuera de (incluidos los valores especificados) | Incluidos los dos valores especificados. |
(consulte la estadística absent()) | ausente |
Predicado de ausencia. Devuelve true (1) si la métrica está ausente para todo el intervalo. Devuelve false (0) si la métrica está presente durante el intervalo. Se ignora después del período de detección de ausencia, sin generar ningún valor. El periodo de detección de ausencias por defecto es de dos horas. Puede personalizar este período al crear o actualizar una alarma de ausencia. Consulte Personalización del período de detección de ausencias para una consulta de alarma. Los valores válidos van de un minuto ( Utilice esta estadística en consultas básicas y en alarmas de ausencia. Consulte Especificación de un predicado en una consulta. |
Para obtener instrucciones sobre alarmas, consulte Creación de una alarma de umbral y Creación de una alarma de ausencia.
Operadores aritméticos
Los siguientes operadores aritméticos están soportados en las expresiones MQL.
Operador | Descripción |
---|---|
+ |
Agregar |
- |
Restar |
* |
Multiplicar |
/ |
Divide |
% |
Módulo (dividir y devolver el resto) |
Ejemplo 1: Calcule el porcentaje disponible de uso de CPU (métrica CPUUtilization
en el espacio de nombres oci_computeagent
).
100 - CpuUtilization[1m].mean()
Ejemplo 2: Calcular el valor en segundos, en lugar de la unidad de milisegundos por defecto de la métrica (métrica TotalRequestLatency
en el espacio de nombres oci_objectstorage
)
TotalRequestLatency[1m].mean() / 1000
Consultas de unión
Utilice los operadores &&
(AND) y ||
(OR) para unir consultas. Varias consultas unidas actúan como una sola consulta.
Los operadores
&&
(AND) y ||
(OR) solo se pueden utilizar entre consultas. No los utilice entre juegos de dimensiones. Por ejemplo, la siguiente consulta no es válida: CpuUtilization[1m]{faultDomain =~ "FAULT-DOMAIN-1|FAULT-DOMAIN-2" || resourceDisplayName = "test"}.mean()
Operador Unir | Descripción |
---|---|
&& |
AND: unir consultas. Devuelve verdadero si ambos operandos son verdaderos. Devuelve false de lo contrario. |
|| |
OR: unir consultas. Devuelve verdadero si cualquiera de ellos es true o si ambos operandos son true. Devuelve false de lo contrario. |
Ejemplo 1: Unión de consultas con OR. Devolver verdadero si el punto de datos de uso de CPU está en el dominio de errores 1 o 2 O si el punto de datos de uso de memoria está en el dominio de errores 1 o 2.
CpuUtilization[1m]{faultDomain =~ "FAULT-DOMAIN-1|FAULT-DOMAIN-2"}.mean() || MemoryUtilization[1m]{faultDomain =~ "FAULT-DOMAIN-1|FAULT-DOMAIN-2"}.mean()
Ejemplo 2: Unión de consultas de alarma con AND. Disparar la alarma (transición al estado de activación) solo cuando ambas consultas sean verdaderas: existe al menos un error y el error medio es mayor que la mitad.
ServiceConnectorHubErrors[1m].count() > 1 && ServiceConnectorHubErrors[1m].mean() > 0.5
Ejemplo 3: Unión de consultas de alarma con AND. Disparar la alarma (transición al estado de activación) solo cuando ambas consultas sean verdaderas: para lecturas más pequeñas (de 0 a 8 Kilobytes), el percentil 50 de solicitudes supera los 100 Y la latencia media es menor que 0,01.
FileSystemReadRequestsBySize[5m]{resourceType = "filesystem", size = "0B_to_8KiB"}.percentile(.50) > 100 && FileSystemReadAverageLatencybySize[5m]{resourceType = "filesystem", size = "0B_to_8KiB"}.mean() > 0.01
Coincidencia Parcial
Especifique coincidencias aproximadas ("parciales") con los valores de dimensión en una expresión MQL.
Utilice la coincidencia parcial al especificar varios valores para un nombre de dimensión.
En lugar del signo igual (=
) entre el juego de valores, utilice el siguiente operador.
Operador de comparación | Descripción |
---|---|
=~ (signo igual seguido de virgulilla) |
Aproximadamente igual a. Usar para coincidencias parciales |
Para la coincidencia parcial, rodee el juego de valores con comillas: name = "val*"
o name = "value1|value2"
Actualice el juego de valores con uno o más de los siguientes caracteres.
Carácter de coincidencia parcial de valor | Descripción |
---|---|
* (asterisco) |
Comodín, que indica de cero a muchos caracteres. |
| (pleca) |
Operando OR para valores de dimensión. |
Ejemplo que muestra la coincidencia parcial para dos posibles nombres de recursos ("ol8" o "ol7"):
CpuUtilization[1m]{resourceDisplayName =~ "ol8|ol7"}.min() >= 20
Ejemplo que muestra una coincidencia parcial para los nombres de recursos que contienen la frase "instance-2023-":
CpuUtilization[1m]{resourceDisplayName =~ "instance-2023-*"}.min() >= 30
Ejemplo en el que se muestra la coincidencia parcial para tres conjuntos de valores de dimensión (coincidencia parcial para instancias informáticas de prueba en el dominio de errores 1 que utilizan la unidad myshape
):
CpuUtilization [1m]{faultDomain =~ "FAULT-DOMAIN-1", resourceDisplayName =~ "test*", shape =~ "myshape"}.mean()