Consultar e analisar rastreamentos

Neste documento, descrevemos como consultar e analisar os dados de trace usando a Análise de observabilidade, que oferece uma interface de consulta baseada em SQL. O SQL permite realizar análises agregadas, o que pode ajudar a gerar insights e identificar tendências. Para conferir os resultados da consulta, use tabelas ou gráficos. Você também pode salvar essas tabelas e gráficos nos seus painéis personalizados.

Se você quiser conferir ou explorar traces ou períodos individuais ou visualizar atributos anexados a períodos, use a página Trace Explorer. Para mais informações sobre essa página, consulte Encontrar e explorar traces.

Para analisar os dados de trace, consulte a visualização padrão, chamada _AllSpans. Essa visualização inclui todos os dados de trace armazenados pelo seu projeto. O bucket de observabilidade correspondente é chamado de _Trace. Para mais informações sobre como os seus dados de trace são armazenados, consulte Visão geral do armazenamento de traces.

Sobre conjuntos de dados vinculados do BigQuery

Não é necessário um conjunto de dados vinculado do BigQuery para consultar os dados de trace ou os dados de trace e registro. Para esses cenários, você pode usar a página Análise de observabilidade. Para mais informações sobre como consultar dados de registro, consulte Consultar e analisar registros com a Análise de observabilidade.

Você precisa de um conjunto de dados vinculado do BigQuery quando quiser fazer o seguinte:

Este documento não descreve como criar um conjunto de dados vinculado do BigQuery ou como configurar a Análise de observabilidade para executar consultas em slots reservados. Para mais informações sobre esses tópicos, consulte Criar um conjunto de dados vinculado do BigQuery.

Antes de começar

  1. Faça login na sua Google Cloud conta do. Se você começou a usar o Google Cloud, 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.

  2. 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.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. 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

  5. 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.

    Go to project selector

  6. Verify that billing is enabled for your Google Cloud project.

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

    8.

  8. Para conseguir as permissões que você precisa para carregar a página Análise de observabilidade, escrever, executar e salvar consultas particulares nos dados de trace, 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 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.
    • Usuário da Análise de observabilidade (roles/observability.analyticsUser) no seu projeto. Esse papel contém as permissões necessárias para salvar e executar consultas particulares e executar consultas compartilhadas.

    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.

Mostrar o esquema

O esquema define como os dados são armazenados, incluindo os campos e os tipos de dados. Essas informações são importantes porque o esquema determina os campos que você consulta e se é necessário transmitir campos para diferentes tipos de dados. Por exemplo, para escrever uma consulta que calcula a latência média de solicitações HTTP, é necessário saber como acessar o campo de latência e se ele está armazenado como um número inteiro, como 100, ou como uma string, como "100". Se os dados de latência forem armazenados como uma string, a consulta precisará transmitir o valor para um valor numérico antes de calcular uma média.

Para identificar o esquema, 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. No menu Visualizações, acesse a seção Traces, e selecione _Trace.Spans._AllSpans.

    O painel Esquema é atualizado. A Análise de observabilidade infere automaticamente os campos de uma coluna quando o tipo de dados é JSON. Para conferir a frequência com que esses campos inferidos aparecem nos seus dados, clique Opções e selecione Visualizar informações e descrição.

    Para saber mais sobre o esquema, consulte Esquema de armazenamento de dados de trace.

    Se você não encontrar uma visualização chamada _Trace.Spans._AllSpans, seu Google Cloud projeto não contém um bucket de observabilidade chamado _Trace. Para mais informações sobre como resolver essa falha, consulte A inicialização do armazenamento de traces falha.

Consultar dados de trace

Esta seção descreve as abordagens que você pode usar para consultar os dados de trace:

  • Carregue uma consulta definida pelo sistema, edite-a e execute-a.
  • Insira e execute uma consulta personalizada. Por exemplo, você pode colar uma consulta que tem ou escrever uma. As consultas personalizadas podem incluir combinações, consultas aninhadas e outras instruções SQL complexas. Para exemplos, consulte Amostras de consultas SQL.
  • Crie uma consulta fazendo seleções de menu e execute-a. A Análise de observabilidade converte suas seleções em uma consulta SQL, que você pode visualizar e editar.

Carregar, editar e executar a consulta definida pelo sistema

  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 menu Visualizações, acesse a seção Traces, e selecione _Trace.Spans._AllSpans.

    Se você não encontrar uma visualização chamada _Trace.Spans._AllSpans, seu Google Cloud projeto não contém um bucket de observabilidade chamado _Trace. Para mais informações sobre como resolver essa falha, consulte A inicialização do armazenamento de traces falha.

  3. Escolha uma destas opções:

    • Para carregar uma consulta definida pelo sistema que depende do Criador de consultas, que permite definir a consulta com seleções de menu, verifique se o painel Consulta mostra o Criador de consultas. Se um editor de SQL for mostrado, então clique em  Criador.

    • Para carregar uma consulta definida pelo sistema que extrai valores JSON, verifique se o painel Consulta mostra o editor de SQL. Se esse painel mostrar Criador de consultas, clique em  SQL.

  4. No painel Esquema, selecione Consulta e clique em Substituir.

    O painel Consulta mostra uma consulta definida pelo sistema. Se você selecionou o Criador de consultas modo, mas quer visualizar a consulta SQL, clique em  SQL.

  5. Opcional: modifique a consulta.

  6. Para executar a consulta, acesse a barra de ferramentas e selecione Executar consulta.

    A Análise de observabilidade apresenta os resultados da consulta em uma tabela. No entanto, você pode criar um gráfico e também salvar a tabela ou o gráfico em um painel personalizado. Para mais informações, consulte Representar os resultados da consulta SQL em um gráfico.

    Se a barra de ferramentas mostrar Executar no BigQuery, será necessário mudar a Análise de observabilidade para usar o mecanismo de consulta padrão. Para fazer essa mudança, na barra de ferramentas do painel Consulta, clique em Configurações e selecione Análise (padrão).

Inserir e executar uma consulta personalizada

Para inserir uma consulta SQL, 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. No painel Consulta, clique em  SQL.

    • Para especificar um período, recomendamos que você use o seletor de período. Se você adicionar uma cláusula WHERE que especifica o campo timestamp, esse valor vai substituir a configuração no seletor de período, e esse seletor será desativado.

    • Para exemplos, consulte Amostras de consultas SQL.

    • O editor de SQL mostra o nome totalmente qualificado da visualização _Trace.Spans._AllSpans, que tem o seguinte formato:

      FROM `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`

      Os campos na expressão anterior têm o seguinte significado:

      Se o painel de consulta mostrar uma mensagem de erro que faz referência à instrução FROM, a visualização não poderá ser encontrada. Para mais informações sobre como resolver essa falha, consulte Mensagem de erro informando que uma visualização não existe.

  3. Para executar a consulta, acesse a barra de ferramentas e selecione Executar consulta.

    A Análise de observabilidade apresenta os resultados da consulta em uma tabela. No entanto, você pode criar um gráfico e também salvar a tabela ou o gráfico em um