Criar gráficos com os resultados da consulta SQL

A Análise de Observabilidade permite visualizar os resultados de consultas SQL como gráficos para identificar padrões e tendências nos dados de trace. Depois de executar uma consulta para pesquisar e agregar dados de trace, é possível ver os resultados em uma tabela, convertê-los em um gráfico e salvar a visualização em um painel.

Por exemplo, o gráfico a seguir mostra o status informado por períodos ao longo do tempo, agrupados por service_name:

Antes de começar

Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloudagora, crie uma conta para avaliar o desempenho dos nossos produtos em situações reais. Clientes novos também recebem US $300 em créditos para executar, testar e implantar cargas de trabalho sem custos financeiros.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Observability API, if it is not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the API

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Observability API, if it is not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the API

1. Para receber as permissões necessárias para carregar a página Análise de Observabilidade, gravar e executar consultas nos dados de trace e salvar gráficos em painéis personalizados, peça ao administrador para conceder a você os seguintes papéis do IAM:

   • Acessador de visualização de observabilidade (roles/observability.viewAccessor) nas visualizações de observabilidade que você quer consultar. Esse papel é compatível com as condições do IAM, que permitem restringir a concessão a uma visualização específica. Se você não anexar uma condição à concessão do papel, o principal poderá acessar todas as visualizações de observabilidade.
   • Editor do Monitoring (roles/monitoring.editor) no projeto.

   Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

   Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Selecione os dados para criar o gráfico

Para configurar quais dados serão exibidos em um gráfico, crie uma consulta usando SQL. Quando você seleciona a guia Gráfico, um gráfico mostra os resultados da consulta. Depois de executar a consulta e gerar um gráfico, é possível personalizá-lo mudando o tipo e selecionando colunas para mostrar dados diferentes.

Para ver os resultados da consulta como um gráfico, execute uma consulta fazendo o seguinte:

1. No console Google Cloud , acesse a página Análise de observabilidade:

   Acessar a análise de observabilidade

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

2. No painel Consulta, insira uma consulta e clique em Executar.

3. Depois que a consulta for concluída, na guia Resultados, selecione como você quer visualizar os resultados da consulta:

   • Tabela: somente formato tabular.

   • Gráfico: somente formato de gráfico.

   • Ambos: formato de gráfico e tabela.

     Depois de selecionar como visualizar os resultados da consulta, é possível configurar os campos para a visualização selecionada e salvar a consulta e os resultados em um painel personalizado. O formato salvo é tabular quando você seleciona a opção Tabela. Caso contrário, o formato é um gráfico.

     Para gráficos, as opções de visualização permitem selecionar o tipo de gráfico e as linhas e colunas que serão representadas. Para mais informações sobre a configuração do gráfico, consulte Personalizar a configuração do gráfico.

Personalizar a configuração do gráfico

É possível personalizar a configuração do gráfico mudando o tipo, selecionando a dimensão e a medida a serem representadas e aplicando um detalhamento. A Dimensão é usada para agrupar ou categorizar linhas e é o valor do eixo X. A Medição, ou o valor do eixo Y, é uma série de dados que é plotada em relação ao eixo Y.

Mudar tipo de gráfico

É possível selecionar entre os seguintes tipos de gráfico, dependendo do tipo de linhas e colunas que você selecionou como dimensão e medida e de como você quer que esses dados sejam visualizados.

• Gráfico de barras (padrão): os gráficos de barras mostram dados em dois eixos. Se o gráfico usar uma categoria ou string como dimensão, será possível definir a configuração de um gráfico de barras como horizontal ou vertical, em que os eixos de dimensão e medida são trocados.

• Gráfico de linhas: pode ser usado para mostrar mudanças nos dados ao longo do tempo. Quando você usa um gráfico de linhas, cada série temporal é mostrada por uma linha diferente que corresponde às medidas selecionadas.

  Se o eixo X for baseado em tempo, cada ponto de dados será colocado no início de um intervalo de tempo. Cada ponto de dados é conectado por interpolação linear.

