Como usar o Editor de consultas

Nesta seção, descrevemos os recursos do Editor de consultas do Monitoring para a linguagem de consulta (MQL, na sigla em inglês). O editor está disponível no Console do Google Cloud e oferece sugestões, detecção de erros e outro suporte para a criação de consultas MQL válidas.

Esta página não abrange a linguagem MQL. Para um conjunto de exemplos e mais informações sobre a linguagem, consulte Exemplos e Sobre a linguagem MQL. A Referência de MQL fornece uma referência abrangente da linguagem.

Como acessar o Editor de consultas

O Editor de consultas pode ser acessado nas seguintes páginas do Console do Google Cloud:

  • Metrics Explorer
  • Adicionar gráfico ao criar painéis

A captura de tela a seguir usa o Metrics Explorer como exemplo:

O seletor MQL aparece logo acima da caixa "Tipo de recurso e métrica".

Para abrir o Editor de consultas, clique em Editor de consultas na guia Métrica. A captura de tela a seguir mostra o Editor de consultas:

Editor de consultas MQL.

Como usar o Editor de consultas

Para usar o Editor de consultas, digite sua consulta na caixa de texto e clique em Executar consulta:

Consulta MQL no Editor de consultas.

Preenchimento automático

Conforme você digita sua consulta, o editor exibe uma lista de preenchimentos sintaticamente válidos. Abra manualmente o menu de preenchimento automático pressionando Control+Space e dispense-o pressionando Escape.

Para navegar na lista de opções, use as teclas de seta. Pressionar Enter insere a opção selecionada.

Para inserir o prefixo comum a todas as opções disponíveis, pressione Tab.

Mensagens de erro

As mensagens de erro aparecem na parte inferior do painel do editor.

Se houver erros na consulta que interfiram nas sugestões de preenchimento automático, serão exibidas mensagens de erro enquanto você digita. Caso contrário, mensagens de erro serão exibidas quando você executar a consulta.

Dobragem do código

O editor fornece dobramento de código (a capacidade de recolher segmentos de suas consultas) para que você possa ocultá-los temporariamente da visualização.

O editor indica segmentos dobráveis da sua consulta com cursores ao lado dos números de linha, conforme mostrado na captura de tela a seguir:

O Editor de consultas indica o código dobrável com acentos.

Localizar e substituir

O editor é compatível com um recurso de localizar e substituir. Para encontrar e, opcionalmente, substituir, termos em sua consulta, pressione Control+F (ou Command+F no Mac). A captura de tela a seguir mostra o recurso:

O Editor de consultas é compatível com um recurso de localizar e substituir.

Controles do Editor

O editor tem três controles que determinam como ele interage com sua consulta.

Controles do Editor de consultas do MQL

Por padrão, sua consulta é executada somente quando você clica em Executar consulta. É possível configurar o Editor de consultas para executar automaticamente sua consulta enquanto digita, mas essa opção é desativada por padrão.

Para ativar a opção de execução automática, use a opção Execução automática. Quando essa opção está ativada, o editor funciona da seguinte maneira:

  • O botão Executar consulta não é exibido.
  • As mensagens de erro aparecem enquanto você digita.
  • Se o cursor estiver no final de uma consulta incompleta, mas sem erros, o editor mostrará um triângulo amarelo na barra de controle. Se houver espaço, o texto Consulta incompleta também será exibido.

    O Editor de consultas não tenta avaliar consultas incompletas.

Para reformatar a consulta e torná-la mais legível, clique em Formato. A reformatação da consulta não altera o significado dela. A reformatação usa um comprimento de linha de 80 caracteres. Portanto, se a janela do Editor de consultas for menor que isso, as linhas serão ajustadas.

Há também uma barra de captura entre o Editor de consultas e a região do gráfico. Use essa barra para alterar os tamanhos relativos das duas regiões.

Como salvar gráficos

No Metrics Explorer

No Editor de consultas do Metrics Explorer, você tem a opção de salvar o gráfico em um painel. Para salvar o gráfico, faça o seguinte:

  1. Se a opção de execução automática não estiver ativada, execute a consulta clicando em Executar consulta antes de salvar o gráfico. Se você não executar a consulta primeiro, o "Editor de consultas" salvará a última consulta que você executou.

  2. Clique em Salvar gráfico. Uma caixa de diálogo informa que salvar o gráfico substitui a consulta por uma forma restrita. Veja mais informações em Consultas de formulário restrito.

  3. Para continuar salvando o gráfico:

    1. Dê um título descritivo ao gráfico.
    2. Selecione o painel desejado para o novo gráfico.
    3. Clique em Salvar na caixa de diálogo.

Em um painel

