Representar os resultados da consulta SQL em um gráfico

Este documento descreve como criar gráficos com os resultados da consulta da Análise de dados de registros, o que permite identificar padrões e tendências nos dados de registros. Com a Análise de dados de registros, você pode pesquisar e agregar registros para gerar insights úteis usando consultas em SQL.

Depois de executar uma consulta, os resultados podem ser mostrados em uma tabela ou convertidos em um gráfico. A consulta e a visualização podem ser salvas em um painel. Por exemplo, para saber quais tipos de gravidade seus registros estão gerando, crie um gráfico que mostre as contagens de registros gerados nas últimas 12 horas e detalhe os registros por severity. A captura de tela a seguir ilustra pontos de dados divididos em diferentes tipos de gravidade:

Antes de começar

Nesta seção, descrevemos as etapas que você precisa concluir antes de usar a análise de registros.

configurar buckets de registros

Confirme se os buckets de registros foram atualizados para usar a Análise de registros:

1. No console Google Cloud , acesse a página Armazenamento de registros:

   Acessar o armazenamento de registros

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

2. Para cada bucket de registros com uma visualização que você quer consultar, verifique se a coluna Análise de Dados de Registros disponível mostra Abrir. Se a opção Fazer upgrade aparecer, clique nela e conclua a caixa de diálogo.

Configurar permissões e papéis do IAM

Nesta seção, descrevemos os papéis ou as permissões do IAM necessários para usar a análise de registros:

• Para receber as permissões necessárias para usar a Análise de registros e consultar visualizações de registros, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

  • Para consultar os buckets de registros _Required e _Default: Visualizador de registros (roles/logging.viewer)
  • Para consultar todas as visualizações de registros em um projeto: Acessador de visualização de registros (roles/logging.viewAccessor)

  É possível restringir um principal a uma visualização de registros específica adicionando uma condição do IAM à concessão de papel de leitor de acesso à visualização de registros feita no nível do projeto ou adicionando uma vinculação do IAM ao arquivo de política da visualização de registros. Para mais informações, consulte Controlar o acesso a uma visualização de registro.

  Essas são as mesmas permissões necessárias para visualizar entradas de registro na página Análise de registros. Para informações sobre outros papéis necessários para consultar visualizações em buckets definidos pelo usuário ou para consultar a visualização _AllLogs do bucket de registros _Default, consulte Papéis do Cloud Logging.

• Para receber as permissões necessárias para consultar visualizações de análise, peça ao administrador para conceder a você o papel Usuário da análise de observabilidade (roles/observability.analyticsUser) do IAM no seu projeto.

• Para receber as permissões necessárias para criar gráficos, peça ao administrador para conceder a você o papel Editor do Monitoring (roles/monitoring.editor) do IAM no seu projeto.

Selecionar os dados para o gráfico

Para configurar quais dados mostrar 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 que a consulta for executada e um gráfico for gerado, você poderá personalizar a configuração mudando o tipo de gráfico e selecionando colunas para ver 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 dados de registros:

   Acesse Análise de registros

   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 ver 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, configure os campos da visualização selecionada e salve 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 escolher 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, 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 medida, ou o valor do eixo Y, é uma série de dados que é representada em relação ao eixo Y.

Mudar tipo de gráfico

Você pode escolher entre os seguintes tipos de gráficos, dependendo do tipo de linhas e colunas selecionadas como dimensão e métrica 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 métrica 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 rosca: Um gráfico de pizza mostra como as categorias em um conjunto de dados se relacionam com o conjunto 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 uma fatia indica o 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 de tabela 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 indicadores, que mostram apenas informações sobre o valor mais recente, os quadros de visão geral também podem incluir informações sobre valores anteriores.

  Os indicadores e quadros de visão geral só podem mostrar o resultado da consulta quando ele contém pelo menos uma linha, e essa linha tem uma coluna com um carimbo de data/hora e outra 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 com base no tempo como parte da consulta, faça o seguinte:

  • Configure sua 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.

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

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

  • 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 nenhuma.

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

  Se você quiser usar a Análise de registros para fazer a agregação com base 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 o intervalo de agregação para um intervalo 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 métrica

É possível escolher quais linhas e colunas serão representadas em um gráfico selecionando os campos de dimensão e métricas.

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 não houver um carimbo de data/hora na consulta, a primeira coluna de string será selecionada como a dimensão. Você também pode 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 com o 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. Você também pode manter a ordem de classificação "padrão", que classifica a dimensão com base nos valores da métrica correspondente em ordem decrescente.

  Por padrão, o intervalo dos 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 medidas 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 métrica, você também precisa escolher 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ê marcar a caixa de seleção Desativar intervalo para a dimensão, a opção de função de agregação none vai estar disponível. Se a dimensão for um valor de string, a caixa de seleção Desativar intervalo não vai aparecer. No entanto, definir as funções de agregação de uma medida como none também desativa o intervalo.

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, em vez de campos que possam conter um grande número de strings ou strings longas, como textPayload.

