Usar o editor de código para MQL

Esta seção descreve os recursos do editor de código para Linguagem de consulta de monitoramento (MQL, na sigla em inglês). O editor está disponível console do Google Cloud e fornece sugestões, detecção de erros e outros suporte à 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 código

Para acessar o editor de código ao usar o Metrics Explorer: faça o seguinte:

1. No Console do Google Cloud, acesse a página do  Metrics Explorer:

   Acesse o Metrics explorer

   Se você usar a barra de pesquisa para encontrar essa página, selecione o resultado com o subtítulo Monitoring.

2. Na barra de ferramentas do painel do criador de consultas, selecione o botão  MQL ou  PromQL.
3. Verifique se MQL está selecionado na opção de ativar/desativar Idioma. A alternância de idiomas está na mesma barra de ferramentas que permite formatar sua consulta.

Siga etapas semelhantes para acessar o editor de código ao criar um gráfico em uma mais avançado.

Como usar o editor de código

Para usar o editor de código, digite sua consulta nele 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. Você pode configurar o editor de código para executar automaticamente sua consulta como que 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 Executar automaticamente. 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 vertical 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 do Metrics Explorer, é possível salvar os dados gráfico a um painel. Para salvar o gráfico, faça o seguinte:

1. Se você não tiver a opção de execução automática ativada, execute sua consulta Clique em Executar consulta antes de salvar o gráfico. Se você não executar sua consulta primeiro, o editor de código salva 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 do 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 você não tiver a opção de execução automática ativada, execute sua consulta Clique em Executar consulta antes de salvar o gráfico. Se você não executar sua consulta primeiro, o editor de código salva a última consulta executada.

3. Clique em Salvar. 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 condição, faça o seguinte: Clique em Voltar ao widget do seletor de consultas. Todo o texto de consulta no editor é descartado, mas você tem a opção de salvá-lo na área de transferência.

Ver consultas de forma estrita

Para visualizar uma consulta de forma rígida usando 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.

Períodos, 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 a ser retornado como parte do na consulta. O intervalo de tempo pode ser expresso implicitamente usando a função ou explicitamente no texto da consulta MQL.

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

Para mudar o intervalo de tempo de um gráfico, use o seletor de intervalo de tempo. Para Por exemplo, se você quiser visualizar os dados da última semana, selecione Última uma semana no seletor de intervalo de tempo. Também é possível especificar um horário de início e de término ou especificar um horário para visualização.

Para mais 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 mais 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 valor do seletor de intervalo de tempo do gráfico e o número máximo de pontos que um gráfico pode exibir. Por exemplo, se você selecionar uma semana, o período do gráfico poderá ser de uma hora. Para gráficos em painéis, para visualizar período do gráfico, clique em Estatísticas de 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, considere a seguinte consulta MQL:

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

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

Se o seletor de tempo do gráfico estiver definido como uma semana, o período do gráfico será uma hora, indicada 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ê mudar o período de alinhamento transmitido ao every de 1h a 1m na consulta anterior, ela produzirá uma gráfico que inclui as faixas 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

Você também pode usar o MQL e o editor de código 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 normais para criar a política, descritas em Como gerenciar políticas de alertas, mas quando você cria a condição para a política de alertas, use o editor de código em vez do modelo seletor de métricas.

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, ao usar o o Metrics Explorer, faça o seguinte:

1. Na barra de ferramentas do painel do criador de consultas, selecione o botão  MQL ou  PromQL.
2. Verifique se MQL está selecionado na opção de ativar/desativar Idioma. A alternância de idiomas está na mesma barra de ferramentas que permite formatar sua consulta.

Para converter uma consulta baseada em formulário em MQL, ao visualizar um gráfico em 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 têm seus valores padrão.

A captura de tela abaixo mostra o resultado da conversão do modelo seleção 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. Quando você sai do editor de código, o texto da consulta é descartado se você não salvá-lo.