Referência do Monitoring Query Language (MQL)
Entenda a sintaxe de expressões MQL (Monitoring Query Language) e revise os valores válidos para operadores de intervalo, estatística e predicado nas expressões MQL.
Para obter informações sobre a edição do MQL , consulte Editando a Expressão MQL para uma Consulta. Para recuperar um intervalo de tempo específico, como a última hora, consulte Selecionando um Intervalo de Tempo Não Padrão para uma Consulta.
Sintaxe MQL
A sintaxe do MQL controla expressões para consultar métricas publicadas no serviço Monitoring. As expressões MQL definem consultas (incluindo consultas de alarme). O MQL age nos dados agregados.
O diagrama a seguir descreve os componentes obrigatórios e os componentes opcionais comuns.
Alguns componentes podem aparecer em uma expressão MQL várias vezes. Por exemplo, você pode usar duas funções de agrupamento (como em groupBy(), seguido por uma estatística, seguida por grouping()). Você também pode aninhar consultas.
Você também pode juntar várias consultas em uma única consulta.
Para alarmes na Console, a estatística absent() é listada em (Operador). Consulte Criando um Alarme de Ausência.
Para selecionar a estatística absent() na Console, consulte as seguintes instruções específicas da página.
- Página Criar Alarme ou Editar alarme: No modo Básico, selecione ausente em Operador em Regra de acionamento. No modo Avançado (selecione Alternar para o Modo Avançado), atualize a expressão MQL.
- Página Explorador de Métrica: Selecione Modo avançado para usar o MQL.
- Página Métricas do Serviço: Abra a consulta no Metrics Explorer e selecione Modo avançado para usar o MQL.
Para obter informações sobre como ler diagramas de ferrovia, consulte Lendo Diagramas de Ferrovia.
Valores Válidos para Expressões MQL
Verifique valores válidos para operadores de intervalo, estatística e predicado em expressões MQL.
Intervalo
Com o intervalo, considere a resolução e o intervalo de tempo.
Os valores suportados para o intervalo dependem do intervalo de tempo especificado na consulta métrica (não aplicável a consultas de alarme). Mais valores de intervalo são suportados para intervalos de tempo menores. Por exemplo, se você selecionar uma hora para o intervalo de tempo, todos os valores de intervalo serão suportados. Se você selecionar 90 dias para o intervalo de tempo, só haverá suporte para os valores de intervalo entre 1 hora e 1 dia.
Selecione um intervalo para alarme com base na frequência em que a métrica é emitida. Por exemplo, uma métrica emitida a cada cinco minutos requer um intervalo ou mais de 5 minutos de alarme. A maioria das métricas é emitida a cada minuto, o que significa que a maioria das métricas suporta qualquer intervalo de alarme. Para determinar intervalos de alarme válidos para uma métrica específica, verifique a referência de métrica do serviço relevante.
- Exemplo: Intervalo de Um Minuto (
1m) -
CpuUtilization[1m].mean()
Estes são os intervalos válidos para expressões MQL: 1m-60m, 1h-24h, 1d
Para obter instruções, consulte Selecionando o Intervalo de uma Consulta.
Para consultas métricas, o intervalo que você seleciona direciona a resolução padrão da solicitação, que determina a faixa de tempo máximo dos dados retornados.
Para consultas de alarme, o intervalo especificado não tem efeito na resolução da solicitação. O único valor válido da resolução de uma solicitação de consulta de alarme é 1m. Para obter mais informações sobre o parâmetro de resolução como usado em consultas de alarme, consulte Alarme.
O intervalo de tempo máximo retornado para uma consulta de métrica depende da resolução. Por padrão, para consultas de métrica, a resolução é a mesma do intervalo de consulta.
O intervalo de tempo máximo é calculado usando o horário atual, independentemente de qualquer horário final especificado. A seguir estão as faixas de tempo máximas retornadas para cada seleção do intervalo disponível na Console (modo Básico).
| Intervalo | Resolução padrão (consultas de métrica) | Intervalo de tempo máximo retornado |
|---|---|---|
|
1 minuto Automático (página Métricas de Serviço)*, quando o período selecionado for de 6 horas ou menos |
1 minuto | 7 dias |
|
5 minutos Automático (página Métricas de Serviço)*, quando o período selecionado for maior que 6 horas e menor que 36 horas |
5 minutos | 30 dias |
|
1 hora Automático (página Métricas de Serviço)*, quando o período selecionado é maior que 36 horas |
1 hora | 90 dias |
|
1 dia |
1 dia | 90 dias |
* A faixa de tempo máxima retornada quando você seleciona Automático para a página Intervalo (apenas Métricas de Serviço) é determinada pela seleção de intervalo automático. A seleção automática de intervalo é baseada no período selecionado.
Para especificar uma resolução não padrão que difere do intervalo, consulte Selecionando uma Resolução Não Default para uma Consulta.
- Exemplo 1 para Dados Retornados
- Intervalo de um minuto e resolução até o horário atual, enviados às 10:00 em 8 de janeiro. Nenhuma resolução ou horário final foi especificado, portanto, a resolução assume como padrão o valor do intervalo de
1me o horário final é definido como o horário atual (2023-01-08T10:00:00.789Z). Esta solicitação retorna um máximo de 7 dias de pontos de dados da métrica. O ponto de dados mais antigo possível dentro desse período de sete dias seria 10:00 em 1º de janeiro (2023-01-01T10:00:00.789Z). - Exemplo 2 para Dados Retornados
- Intervalo de cinco minutos com resolução de um minuto até dois dias atrás, enviado às 10:00 em 8. de janeiro. Como a resolução conduz ao intervalo de tempo máximo, é retornado um máximo de 7 dias de pontos de dados da métrica. Embora o horário final especificado seja 10:00 em 6 de janeiro (
2023-01-06T10:00:00.789Z), o ponto de dados mais antigo possível nesse período de sete dias seria 10:00 em 1º de janeiro (2023-01-01T10:00:00.789Z). Portanto, apenas 5 dias de pontos de dados da métrica podem ser retornados neste exemplo.
Estatística
A estatística é a função de agregação aplicada ao conjunto de ponto de dados brutos na intervalo especificada.
- Exemplo: Estatística Média
-
CpuUtilization[1m].mean()
Para obter instruções, consulte Selecionando a Estatística de uma Consulta.
Veja a seguir as estatísticas válidas.
| Estatística (expressão MQL) | Opção estatística (Modo Básico na Console) | Descrição |
|---|---|---|
absent()
|
(consulte o operador absent) |
Predicado de ausência. Retornará verdadeiro (1) se a métrica estiver ausente para todo o intervalo. Retornará falso (0) se a métrica estiver presente durante o intervalo. É ignorado após o período de detecção de ausência, sem gerar valores. O período de detecção de ausência padrão é de duas horas. Você pode personalizar esse período ao criar ou atualizar um alarme de ausência. Consulte Personalizando o Período de Detecção de Ausência para uma Consulta de Alarme. Os valores válidos variam de um minuto ( Use essa estatística em consultas básicas, bem como em alarmes de ausência. Consulte Especificando um Predicado em uma Consulta. |
avg()
|
(não disponível) | Retorna o valor da Soma dividido pela Contagem durante o intervalo especificado. Idêntico a mean(). |
count()
|
Contagem | Retorna o número de observações recebidas no intervalo especificado. |
first() |
(não disponível) | Para cada intervalo, retorna o valor com o timestamp mais antigo no intervalo especificado. |
increment()
|
(não disponível) | Retorna a alteração por intervalo. |
last() |
(não disponível) | Para cada intervalo, retorna o valor com o timestamp mais recente no intervalo especificado. |
max()
|
Máx. | Retorna o valor mais alto observado durante o intervalo especificado. |
mean()
|
Média | Retorna o valor da Soma dividido pela Contagem durante o intervalo especificado. |
min()
|
Mín. | Retorna o valor mais baixo observado durante o intervalo especificado. |
percentile(p)
|
P50 P90 P95 P99 P99.9 (somente página Métricas de Serviço) |
Retorna o valor estimado do percentil especificado ( Por exemplo, |
rate()
|
Taxa | Retorna a taxa média de alteração por intervalo. A unidade é por segundo. |
sum()
|
Soma | Retorna todos os valores adicionados juntos, por intervalo. |
Operadores de Predicado
O componente de predicado mantém apenas valores especificados dos streams de métrica. Use um operador de predicado para definir um limite ou uma ausência.
- Exemplo 1: Maior que 80% para a Média de Utilização da CPU
-
CpuUtilization[1m].mean() > 80 - Exemplo 2: Entre 60 e 80 por cento para a Média de Utilização da CPU
-
CpuUtilization[1m].mean() in (60, 80) - Exemplo 3: Maior que 1 para Erros
-
ServiceConnectorHubErrors[1m].count() > 1 - Exemplo 4: Maior que 85 para Utilização de CPU do 90º Percentil (Selecionando um Domínio da Disponibilidade e Agrupamento por Pool)
-
CpuUtilization[1m]{availabilityDomain = "VeBZ:PHX-AD-1"}.groupBy(poolId).percentile(0.9) > 85 - Exemplo 5: Pelo Menos 20 para Utilização Mínima da CPU (Selecionando "ol8" ou "ol7")
-
CpuUtilization[1m]{resourceDisplayName =~ "ol8|ol7"}.min() >= 20 - Exemplo 6: Pelo Menos 30 para Utilização Mínima da CPU (Selecionando Nomes de Instâncias que Começam com "instance-2023-")
-
CpuUtilization[1m]{resourceDisplayName =~ "instance-2023-*"}.min() >= 30 - Exemplo 7: Ausência de Métricas de Utilização da CPU para Recurso Especificado, definido como 20 horas para o período de detecção de ausência
-
CpuUtilization[1m]{resourceId = "<resource_identifier>"}.groupBy(resourceId).absent(20)
Para obter instruções, consulte Especificando um Predicado em uma Consulta.
Veja a seguir os operadores válidos.
| Operador (expressão MQL) | Opção do operador (Modo Básico na Console) | Comentários |
|---|---|---|
> |
maior que | |
>= |
maior que ou igual a | |
== |
igual a | |
=~ |
(não disponível) | Correspondência Difusa. |
!= |
(não disponível) | Diferente de. |
<
|
menor que | |
<=
|
menor que ou igual a | |
in |
entre (incluindo valores especificados) | Incluindo os dois valores especificados. |
not in |
fora (incluindo de valores especificados) | Incluindo os dois valores especificados. |
| (consulte a estatística absent()) | ausente |
Predicado de ausência. Retornará verdadeiro (1) se a métrica estiver ausente para todo o intervalo. Retornará falso (0) se a métrica estiver presente durante o intervalo. É ignorado após o período de detecção de ausência, sem gerar valores. O período de detecção de ausência padrão é de duas horas. Você pode personalizar esse período ao criar ou atualizar um alarme de ausência. Consulte Personalizando o Período de Detecção de Ausência para uma Consulta de Alarme. Os valores válidos variam de um minuto ( Use essa estatística em consultas básicas, bem como em alarmes de ausência. Consulte Especificando um Predicado em uma Consulta. |
Para obter instruções sobre alarme, consulte Criando um Alarme de Limite e Criando um Alarme de Ausência.
Operadores Aritméticos
Os operadores aritméticos a seguir são suportados em expressões MQL.
| Operador | Descrição |
|---|---|
+ |
Adicionar |
- |
Subtrair |
* |
Multiplicar |
/ |
Divide |
% |
Modulo (dividir e devolver o restante) |
Exemplo 1: Calcule a porcentagem disponível de utilização da CPU (métrica CPUUtilization no namespace oci_computeagent).
100 - CpuUtilization[1m].mean()Exemplo 2: Calcular o valor em segundos, em vez da unidade padrão de milissegundos da métrica (métrica TotalRequestLatency no namespace oci_objectstorage)
TotalRequestLatency[1m].mean() / 1000Associar Consultas
Use os operadores && (AND) e || (OR) para unir consultas. Várias consultas unidas atuam como uma única consulta.
Os operadores
&& (AND) e || (OR) só podem ser usados entre consultas. Não use-os entre conjuntos de dimensões. Por exemplo, a seguinte consulta é inválida: CpuUtilization[1m]{faultDomain =~ "FAULT-DOMAIN-1|FAULT-DOMAIN-2" || resourceDisplayName = "test"}.mean()| Operador JOIN | Descrição |
|---|---|
&& |
AND: Juntar consultas. Retorna verdadeiro se os dois operandos forem verdadeiros. Retorna falso caso contrário. |
|| |
OR: Participar de consultas. Retorna verdadeiro se o operando for verdadeiro ou se os dois operandos forem verdadeiros. Retorna falso caso contrário. |
Exemplo 1: Unir consultas com OR. Retornará verdadeiro se o ponto de dados de utilização de CPU estiver no domínio de falha 1 ou 2 OU se o ponto de dados de utilização de memória estiver no domínio de falha 1 ou 2.
CpuUtilization[1m]{faultDomain =~ "FAULT-DOMAIN-1|FAULT-DOMAIN-2"}.mean() || MemoryUtilization[1m]{faultDomain =~ "FAULT-DOMAIN-1|FAULT-DOMAIN-2"}.mean()Exemplo 2: Unir consultas de alarme com AND. Acione o alarme (transição para o estado de acionamento) somente quando ambas as consultas forem verdadeiras: Existe pelo menos um erro E a média do erro é maior que a metade.
ServiceConnectorHubErrors[1m].count() > 1 && ServiceConnectorHubErrors[1m].mean() > 0.5Exemplo 3: Unir consultas de alarme com AND. Acione o alarme (transição para o estado de acionamento) somente quando ambas as consultas forem verdadeiras: Para leituras menores (0 a 8 Kilobytes), o percentil 50 de solicitações excede 100 E a latência média é 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.01Correspondência Difusa
Especifique correspondências aproximadas ("parciais") com valores de dimensão em uma expressão MQL.
Use a correspondência difusa ao especificar vários valores para um nome de dimensão.
No lugar do sinal igual (=) antes do conjunto de valores, use o seguinte operador da comparação.
| Operador de comparação | Descrição |
|---|---|
=~ (sinal de igual seguido por til) |
aproximadamente igual a. Usar para correspondências difusas |
Para correspondência difusa, coloque o conjunto de valores entre aspas: name = "val*" ou name = "value1|value2"
Atualize o conjunto de valores usando um ou mais dos seguintes caracteres.
| Caractere de Correspondência Parcial de Valor | Descrição |
|---|---|
* (asterisco) |
Curinga, indicando de zero a muitos caracteres. |
| (barra vertical) |
Operando OR para valores de dimensão. |
Exemplo mostrando correspondência difusa para dois nomes de recursos possíveis ("ol8" ou "ol7"):
CpuUtilization[1m]{resourceDisplayName =~ "ol8|ol7"}.min() >= 20Exemplo mostrando correspondência difusa para nomes de recursos que contêm a frase "instance-2023-":
CpuUtilization[1m]{resourceDisplayName =~ "instance-2023-*"}.min() >= 30Exemplo mostrando correspondência difusa para três conjuntos de valores de dimensão (testar instâncias de computação no domínio de falha 1 que usam a forma myshape):
CpuUtilization [1m]{faultDomain =~ "FAULT-DOMAIN-1", resourceDisplayName =~ "test*", shape =~ "myshape"}.mean()