• Gráfico de área empilhada: um gráfico de área é baseado em um gráfico de linhas, e a área abaixo de cada linha é sombreada. Nos gráficos de área, as séries de dados são empilhadas. Por exemplo, se você tiver duas séries idênticas, elas vão se sobrepor em um gráfico de linhas, mas a área sombreada será empilhada em um gráfico de área.

• Gráfico de pizza ou de rosca: um gráfico de pizza mostra como as categorias em um conjunto de dados se relacionam com o conjunto de dados inteiro, usando um círculo para representar o conjunto de dados inteiro e fatias no círculo para representar as categorias no conjunto de dados. O tamanho de uma fatia indica quanto, geralmente como uma porcentagem, a categoria contribui para o todo.

• Tabela: uma tabela mostra uma linha para cada linha no resultado da consulta. As colunas na tabela são definidas pela cláusula SELECT. Se você planeja exibir dados em formato tabular em um painel, use uma cláusula LIMIT para restringir o número de linhas no resultado a menos de algumas centenas.

• Medidor ou visão geral: os medidores e as visões gerais fornecem o valor mais recente, além de uma indicação verde, amarela ou vermelha com base na comparação desse valor com um conjunto de limites. Ao contrário dos medidores, que mostram apenas informações sobre o valor mais recente, as visões gerais também podem incluir informações sobre valores anteriores.

  Os medidores e as visões gerais só podem mostrar o resultado da consulta quando ele contém pelo menos uma linha, e essa linha contém uma coluna com um carimbo de data/hora e uma coluna com dados numéricos. O resultado da consulta pode conter várias linhas e mais de duas colunas.

  Se você quiser realizar a agregação baseada em tempo como parte da consulta, faça o seguinte:

  • Configure a consulta para agregar dados em um intervalo de tempo, ordenar os resultados por carimbos de data/hora decrescentes e limitar o número de linhas nos resultados. Use a cláusula LIMIT ou o seletor de período para limitar o número de linhas no resultado da consulta.

    Por exemplo, o comando a seguir consulta os dados de trace e os agrega em intervalos de uma hora, aplica um limite e classifica os resultados:

    SELECT TIMESTAMP_TRUNC(start_time, HOUR) AS hour,
       COALESCE(
          JSON_VALUE(resource.attributes, '$."service.name"'),
          JSON_VALUE(attributes, '$."service.name"'),
          JSON_VALUE(attributes, '$."g.co/gae/app/module"')) AS service_name,
       status.code AS status,
       COUNT(*) AS count
    FROM `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`
    GROUP BY hour, service_name, status
    ORDER BY hour DESC
    LIMIT 1000

    Veja a seguir o significado dos campos na expressão anterior:

    • PROJECT_ID: o identificador do projeto.
    • LOCATION: o local do bucket de observabilidade.

    A consulta anterior foi usada para gerar a figura mostrada no início deste documento. Essa figura também mostra a configuração do gráfico.

  • Defina a Dimensão para corresponder à coluna que informa a unidade de tempo. Por exemplo, se a consulta agregar dados por uma hora e criar uma coluna chamada hour, defina o menu Dimensão como hour.

  • Selecione Desativar intervalo porque sua consulta já especifica o intervalo de agregação. No exemplo, esse intervalo é de uma hora.

  • Defina a Medida como a coluna numérica e a função como none.

    Observação :se a consulta realizar agregação com base no tempo, siga as orientações anteriores. Outras configurações fazem com que a consulta e a Análise de Observabilidade realizem operações de agregação, o que resulta na exibição de valores inesperados no medidor ou na visão geral.

  Se você quiser usar a Análise de Observabilidade para realizar a agregação baseada em tempo, faça o seguinte:

  • Configure o seletor de período, que afeta o número de linhas no resultado da consulta.
  • Defina a Dimensão para corresponder à coluna que informa a unidade de tempo. Por exemplo, você pode definir esse menu como timestamp.
  • Defina o menu Intervalo como um intervalo de agregação específico. Por exemplo, defina o valor desse campo como 1 hour. Não selecione Intervalo automático.
  • Defina a Medida como a coluna numérica e selecione uma função, como soma.

Mudar dimensão e medição

Para escolher quais linhas e colunas serão representadas no gráfico, selecione os campos de dimensão e medida.

Observação: se os resultados da consulta tiverem uma coluna com strings longas, como mensagens de erro, e você selecionar essa coluna como dimensão ou detalhamento, o gráfico poderá ter erros ou valores inesperados.

• Dimensão

  A dimensão precisa ser uma coluna de carimbo de data/hora, numérica ou de string. Por padrão, a dimensão é definida como a primeira coluna baseada em carimbo de data/hora no esquema. Se não houver um carimbo de data/hora na consulta, a primeira coluna de string será selecionada como a dimensão. Também é possível personalizar a dimensão no painel Exibição do gráfico. Quando uma coluna de carimbo de data/hora é selecionada como a dimensão, o gráfico mostra como os dados mudam ao longo do tempo. Quando uma coluna de string é selecionada como a dimensão de um gráfico de barras, é possível classificar os dados em ordem crescente ou decrescente, o que classifica a dimensão por ordem lexical. Também é possível manter a ordem de classificação "padrão", que classifica a dimensão com base nos valores da medida correspondente em ordem decrescente.

  Por padrão, o intervalo para carimbos de data/hora é definido automaticamente, mas você também pode selecionar um intervalo personalizado. Os intervalos automáticos mudam os valores com base no seletor de período para manter grupos de tamanho semelhante.

  Também é possível desativar o intervalo, o que permite especificar suas próprias agregações e períodos na consulta para uma análise mais complexa. Desativar o intervalo define a função de agregação das medições como none. Somente medidas numéricas são permitidas quando o intervalo de dimensão está desativado.

  Observação: somente a coluna TIMESTAMP pode ser usada como uma dimensão de carimbo de data/hora. Para usar DATE e DATETIME, use a função CAST() para converter os tipos de dados em TIMESTAMP.

• Medida

  É possível selecionar várias medidas no painel Exibição do gráfico. Ao selecionar uma medida, você também precisa selecionar a função de agregação a ser executada nos valores agrupados, como count, sum, average e percentile-99. Por exemplo, count-distinct retorna o número de valores exclusivos em uma determinada coluna.

  Se você marcar a caixa de seleção Desativar intervalo para a dimensão, a opção de função de agregação none vai ficar disponível. Se a dimensão for um valor de string, a caixa de seleção Desativar intervalo não será mostrada. No entanto, definir as funções de agregação de uma medição como none também desativa o intervalo.

Adicionar um detalhamento

Observação: se o gráfico tiver mais de uma medição, não será possível adicionar um detalhamento.

Para dividir uma única série de dados em várias com base em outra coluna, adicione um detalhamento.

Ao selecionar um detalhamento, escolha colunas que contenham um pequeno número de rótulos curtos e significativos, como region_name. Não selecione campos que possam conter um grande número de strings ou strings longas, como textPayload.

Por exemplo, o gráfico a seguir mostra o número de períodos criados por cada serviço, além dos dados divididos pelo nome do período:

Gerar e exibir exemplares de trace

Visualizar

Este produto ou recurso está sujeito aos Termos das Soluções Pré-GA na seção Termos Gerais de Serviço dos Termos Específicos de Serviço. Os produtos e recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

É possível configurar os gráficos baseados em SQL que analisam dados de trace para exibir exemplos gerados dinamicamente. Um exemplar é uma solicitação de amostra representativa ou um período associado a uma medição de métrica. Cada exemplar é vinculado a um trace. Ao selecionar um exemplar, um submenu é aberto para mostrar o trace.

Requisitos de configuração

Para mostrar exemplares, as seguintes condições precisam ser verdadeiras:

• A consulta do gráfico é escrita em SQL, e o destino da consulta são dados de trace.
• O gráfico usa a visualização de gráfico de linhas ou de barras.
• O trace_id e o start_time fazem parte dos resultados da consulta.

