Criar e gerenciar escopos de rastreamento

Este documento descreve como criar e gerenciar um escopo de rastreamento, que permite que a página Explorador de rastreamento encontre os períodos de rastreamento que você quer visualizar ou analisar. Se você quiser apenas ver e analisar os intervalos que se originam no projeto Google Cloud , não será necessário configurar nenhum escopo de rastreamento. No entanto, se os dados de rastreamento forem armazenados em vários projetos, como pode acontecer ao usar uma arquitetura de microsserviços, será necessário realizar algumas atividades de configuração para ver todos os intervalos de um único projeto Google Cloud .

Este documento não descreve como visualizar seus rastreamentos e intervalos. Para informações sobre esse tópico, consulte Encontrar e explorar traces.

Esse recurso só é compatível com projetos Google Cloud . Para configurações do App Hub, selecione o projeto host do App Hub ou o projeto de gerenciamento da pasta com app ativado.

Sobre escopos de trace

Os escopos de rastreamento são recursos persistentes no nível do projeto que listam um conjunto de projetos do Google Cloud . É possível configurar a página do Explorador de traces para pesquisar por escopo de trace, o que significa que ela pesquisa os projetos listados no escopo selecionado. Seus papéis do Identity and Access Management (IAM) nos projetos pesquisados e a configuração de período determinam quais dados são buscados no armazenamento e exibidos.

Quando você cria um projeto Google Cloud , um escopo de rastreamento chamado _Default é criado. Esse escopo inclui apenas o projeto Google Cloud . Não é possível adicionar projetos a esse escopo nem excluir esse escopo.

Você pode criar escopos de rastreamento, além de modificar e excluir qualquer um deles. Você quer criar um escopo de rastreamento quando tem um serviço que grava dados de extensão em vários projetos do Google Cloud .

A menos que você abra a página Explorador de traces com um URL que inclua um escopo de trace ou um ID de trace e período, a página Explorador de traces pesquisa os projetosGoogle Cloud listados no escopo de trace padrão para dados de trace. Quando você cria um projeto, o escopo de rastreamento chamado _Default é definido como o padrão. No entanto, é possível selecionar um escopo de rastreamento diferente para usar como padrão.

Aplicativos do App Hub e escopos de rastreamento

Seus aplicativos do App Hub podem gravar dados de rastreamento em vários projetos. Para ter uma visão agregada desses dados, crie um escopo de rastreamento, configure-o para listar todos os projetos que armazenam seus dados de rastreamento e defina-o como o escopo de rastreamento padrão. Quando você concluir essas etapas, a página Explorador de rastreamentos vai mostrar automaticamente os dados gravados pelo aplicativo, mesmo que eles estejam armazenados em projetos diferentes.

Crie o escopo de rastreamento personalizado no projeto em que você vai ver os dados de registro. Esse projeto é o host do App Hub ou o projeto de gerenciamento da sua pasta habilitada para gerenciar apps. Por exemplo, se o nome de exibição da pasta for My Folder, o nome de exibição do projeto de gerenciamento será My Folder-mp.

