Este documento descreve como criar e gerenciar um escopo de trace, que permite que a página Trace Explorer encontre os intervalos de trace que você quer visualizar ou analisar. Se você só quer visualizar e analisar os intervalos que originam no seu projeto do Google Cloud, não é necessário configurar nenhum escopo de rastreamento. No entanto, se os dados de rastreamento forem armazenados em vários projetos, como pode ocorrer quando você usa uma arquitetura de microsserviços, será necessário realizar algumas atividades de configuração para visualizar todos os intervalos em um único projeto do Google Cloud.
Este documento não descreve como visualizar seus traços e intervalos. Para informações sobre esse tópico, consulte Encontrar e analisar traces.
Sobre os escopos de trace
Os escopos de trace são recursos persistentes no nível do projeto que listam um conjunto de projetos do Google Cloud. É possível configurar a página Trace Explorer para pesquisar por escopo de trace, o que significa que a página pesquisa os projetos listados no escopo selecionado. Seus papéis Identity and Access Management (IAM) nos projetos pesquisados e a configuração do período determinam quais dados são buscados do armazenamento e exibidos.
Quando você cria um projeto do Google Cloud, um escopo de rastreamento chamado _Default é criado. Esse escopo inclui apenas o projeto do Google Cloud. Não é possível adicionar
projetos a esse escopo nem excluí-lo.
Você pode criar, modificar e excluir os escopos de rastreamento que criar. Você quer criar um escopo de rastreamento quando tiver um serviço que grava dados de vários projetos do Google Cloud.
A menos que você abra a página Trace Explorer com um URL que inclua um
escopo de trace ou um ID de trace e de intervalo,
a página Trace Explorer pesquisa os
projetos do Google Cloud listados no escopo de trace padrão para dados de trace.
Quando você cria seu projeto, o escopo de rastreamento chamado _Default é
definido como o escopo de rastreamento padrão. No entanto, é possível selecionar um escopo de rastreamento diferente para usar como o padrão.
Antes de começar
Para receber as permissões necessárias para criar e visualizar os escopos de rastreamento e definir o escopo de rastreamento padrão, peça ao administrador para conceder a você os seguintes papéis do IAM:
-
Para criar e conferir os escopos de trace e receber o escopo de trace padrão:
Usuário do Cloud Trace (
roles/cloudtrace.user) no seu projeto -
Para definir o escopo de rastreamento padrão:
Editor de Observabilidade (
roles/observability.editor) no seu projeto
Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.
Esses papéis predefinidos contêm as permissões necessárias para criar e visualizar os escopos de rastreamento e definir o escopo de rastreamento padrão. Para conferir as permissões exatas necessárias, expanda a seção Permissões necessárias:
Permissões necessárias
As seguintes permissões são necessárias para criar e visualizar escopos de rastreamento e definir o escopo de rastreamento padrão:
-
Para criar e gerenciar escopos de rastreamento:
cloudtrace.traceScopes.[create, delete, get, list, update] -
Para definir o escopo de rastreamento padrão:
observability.scopes.[get, update]
Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.
Listar escopos de trace
Para listar os escopos de rastreamento, faça o seguinte:
-
No console do Google Cloud, abra a página settings Configurações:
Se você usar a barra de pesquisa para encontrar essa página, selecione o resultado com o subtítulo Monitoramento.
Selecione a guia Trace Scopes.
A tabela lista seus escopos de rastreamento. Quando você seleciona um projeto do Google Cloud, uma entrada é mostrada com um ícone "Padrão",
,
que indica que é o escopo de rastreamento padrão.
A página Trace Explorer pesquisa os projetos listados no escopo de trace padrão para dados de trace quando a página é aberta.
Criar um escopo do trace
Os intervalos mostrados pela página Trace Explorer dependem dos projetos pesquisados, das suas funções do IAM nesses projetos, da configuração do período e dos filtros aplicados.
É possível criar 100 escopos de rastreamento por projeto. Um escopo de trace pode incluir um total de 20 projetos.
Para criar um escopo de trace, faça o seguinte:
-
No console do Google Cloud, abra a página settings Configurações:
Se você usar a barra de pesquisa para encontrar essa página, selecione o resultado com o subtítulo Monitoramento.
- Selecione a guia Trace Scopes e clique em Create trace scope.
Clique em Adicionar projetos e preencha a caixa de diálogo.
Quando você adiciona um projeto, os spans armazenados nele são incluídos no escopo do trace. Se você não souber quais projetos incluir em um escopo, use a página Trace Explorer legada para identificá-los. Para mais informações, consulte a seção Migrar para escopos de rastreamento deste documento.
Na seção Nomear escopo de rastreamento, insira o nome e a descrição que você quer que apareçam na guia Escopos de rastreamento.
O nome de um escopo de trace não pode ser modificado e precisa ser exclusivo no projeto.
Clique em Criar escopo de rastreamento.
Migrar para escopos de trace
A página Trace Explorer exige que você especifique os projetos do Google Cloud para pesquisar dados de trace, o que é uma mudança no comportamento em relação à página Trace Explorer legada. A página Trace Explorer herdada pesquisa todos os projetos em uma organização. Devido a essas diferenças, a página Trace Explorer pode não mostrar intervalos que as páginas Trace Explorer legados mostram.
Você pode usar a seção do painel Detalhes do trace da página legada Trace Explorer para compilar uma lista de projetos do Google Cloud que armazenam seus dados de trace:
Acesse a página Explorador de traces legada:
Selecione um trace.
Tente o seguinte:
- Visualizar um trace inserindo o ID dele no campo ID do trace.
- Adicionar filtros.
No painel Detalhes do trace, selecione o trace e acesse a guia Projects.
Esta guia lista os projetos que armazenam spans para o rastro.
Para criar um escopo de trace que contenha os projetos listados, acesse a barra de ferramentas da guia Projects e selecione Create scope with these projects e conclua a caixa de diálogo.
Repita as etapas anteriores até compilar uma lista de projetos.
Depois de compilar uma lista de projetos, crie um escopo de trace. Você também pode definir o escopo do trace como padrão.
Definir o escopo de rastreamento padrão
Quando a página Trace Explorer é aberta, ela pesquisa os projetos listados no escopo de trace padrão para dados de trace. Se esse escopo de rastreamento não for acessível, o projeto será pesquisado para dados de rastreamento.
Quando os projetos são criados, o escopo de rastreamento chamado _Default é criado
e designado como o escopo de rastreamento padrão. No entanto, você pode criar
seu próprio escopo de rastreamento e designá-lo como o escopo
padrão.
Para definir o escopo de rastreamento padrão, faça o seguinte:
-
No console do Google Cloud, abra a página settings Configurações:
Se você usar a barra de pesquisa para encontrar essa página, selecione o resultado com o subtítulo Monitoramento.
- Selecione a guia Trace Scopes.
Encontre o escopo de rastreamento que você quer designar como padrão, clique em more_vert Mais e selecione Definir como padrão.
O escopo de rastreamento selecionado é mostrado com um ícone "Padrão",
.
Modificar ou excluir um escopo de rastreamento
Não é possível excluir ou modificar o
escopo de rastreamento chamado _Default. É possível modificar ou excluir todos os outros
escopos de rastreamento.
Para modificar ou excluir um escopo de rastreamento, faça o seguinte:
-
No console do Google Cloud, abra a página settings Configurações:
Se você usar a barra de pesquisa para encontrar essa página, selecione o resultado com o subtítulo Monitoramento.
- Selecione a guia Trace Scopes.
Encontre o escopo de rastreamento que você quer modificar ou excluir, clique em more_vert Mais e faça uma das seguintes ações:
- Para modificar, selecione Editar escopo e preencha a caixa de diálogo.
- Para excluir, selecione Excluir escopo e preencha a caixa de diálogo.
Limitações
Não há suporte da API Cloud Trace ou da Google Cloud CLI para criar ou gerenciar escopos de rastreamento.
A seguir
O Cloud Logging e o Cloud Monitoring contêm construções semelhantes que permitem controlar os dados de registro ou de métrica que você pode consultar ou monitorar. Para informações sobre esses escopos, consulte os seguintes documentos: