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.

Nota

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.

Más información sobre absent() en la consola

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.
Expresión 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

Nota

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.

Nota

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.

Intervalo de tiempo máximo devuelto para una consulta

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 (1m) a tres días (3d o 72h). Especifique la cantidad de tiempo en el período de detección de ausencias mediante un número y una unidad (m, h o d para el minuto, la hora o el día).

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 (p al utilizar SDK, CLI o API) durante el intervalo especificado. Los valores válidos son superiores a 0,0 e inferiores a 1,0.

Por ejemplo, percentile(0.8) devuelve el valor del percentil 80.

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)
Descripción absent(): 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.

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 (1m) a tres días (3d o 72h). Especifique la cantidad de tiempo en el período de detección de ausencias mediante un número y una unidad (m, h o d para el minuto, la hora o el día).

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.

Nota

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()