Usar o editor de código para MQL

Nesta seção, descrevemos os recursos do editor de código para a linguagem de consulta do Monitoring (MQL, na sigla em inglês). O editor está disponível no console do Google Cloud e fornece sugestões, detecção de erros e outro suporte para criar 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 código

Para acessar o editor de código usando o Metrics Explorer, faça o seguinte:

1. No painel de navegação do console do Google Cloud, selecione Monitoramento e  Metrics Explorer:

   Acesse o Metrics explorer

2. Na barra de ferramentas do painel do criador de consultas, selecione o botão com o nome  MQL ou  PromQL.
3. Verifique se MQL está selecionado no botão de alternância Idioma. O botão de alternância está na mesma barra de ferramentas que permite formatar a consulta.

Você usa etapas semelhantes para acessar o editor de código ao criar um gráfico em um painel.

Como usar o editor de código

Para usar o editor de código, digite sua consulta na caixa de texto e clique em Executar consulta:

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.

Caso a consulta inclua erros que interferem nas sugestões de preenchimento automático, as mensagens de erro aparecerão à medida que você digitar. Caso contrário, as mensagens de erro serão exibidas quando você executar a consulta.

Dobramento de código

O editor fornece o dobramento de código, ou seja, a capacidade de recolher segmentos das consultas, para que você possa ocultá-los temporariamente.

O editor indica segmentos dobráveis da consulta com circunflexos ao lado dos números de linha, conforme mostrado nesta captura de tela:

Localizar e substituir

O editor tem o recurso de localizar e substituir. Para encontrar e, opcionalmente, substituir termos na consulta, pressione Control+F (ou Command+F no Mac). A captura de tela a seguir mostra o recurso:

Controles do Editor

O editor tem dois controles que determinam como ele interage com a consulta.

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

Para ativar a opção de execução automática, use o botã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 código não tenta avaliar consultas incompletas.

Há também uma barra fixa entre o editor de código e a região do gráfico. Use essa barra para alterar os tamanhos relativos das duas regiões.

Salvar gráficos

No Metrics Explorer

No editor de código no Metrics Explorer, você tem a opção de salvar seu 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, clique em Executar consulta antes de salvar o gráfico para fazer a consulta. Se você não executar sua consulta primeiro, o editor de código salvará a última consulta executada.

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, clique em Executar consulta antes de salvar o gráfico para fazer a consulta. Se você não executar sua consulta primeiro, o editor de código salvará a última consulta executada.

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.

Sair do editor de código

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

Visualizar consultas em formato restrito

Para visualizar uma consulta em formato restrito ao usar o editor de código, clique em Mais opções e selecione Ver formulário restrito.

Veja mais informações em Consultas de formulário restrito.

Intervalos de tempo, gráficos e o editor de código

Exceto para consultas MQL usadas em condições de políticas de alertas, as consultas MQL no editor de código precisam incluir um período. O intervalo de tempo especifica o subconjunto de dados que será retornado como parte da consulta. O intervalo de tempo pode ser expresso implicitamente usando o seletor de intervalo de tempo do gráfico ou explicitamente no texto da consulta MQL.

Por padrão, o seletor de intervalo de tempo é definido como uma hora.

Para mudar o período de um gráfico, use o seletor de intervalo de tempo. Por exemplo, se você quiser ver os dados da última semana, selecione Última semana no seletor de período. Você também pode especificar um horário de início e de término ou um horário de visualização.

Para informações sobre como criar políticas de alertas com o editor de código, consulte Como criar políticas de alertas do 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.

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 Gerenciar painéis personalizados.

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.

Nos gráficos do Monitoring, o período do gráfico é definido com base no valor do seletor de intervalo de tempo e no número máximo de pontos que ele pode exibir. Por exemplo, se você selecionar uma semana, o período do gráfico poderá ser de uma hora. Nos gráficos em painéis, para visualizar o período do gráfico, clique em Estatísticas da consulta.

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 a 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:

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:

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 o MQL e o editor de código para criar consultas que podem ser usadas em políticas de alertas.

Para criar uma política de alertas baseada em MQL usando o 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 para a política de alertas, use o editor de código em vez do seletor de métricas baseado em formulários.

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

Conversão de consulta

Use o seletor de métricas para gráficos ou no Metrics Explorer para criar uma consulta e convertê-la em MQL. A consulta MQL correspondente é mostrada no editor.

Para converter uma consulta criada pelo menu em MQL, faça o seguinte ao usar o Metrics Explorer:

1. Na barra de ferramentas do painel do criador de consultas, selecione o botão com o nome  MQL ou  PromQL.
2. Verifique se MQL está selecionado no botão de alternância Idioma. O botão de alternância está na mesma barra de ferramentas que permite formatar a consulta.

Para converter uma consulta baseada em formulário em MQL, ao visualizar um gráfico em um painel, clique em MQL.

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:

Os tipos de métricas e recursos monitorados foram inseridos manualmente. Todos os outros campos têm os valores padrão.

A captura de tela abaixo mostra o resultado da conversão da seleção baseada em formulário em uma consulta 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.

Observação: não é possível converter a representação MQL em configurações no seletor de métricas baseado em formulário. A MQL é compatível com consultas que não podem ser criadas com o seletor de métricas. Ao sair do editor de código, o texto da consulta será descartado se não for salvo.