Para salvar um gráfico que você está adicionando a um painel, faça o seguinte:

  1. Dê um título descritivo ao gráfico.

  2. Se a opção de execução automática não estiver ativada, execute a consulta clicando em Executar consulta antes de salvar o gráfico. Se você não executar a consulta primeiro, o "Editor de consultas" salvará a última consulta que você executou.

  3. Clique em Save. Uma caixa de diálogo informa que salvar o gráfico substitui a consulta por uma forma restrita. Veja mais informações em Consultas de formulário restrito.

  4. Clique em Salvar na caixa de diálogo para salvar o gráfico e retornar ao painel.

Como sair do Editor de consultas

Para sair do Editor de consultas sem salvar um gráfico ou uma condição, clique em Voltar ao widget do seletor de consulta. Qualquer texto de consulta no editor é descartado, mas você tem a opção de salvá-lo na área de transferência.

Intervalos de tempo, gráficos e o Editor de consultas

Exceto para consultas MQL usadas em condições para políticas de alertas, as consultas MQL no Editor de consultas precisam incluir um período. O período especifica o subconjunto de dados retornados como parte da consulta.

O período pode ser expresso implicitamente, usando o seletor de tempo do gráfico, ou explicitamente, no texto da consulta MQL.

Para informações sobre como criar políticas de alertas com o Editor de consultas, consulte Como criar políticas de alertas MQL.

Como usar as configurações de gráfico para seleção de tempo

É possível definir o período de uma consulta usando o seletor de tempo do gráfico. Esse seletor é a maneira padrão de definir o período. Para alterar o período, selecione outra opção no gráfico. Se você selecionar, por exemplo, uma semana, a consulta retornará os dados de agora até uma semana atrás.

A MQL pode usar horários especificados no gráfico.

Ao usar esse mecanismo padrão, você não precisa especificar um intervalo de tempo no texto da consulta. O valor no gráfico é usado implicitamente.

Como usar within para selecionar o tempo

É possível especificar o intervalo de tempo da consulta explicitamente usando a operação within. Essa operação determina o intervalo de dados retornados. Se a consulta incluir uma operação within, as opções de seleção de tempo no gráfico serão desativadas e o intervalo de tempo especificado na consulta será usado.

Se você remover uma operação within explícita da consulta, as opções do gráfico serão reativadas automaticamente, garantindo que a consulta sempre inclua um período.

É necessário usar a seleção explícita de tempo se você quiser usar o método de API timeSeries.query para emitir a consulta. Para mais informações, consulte Como usar o MQL da API Monitoring.

Configurações de hora e gráficos salvos

Se você usa a MQL para criar um gráfico e salvá-lo em um painel, duas coisas acontecem com a consulta:

  1. A consulta que você forneceu no editor é convertida em um formulário canônico ou restrito. A conversão não altera o significado da consulta, mas explicita coisas que são assumidas na consulta, como nomes de coluna completos ou operações de alinhamento. Para mais informações, veja Consultas de formato restrito.

  2. A seleção do intervalo de tempo é removida da consulta. Os gráficos nos painéis compartilham um seletor de tempo. As alterações nesse seletor se aplicam a todos os gráficos no painel. Portanto, o seletor de intervalo de tempo da consulta original não é mais necessário.

Para informações sobre como gerenciar painéis e editar gráficos, consulte Como gerenciar painéis.

Consultas, alinhamento e períodos de exibição

A MQL tem diversas operações potencialmente confusas que especificam períodos. As operações a seguir estão relacionadas ao intervalo de uma consulta:

  • within: especifica a janela de saída da consulta. Essa operação determina a quantidade de dados retornados. Por exemplo, se você especificar within 1h, a consulta produzirá apenas os pontos com carimbos de data/hora na última hora. É por isso que essa operação modifica as opções de seletor de horário do gráfico.

  • As operações a seguir estão relacionadas ao período de alinhamento das tabelas de saída. Ambas exigem uma tabela alinhada como entrada ou fornecem uma padrão:

    • every: especifica o período da saída de tabela alinhada.

    • window: especifica a janela das operações de alinhamento.

    Em ambos os casos, se uma operação align for fornecida com uma janela de alinhamento explícita, ela precisará corresponder ao período especificado para a operação window, se fornecida. Para a função de alinhamento delta, o ponto e a janela de alinhamento precisam ser iguais. Se for fornecida uma janela de alinhamento explícita, a operação every, se fornecida, precisará concordar. Em todos os casos, a janela de alinhamento precisa ser pelo menos tão grande quanto o período de alinhamento. Caso contrário, os dados de entrada serão ignorados.