Para ocultar os exemplares, acesse a barra de ferramentas do gráfico e selecione flare Ocultar exemplares.

Como o sistema gera exemplares

O sistema aplica uma estratégia inteligente de seleção de amostragem para manter os exemplares legíveis e relevantes:

• Para medidas estatísticas, como AVG e PERCENTILE:o sistema compara os valores brutos de período com a linha de tendência interpolada do gráfico e agrupa as amostras em pools de desvio. Uma amostra proporcional de cada pool é plotada e espaçada de maneira uniforme ao longo do tempo.
• Para contagens de frequência, como COUNT:o sistema posiciona os exemplares ao longo do limite superior da janela do gráfico e os espaça uniformemente entre as análises detalhadas de tempo e série de dados.

Limitações

• Se um gráfico exibir várias série temporal, o sistema reduzirá o número de exemplares mostrados.
• Os exemplares podem não estar distribuídos de maneira uniforme no intervalo de tempo do gráfico.
• A escala do eixo Y pode distorcer a exibição visual. A distorção é mais provável quando um gráfico usa um eixo Y logarítmico ou quando série temporal contêm outliers.
• Não é possível configurar como o sistema gera exemplares.

Salvar um gráfico em um painel personalizado

Depois que um gráfico é gerado com base na consulta, é possível salvá-lo em um painel personalizado. Com os painéis personalizados, é possível exibir e organizar informações úteis usando vários tipos de widgets. Esses painéis também permitem definir variáveis, que são filtros no nível do painel que se aplicam apenas a widgets específicos. Para aplicar uma variável a um widget, é necessário modificar a consulta. Para mais informações, consulte Aplicar uma variável a um widget.

Um painel exibe uma mensagem de aviso para um widget que contém uma consulta SQL quando a consulta é executada no mecanismo do BigQuery e os recursos consultados não estão no mesmo limite de propriedade. Os limites de propriedade são determinados por vários fatores, um deles é a hierarquia dos recursos que a consulta usa. Para evitar esses avisos, configure um perímetro de serviço.

Para salvar o gráfico em um painel, faça o seguinte:

1. No console Google Cloud , acesse a página Análise de observabilidade:

   Acessar a análise de observabilidade

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

2. Execute uma consulta para gerar um gráfico e clique em Salvar no painel.

3. Na caixa de diálogo Salvar no painel, insira um título para o gráfico e selecione o painel em que você quer salvá-lo.

4. Opcional: para acessar o painel personalizado, clique em Ver painel na mensagem de aviso.

Para ver uma lista de painéis personalizados que contêm gráficos gerados por consultas SQL, acesse o botão Salvar no painel e clique em Menu.

Editar um gráfico salvo em um painel personalizado

É possível modificar um gráfico depois que ele é salvo em um painel. Para mais informações, consulte Modificar a configuração de um widget. Na caixa de diálogo Configurar widget, é possível fazer o seguinte:

• Mude os dados que você consulta.
• Editar a consulta usada para gerar um gráfico.
• Personalize a configuração do gráfico para visualizar dados diferentes.

Limitações

• Se o projeto do Google Cloud estiver em uma pasta que usa o Assured Workloads, os gráficos gerados não poderão ser exibidos em um painel personalizado.

• Os filtros no nível do painel não se aplicam a gráficos gerados com base em uma consulta SQL.

• As colunas selecionadas precisam ter pelo menos uma linha com um valor não nulo.

• Se você salvar uma consulta e personalizar a configuração do gráfico, a configuração personalizada do gráfico não será salva.

• Se a consulta já tiver agregações, o gráfico gerado poderá ser diferente devido à agregação adicional aplicada automaticamente pela Análise de Observabilidade.

• Os caminhos JSON precisam ser convertidos em strings ou números para serem representados em gráficos.

A seguir

• Salvar e compartilhar uma consulta SQL
• Exemplos de consultas SQL
• Consultar um conjunto de dados vinculado do BigQuery no BigQuery