Por exemplo, confira a configuração de gráfico a seguir, em que o campo Dimensão está definido como tipo, o campo Métrica 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. Assim, é possível identificar quantos registros de cada tipo de gravidade foram gerados por um determinado recurso.

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

Salvar um gráfico em um painel personalizado

Depois que um gráfico é gerado com base na sua consulta, é possível salvá-lo em um painel personalizado. Os painéis personalizados permitem exibir e organizar informações úteis para você usando vários tipos de widgets. Com eles, também é possível 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, modifique a consulta. Para mais informações, consulte Aplicar uma variável a um widget.

Por exemplo, é possível criar um painel que forneça detalhes sobre o uso dos seus buckets do Cloud Storage:

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

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

   Acesse Análise de registros

   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 gráfico na guia Gráfico.

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.

Para conferir uma lista de painéis personalizados com gráficos gerados por consultas SQL, clique no botão Salvar gráfico e 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 da consulta.
• Edite a consulta usada para gerar um gráfico.
• Personalize a configuração do gráfico para visualizar dados diferentes.

Limitações

• Se o projeto Google Cloud 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 no nível do painel não se aplicam aos gráficos gerados com uma consulta SQL.

Amostras de consultas

Nesta seção, você encontra exemplos de consultas SQL para criar gráficos com os resultados da consulta. Para ter insights mais úteis dos seus registros, personalize a configuração do gráfico. Para usar as consultas de amostra, faça o seguinte:

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

   Acesse Análise de registros

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

2. Identifique o nome da tabela da visualização de registros que você quer consultar.

   Para identificar esse nome, acesse a lista Visualizações de registros, localize a visualização e selecione Consulta. O painel Consulta é preenchido com uma consulta padrão, que inclui o nome da tabela da visualização de registros consultada. O nome da tabela tem o formato project_ID.region.bucket_ID.view_ID.

   Para mais informações sobre como acessar a consulta padrão, consulte Consultar uma visualização de registros.

3. Substitua TABLE_NAME_OF_LOG_VIEW pelo nome da tabela da visualização de registros que você quer consultar e copie a consulta.

4. Cole a consulta no painel Consulta e clique em Executar consulta.

Criar gráficos de entradas de registro por local e gravidade

A consulta a seguir seleciona location e severity, com o local convertido como uma string:

SELECT
  CAST(JSON_VALUE(resource.labels.location) AS STRING) AS location,
  severity,
FROM
  `TABLE_NAME_OF_LOG_VIEW`
WHERE resource.labels.location IS NOT NULL

Um exemplo de gráfico e configuração de gráfico é mostrado abaixo:

Na captura de tela anterior, a configuração do gráfico tem os seguintes valores:

• Tipo de gráfico: gráfico de barras horizontal
• Dimensão: location, com um limite de 10
• Métrica: contar linhas
• Detalhamento: severity, com um limite de cinco

Criar gráficos com registros de auditoria de acesso a dados do BigQuery

A consulta a seguir filtra os registros de auditoria data_access do BigQuery e seleciona determinados campos, como user_email, ip, auth_permission e job_execution_project. Por exemplo, é possível criar um gráfico que mostre a frequência do uso da API BigQuery de cada principal ao longo do tempo.

SELECT
  timestamp,
  proto_payload.audit_log.authentication_info.principal_email as user_email,
  proto_payload.audit_log.request_metadata.caller_ip as ip,
  auth.permission as auth_permission,
  auth.granted as auth_granted,
  JSON_VALUE(data_access.resource.labels.project_id) AS job_execution_project,
  SPLIT(proto_payload.audit_log.resource_name, '/')[SAFE_OFFSET(1)] AS referenced_project,
  SPLIT(proto_payload.audit_log.resource_name, '/')[SAFE_OFFSET(3)] AS referenced_dataset,
  SPLIT(proto_payload.audit_log.resource_name, '/')[SAFE_OFFSET(5)] AS referenced_table
FROM `TABLE_NAME_OF_LOG_VIEW` as data_access,
  UNNEST(proto_payload.audit_log.authorization_info) AS auth
WHERE
  log_id="cloudaudit.googleapis.com/data_access"
  AND data_access.resource.type = 'bigquery_dataset'

Um exemplo de gráfico e configuração de gráfico é mostrado abaixo:

Na captura de tela anterior, a configuração do gráfico tem os seguintes valores:

• Tipo de gráfico: barras verticais
• Dimensão: user_email, com um limite de cinco
• Métrica: contar linhas
• Detalhamento: auth_permission, com um limite de cinco

Limitações

• 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, essa configuração 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 dados de registros.

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

A seguir

• Para uma visão geral da Análise de dados de registros, consulte Visão geral de consultas e análise de registros.

• Para exemplos de consultas, consulte Exemplos de consultas SQL.

• Para saber como analisar com registros de auditoria usando a Análise de dados de registros, consulte Consultas SQL para insights de segurança.