A MQL também tem uma operação graph_period, que especifica o período dos pontos de saída dos gráficos. Essa operação é útil em consultas solicitadas à API cuja saída está sendo mapeada em um gráfico por um software de terceiros. O software de gráficos do Monitoring ignora a operação graph_period nas consultas, definindo o período de pontos de acordo com a largura no tempo do gráfico de saída.

Em gráficos do Monitoring, o período do gráfico é definido com base no valor do seletor de intervalo do gráfico. Por exemplo, se você selecionar uma semana, o período do gráfico poderá ser de uma hora. Esse valor é mostrado em uma caixa pequena com cantos arredondados, chamada de ícone, na região do gráfico. O ícone que mostra o período do gráfico tem um rótulo como 1 hr interval. A captura de tela a seguir mostra um ícone de gráfico de período que indica um intervalo de uma hora e o seletor de horário do gráfico definido como uma semana:

O seletor de horário do gráfico determina o período do gráfico, exibido em um ícone no gráfico.

A relação entre o período de alinhamento da consulta e o período do gráfico pode alterar a aparência do gráfico. Esse relacionamento é descrito na seção a seguir.

Larguras de banda mínimas/máximas

Quando o período de alinhamento da consulta é próximo ao período do gráfico, o gráfico representa cada série temporal mapeada no gráfico com uma única linha. Se o período de alinhamento da consulta for menor que metade do período do gráfico, o gráfico incluirá uma região sombreada em torno de cada linha. Essa região, chamada de largura de banda mínima/máxima, mostra o intervalo de valores que produziu o valor médio.

Por exemplo, suponhamos a seguinte consulta MQL simples:

fetch gce_instance::compute.googleapis.com/instance/cpu/utilization
| group_by [zone], mean(val())
| every 1h

Essa consulta retorna a utilização média de CPU das VMs por zona, com um período de alinhamento de uma hora.

Se o seletor de tempo do gráfico for definido como uma semana, o período do gráfico será uma hora, indicado em um ícone. Na consulta de exemplo, o período do gráfico e o período de alinhamento são iguais. A execução da consulta produz um gráfico que tem a seguinte aparência:

Um gráfico de linhas com alinhamento e períodos de gráfico iguais mostra apenas linhas.

Por exemplo, se você alterar o período de alinhamento transmitido para a operação every de 1h para 1m na consulta anterior, a consulta produzirá um gráfico que inclui a largura de banda mínima/máxima:

Um gráfico de linhas com um período de alinhamento inferior a metade do período mostra as linhas e largura de banda mínima/máxima.

As linhas do gráfico são representadas com períodos de gráficos de uma hora, com base na seleção de uma semana do gráfico. Portanto, as linhas são iguais às do exemplo anterior. Entretanto, a consulta produz um ponto a cada minuto. Portanto, as larguras de banda mínima/máxima mostram o intervalo de valores de um minuto da consulta que se enquadram em cada ponto do gráfico de uma hora.

Se a operação every for omitida, o período de alinhamento da consulta padrão será o valor da janela de alinhamento ou, se a janela de alinhamento não for especificada, um minuto.

Políticas de alertas baseadas em MQL

Também é possível usar a MQL e o Editor de consultas para criar consultas para uso em políticas de alertas.

Para criar uma política de alertas baseada em MQL no Console do Google Cloud, siga as etapas habituais de criação da política, descritas em Como gerenciar políticas de alertas, mas ao criar a condição da política de alertas, use o Editor de consultas em vez do seletor de métricas com base em formulários.

Para mais informações, consulte Como criar políticas de alertas MQL.

Conversão de consulta

É possível usar o seletor de métricas para gráficos ou no Metrics Explorer para criar uma consulta e convertê-la em MQL clicando em Editor de consultas. A consulta MQL correspondente é mostrada no editor.

Considere uma solicitação muito simples, como "Encontrar o uso da CPU das minhas instâncias de VM do Compute Engine". Essa consulta envolve o tipo de recurso monitorado gce_instance e o tipo de métrica compute.googleapis.com/instance/cpu/usage_time.

A captura de tela a seguir mostra essa consulta no seletor de métricas baseado em formulário:

Selecionar uma métrica e um tipo de recurso no seletor de métricas.

Os tipos de métricas e recursos monitorados foram inseridos manualmente. Os valores de Alinhador e Período de alinhamento em Agregação avançada são padronizados.

Quando você clica em Editor de consultas, a consulta no seletor baseado em formulário é convertida em uma consulta MQL. A captura de tela a seguir mostra o resultado da conversão:

O Editor mostra o resultado da conversão dos valores do formulário em MQL.

A consulta MQL busca a série temporal para os tipos de recurso e métrica especificados e executa o alinhamento de taxa em intervalos de 1 minuto. A consulta convertida está no formato restrito.