Criar gráficos com os resultados da consulta SQL

É possível criar gráficos com os resultados de consultas SQL na Análise de observabilidade para identificar padrões e tendências de desempenho nos dados de registro e de rastreamento e salvar essas visualizações em painéis personalizados.

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

Antes de começar

Faça login na sua Google Cloud conta. 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.

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.

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.

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 ter as permissões necessárias para carregar a página Análise de observabilidade , escrever e executar consultas nos dados de registro e de rastreamento e salvar gráficos em painéis personalizados, peça ao administrador para conceder a você os seguintes papéis do IAM:

   • Editor do Monitoring (roles/monitoring.editor) no seu projeto
   • Acessador de visualização de observabilidade (roles/observability.viewAccessor) nas visualizações de observabilidade que você quer consultar. Esse papel oferece suporte às 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 de papel, o principal poderá acessar todas as visualizações de observabilidade.
   • Leitor de registros (roles/logging.viewer) no seu projeto
   • Acessador de visualização de registros (roles/logging.viewAccessor) no projeto que armazena as visualizações de registro que você quer consultar.

   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 com papéis personalizados ou outros papéis predefinidos.

Selecionar os dados para 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, você pode personalizá-lo mudando o tipo de gráfico e selecionando as colunas para mostrar dados diferentes.

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

1. No Google Cloud console, 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 conferir os resultados da consulta:

   • Tabela: somente formato tabular.

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

   • Ambos: formato de gráfico e tabular.

     Depois de selecionar como conferir os resultados da consulta, você pode configurar todos 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 quais linhas e colunas 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 de gráfico, selecionando a dimensão e a medida para representar e aplicando um detalhamento. A dimensão é usada para agrupar ou categorizar linhas e é o valor do eixo X. A medida, ou o valor do eixo Y, é uma série de dados que é representada no eixo Y.

Mudar tipo de gráfico

É possível selecionar entre os seguintes tipos de gráficos, dependendo do tipo de linhas e colunas selecionadas 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 representam dados em dois eixos. Se o gráfico usar uma categoria ou string como dimensão, você poderá definir a configuração do gráfico de barras como horizontal ou vertical, em que os eixos de dimensão e medida são trocados.

• Gráfico de linhas: os gráficos de linhas podem ser usados para mostrar mudanças de 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 no 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 ao conjunto de dados inteiro, usando um círculo para representar o conjunto de dados inteiro e setores no círculo para representar as categorias no conjunto de dados. O tamanho de um setor 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 mostrar 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 em como esse valor é comparado a 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. É possível usar a cláusula LIMIT ou o seletor de período para limitar o número de linhas no resultado da consulta.

    Dados de registros

    Por exemplo, a consulta a seguir consulta uma visualização de registro e agrega dados por hora, aplica um limite e classifica os resultados:

    SELECT TIMESTAMP_TRUNC(timestamp, HOUR) AS hour, severity, COUNT(*) AS count
    FROM `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID`
    WHERE severity IS NOT NULL AND severity = "DEFAULT"
    GROUP BY hour,severity
    ORDER BY hour DESC
    LIMIT 10

    A seguir, descrevemos o significado dos campos na expressão anterior:

    • PROJECT_ID: o identificador do projeto.
    • LOCATION: o local da visualização de registro ou da visualização de análise.
    • BUCKET_ID: o nome ou ID do bucket de registros.
    • LOG_VIEW_ID: o identificador da visualização de registro, que é limitado a 100 caracteres e pode incluir apenas letras, dígitos, sublinhados e hifens.

    Rastrear dados

    Por exemplo, a consulta a seguir consulta os dados de rastreamento e agrega os dados 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

    A seguir, descrevemos 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 a consulta já especifica o intervalo de agregação. No exemplo, esse intervalo é de uma hora.

  • Defina a medida como a coluna numérica e defina a função como nenhuma.

    Observação: se a consulta realizar a agregação baseada em tempo, certifique-se de que você siga as orientações anteriores. Outras configurações resultam na execução de operações de agregação pela consulta e pela Análise de observabilidade, o que resulta na exibição de valores inesperados pelo medidor ou pela visão geral.

  Se você quiser que a Análise de observabilidade realize 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, defina 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 medida

É possível escolher quais linhas e colunas serão representadas selecionando os campos de dimensão e medida.

**Observação**: se os resultados da consulta contiverem 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 nenhum carimbo de data/hora estiver presente 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 `default`, 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 também é possível 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. A desativação do intervalo define a função de agregação das medidas como none. Somente medidas numéricas são permitidas quando o intervalo de dimensão está desativado.

  Observação: apenas a coluna TIMESTAMP pode ser usada como uma dimensão de carimbo de data/hora. Para usar DATE e DATETIME, é necessário usar a CAST() função 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, também é necessário selecionar a função de agregação a ser realizada 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ê selecionar a caixa de seleção Desativar intervalo para a dimensão, a opção de função de agregação none estará 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 medida como none também desativa o intervalo.

Adicionar um detalhamento

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

Para dividir uma única série de dados em várias séries de dados 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.

Dados de registros

Por exemplo, consulte a configuração do gráfico a seguir, em que o campo Dimensão está definido como tipo, o campo Medida está definido como Contar linhas e o campo Detalhamento está definido como gravidade:

Na captura de tela anterior, você vê uma série de dados empilhados, em que o tipo de recurso k8s_container é dividido em diferentes tipos de severity. Isso permite identificar quantos registros de cada tipo de gravidade foram gerados por um determinado recurso.

Rastrear dados

Por exemplo, o gráfico a seguir mostra o número de períodos criados por cada serviço, juntamente com os dados detalhados pelo nome do período:

Gerar e mostrar exemplares de rastreamento

Visualizar

Esse produto ou recurso está sujeito aos "Termos de ofertas 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 rastreamento para mostrar exemplares gerados dinamicamente. Um exemplar é uma solicitação ou período de amostra representativo associado a uma medição de métrica. Cada exemplar é vinculado a um rastreamento. Ao selecionar um exemplar, um menu flutuante que mostra o rastreamento é aberto.

Requisitos de configuração

Para mostrar exemplares, o seguinte precisa ser verdadeiro:

• A consulta do gráfico é escrita em SQL e o destino da consulta são dados de rastreamento.
• 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 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 de seleção de amostragem inteligente para manter os exemplares legíveis e relevantes:

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

Limitações

• Se um gráfico mostrar várias série temporal, o sistema vai reduzir o número de exemplares mostrados.
• Os exemplares podem não ser distribuídos uniformemente 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 na consulta, é possível salvá-lo em um painel personalizado. Os painéis personalizados permitem mostrar e organizar informações úteis usando uma variedade de tipos de widgets. Esses painéis também permitem definir variáveis, que são filtros de nível de 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 mostra 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 dos quais é a hierarquia dos recursos usados pela consulta. 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 Google Cloud console, 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 salvar o gráfico.

4. Opcional: para conferir o painel personalizado, no pop-up, clique Conferir painel.

Para conferir 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:

• Mudar os dados consultados.
• Editar a consulta usada para gerar um gráfico.
• Personalizar a configuração do gráfico para visualizar dados diferentes.

Limitações

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

• Os filtros de nível de painel não se aplicam a gráficos gerados 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 do gráfico personalizado não será salva.

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

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

A seguir

• Salvar e compartilhar consultas
• Amostras de consultas SQL