Antes de começar

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

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

    Go to project selector

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

  4. Enable the Observability API.

    Enable the API

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

    Go to project selector

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

  7. Enable the Observability API.

    Enable the API

    8.

  8. Para receber as permissões necessárias para criar e visualizar escopos de rastreamento, peça ao administrador para conceder a você o papel do IAM de Editor de escopos de observabilidade (roles/observability.scopesEditor) no seu 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.

    O papel de editor de escopos de observabilidade inclui permissões particulares que permitem criar e visualizar escopos de rastreamento. Essas permissões não estão disponíveis para inclusão em papéis personalizados do IAM.

  9. Select the tab for how you plan to use the samples on this page:

    Console

    When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

    gcloud

    In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

    REST

    Para usar as amostras da API REST nesta página em um ambiente de desenvolvimento local, use as credenciais fornecidas para a CLI gcloud.

      Instale a CLI do Google Cloud. Após a instalação, inicialize a CLI do Google Cloud executando o seguinte comando: 

      gcloud init

      Ao usar um provedor de identidade (IdP) externo, primeiro faça login na gcloud CLI com sua identidade federada.

    Para mais informações, consulte Autenticar para usar REST na documentação de autenticação do Google Cloud .

    Listar escopos de trace

    Console

    Para listar os escopos de rastreamento, faça o seguinte:

    1. No Google Cloud console, acesse a página  Configurações:

      Acessar Configurações

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

    2. Na barra de ferramentas do console Google Cloud , selecione seu projeto Google Cloud . Para configurações do App Hub, selecione o projeto host do App Hub ou o projeto de gerenciamento da pasta com app ativado.

    3. Selecione a guia Escopos de rastreamento.

      A tabela lista seus escopos de rastreamento. Quando você seleciona um projeto Google Cloud , uma entrada é mostrada com um ícone "Padrão", , que indica que é o escopo de rastreamento padrão. A página Explorador de traces pesquisa os projetos listados no escopo de trace padrão para dados de trace quando a página é aberta.

    gcloud

    Incompatível.

    REST

    Para listar todos os escopos de rastreamento em um projeto Google Cloud , use o comando projects.locations.traceScopes.list. É necessário especificar um parâmetro de caminho.

    O parâmetro de caminho para esse endpoint tem a seguinte sintaxe:

    projects/PROJECT_ID/locations/LOCATION_ID/traceScopes

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

    • PROJECT_ID: o identificador do projeto. Para configurações do App Hub, selecione o projeto host do App Hub ou o projeto de gerenciamento da pasta com app ativado.
    • LOCATION_ID precisa ser definido como global.

    A resposta é uma matriz de objetos TraceScope. Cada objeto inclui um nome e uma lista de recursos.

    Para informações sobre um escopo de rastreamento específico, use o comando projects.locations.traceScopes.get.

    Criar um escopo de rastreamento

    Os períodos mostrados na página do Buscador de trace dependem dos projetos pesquisados, das suas funções do IAM nesses projetos, da configuração de período e dos filtros aplicados.

    É possível criar 100 escopos de rastreamento por projeto. Um escopo de rastreamento pode incluir um total de 20 projetos.

    Console

    Para criar um escopo de rastreamento, faça o seguinte:

    1. No Google Cloud console, acesse a página  Configurações:

      Acessar Configurações

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

    2. Na barra de ferramentas do console Google Cloud , selecione seu projeto Google Cloud . Para configurações do App Hub, selecione o projeto host do App Hub ou o projeto de gerenciamento da pasta com app ativado.
    3. Selecione a guia Escopos de rastreamento e clique em Criar escopo de rastreamento.

    4. Clique em Adicionar projetos e preencha a caixa de diálogo.

      Se você não souber quais projetos incluir em um escopo, use a página legada do Buscador de trace para ajudar a identificá-los. Para mais informações, consulte a seção Migrar para escopos de rastreamento deste documento.

    5. 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 rastreamento não pode ser modificado e precisa ser exclusivo no projeto.

    6. Clique em Criar escopo de rastreamento.

    gcloud

    Incompatível.

    REST

    Para criar um escopo de rastreamento, use o comando projects.locations.traceScopes.create. É necessário especificar um parâmetro de caminho e fornecer um objeto TraceScope. A resposta é um objeto TraceScope.

    O parâmetro de caminho para esse endpoint tem a seguinte sintaxe:

    projects/PROJECT_ID/locations/LOCATION_ID/traceScopes

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

    • PROJECT_ID: o identificador do projeto. Para configurações do App Hub, selecione o projeto host do App Hub ou o projeto de gerenciamento da pasta com app ativado.
    • LOCATION_ID precisa ser definido como global.

    Migrar para escopos de trace

    A página Buscador de trace exige que você especifique os Google Cloud projetos em que pesquisar dados de trace, o que é uma mudança de comportamento em relação à página legada Buscador de trace. A página legada do Buscador de trace pesquisa todos os projetos em uma organização. Devido a essas diferenças, a página Explorador de traces pode não mostrar intervalos que as páginas legadas do Explorador de traces mostram.

    Use a seção do painel Detalhes do trace da página legada do Buscador de trace para compilar uma lista de projetos doGoogle Cloud que armazenam seus dados de trace:

    1. Acesse a página legada do Explorador de traces:

      Acessar o Explorador de traces legado

    2. Na barra de ferramentas do console Google Cloud , selecione seu projeto Google Cloud . Para configurações do App Hub, selecione o projeto host do App Hub ou o projeto de gerenciamento da pasta com app ativado.

    3. Selecione um rastreamento.

      Tente o seguinte:

      • Inserir o ID no campo ID do rastreamento.
      • Adicionar filtros.

    4. No painel Detalhes do trace, selecione o trace e acesse a guia Projetos.

      Essa guia lista os projetos que armazenam intervalos para o rastreamento.

    5. Para criar um escopo de rastreamento que contenha os projetos listados, acesse a barra de ferramentas da guia Projetos e selecione Criar escopo com esses projetos. Em seguida, preencha a caixa de diálogo.

    6. Repita as etapas anteriores até compilar uma lista de projetos.

    Depois de compilar uma lista de projetos, crie um escopo de rastreamento. Você também pode definir como o escopo de rastreamento 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.

    Console

    Para modificar ou excluir um escopo de rastreamento, faça o seguinte:

    1. No Google Cloud console, acesse a página  Configurações:

      Acessar Configurações

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

    2. Na barra de ferramentas do console Google Cloud , selecione seu projeto Google Cloud . Para configurações do App Hub, selecione o projeto host do App Hub ou o projeto de gerenciamento da pasta com app ativado.
    3. Selecione a guia Escopos de rastreamento.

    4. Encontre o escopo de rastreamento que você quer modificar ou excluir, clique em  Mais e faça o seguinte:

      • Para modificar, selecione Editar escopo e preencha a caixa de diálogo.
      • Para excluir, selecione Excluir escopo e preencha a caixa de diálogo.

    gcloud

    Incompatível.

    REST

    Modificar um escopo

    Para modificar um escopo de rastreamento, use o comando projects.locations.traceScopes.patch. É necessário especificar um parâmetro de caminho, parâmetros de consulta e fornecer um objeto TraceScope. Os parâmetros de consulta identificam quais campos foram alterados. A resposta é um objeto TraceScope.

    O parâmetro de caminho para esse endpoint tem a seguinte sintaxe:

    projects/PROJECT_ID/locations/LOCATION_ID/traceScopes/TRACE_SCOPE_NAME

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

    • PROJECT_ID: o identificador do projeto. Para configurações do App Hub, selecione o projeto host do App Hub ou o projeto de gerenciamento da pasta com app ativado.
    • LOCATION_ID precisa ser definido como global.
    • TRACE_SCOPE_NAME: o nome de um escopo de rastreamento. Por exemplo, my-trace-scope.

    Excluir um escopo

    Para excluir um escopo de rastreamento, use o comando projects.locations.traceScopes.delete. É necessário especificar um parâmetro de caminho.

    O parâmetro de caminho para esse endpoint tem a seguinte sintaxe:

    projects/PROJECT_ID/locations/LOCATION_ID/traceScopes/TRACE_SCOPE_NAME

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

    • PROJECT_ID: o identificador do projeto. Para configurações do App Hub, selecione o projeto host do App Hub ou o projeto de gerenciamento da pasta com app ativado.
    • LOCATION_ID precisa ser definido como global.
    • TRACE_SCOPE_NAME: o nome de um escopo de rastreamento. Por exemplo, my-trace-scope.

    Configurar o escopo de rastreamento padrão

    Quando a página Explorador de traces é aberta, ela pesquisa os projetos listados no escopo de trace padrão em busca de dados de trace. Se esse escopo de rastreamento não estiver acessível, o projeto será pesquisado em busca de 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, é possível criar seu próprio escopo de rastreamento e designá-lo como o padrão.

    Console

    Para definir o escopo de rastreamento padrão, faça o seguinte:

    1. No Google Cloud console, acesse a página  Configurações:

      Acessar Configurações

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

    2. Na barra de ferramentas do console Google Cloud , selecione seu projeto Google Cloud . Para configurações do App Hub, selecione o projeto host do App Hub ou o projeto de gerenciamento da pasta com app ativado.

    3. Selecione a guia Escopos de rastreamento.

      A guia mostra seus escopos de rastreamento e inclui um botão para criar um escopo de rastreamento personalizado. O escopo de rastreamento mostrado com um ícone "Padrão", , é o escopo de rastreamento padrão atual.

    4. Para mudar o escopo de rastreamento padrão, encontre o escopo que você quer designar como padrão, clique em  Mais e selecione Definir como padrão.

      O escopo de rastreamento selecionado é mostrado com um ícone "Padrão", .

    gcloud

    Incompatível.

    REST

    Para receber e definir o escopo de registro ou de rastreamento padrão usando uma chamada de API, configure o escopo de observabilidade. O escopo de observabilidade lista o escopo de registro e o escopo de rastreamento padrão:

    • Para receber o escopo de observabilidade padrão de um projeto, envie uma solicitação ao endpoint projects.locations.scopes.get. É necessário especificar um parâmetro de caminho. A resposta é um objeto Scope, que lista o escopo de registros e o escopo de rastreamento padrão.

    • Para atualizar o escopo de observabilidade padrão de um projeto, envie uma solicitação ao endpoint projects.locations.scopes.patch. É necessário especificar um parâmetro de caminho, parâmetros de consulta e fornecer um objeto Scope. Os parâmetros de consulta identificam quais campos foram alterados. A resposta é um objeto Scope.

    O parâmetro de caminho para ambos os endpoints tem o seguinte formato:

    projects/PROJECT_ID/locations/LOCATION/scopes/OBSERVABILITY_SCOPE_ID

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

    • PROJECT_ID: o identificador do projeto. Para configurações do App Hub, selecione o projeto host do App Hub ou o projeto de gerenciamento da pasta com app ativado.
    • LOCATION: o campo de local precisa ser definido como global.
    • OBSERVABILITY_SCOPE_ID: o nome de um objeto Scope. Esse campo precisa ser definido como _Default. O objeto Scope com o nome _Default, que é criado automaticamente, armazena informações sobre o escopo de registro e o escopo de rastreamento padrão.

    Para enviar um comando a um endpoint de API, use o APIs Explorer, que permite emitir um comando em uma página de referência. Por exemplo, para receber o escopo padrão atual, faça o seguinte:

    1. Clique em projects.locations.scopes.get.

    2. No widget Testar este método, insira o seguinte no campo name:

      projects/PROJECT_ID/locations/global/scopes/_Default

      Antes de copiar o campo anterior, substitua PROJECT_ID pelo nome do projeto.

    3. Selecione Executar.

    4. Na caixa de diálogo de autorização, conclua as etapas necessárias.

      A resposta é semelhante a:

      {
"name": "projects/my-project/locations/global/scopes/_Default",
"logScope": "logging.googleapis.com/projects/my-project/locations/global/logScopes/_Default"
"traceScope": "projects/my-project/locations/global/traceScopes/_Default"
}

    Limites nos escopos de rastreamento

    Limites nos escopos de rastreamento Valor
    Número máximo de escopos de rastreamento por projeto 100
    Número máximo de projetos por escopo de rastreamento 20

    A seguir