Crie e faça a gestão de âmbitos de rastreio

Este documento descreve como pode criar e gerir um âmbito de rastreio, que permite à página Explorador de rastreios encontrar os intervalos de rastreio que quer ver ou analisar. Se só quiser ver e analisar os intervalos que têm origem no seu projeto, não precisa de configurar âmbitos de rastreio. Google Cloud No entanto, se os seus dados de rastreio estiverem armazenados em vários projetos, como pode acontecer quando usa uma arquitetura de microsserviços, tem de realizar algumas atividades de configuração para ver todos os intervalos de um único projeto Google Cloud .

Este documento não descreve como ver os seus rastreios e intervalos. Para obter informações sobre esse tópico, consulte o artigo Encontre e explore rastreios.

Esta funcionalidade só é suportada para projetos do Google Cloud . Para configurações do App Hub, selecione o projeto anfitrião do App Hub ou o projeto de gestão da pasta com apps ativadas.

Acerca dos âmbitos de rastreio

Os âmbitos de rastreio são recursos persistentes ao nível do projeto que listam um conjunto de Google Cloud projetos. Pode configurar a página Explorador de rastreios para pesquisar por âmbito de rastreio, o que significa que a página pesquisa os projetos listados no âmbito selecionado. As suas funções de gestão de identidade e de acesso (IAM) nos projetos pesquisados e a definição do intervalo de tempo determinam os dados obtidos do armazenamento e, em seguida, apresentados.

Quando cria um Google Cloud projeto, é criado um âmbito de rastreio denominado _Default. Este âmbito inclui apenas o Google Cloud projeto. Não pode adicionar projetos a este âmbito nem eliminar este âmbito.

Pode criar âmbitos de rastreio, bem como modificar e eliminar quaisquer âmbitos de rastreio que criar. Quer criar um âmbito de rastreio quando tem um serviço que escreve dados de intervalos em vários Google Cloud projetos.

A menos que abra a página do Explorador de rastreios com um URL que inclua um âmbito de rastreio ou um ID de rastreio e intervalo, a página do Explorador de rastreios pesquisa os Google Cloud projetos listados no âmbito de rastreio predefinido para dados de rastreio. Quando cria o projeto, o âmbito de rastreio denominado _Default é definido como o âmbito de rastreio predefinido. No entanto, pode selecionar um âmbito de rastreio diferente para usar como âmbito de rastreio predefinido.

Aplicações do App Hub e âmbitos de rastreio

As suas aplicações do App Hub podem escrever dados de rastreio em vários projetos. Para obter uma vista agregada destes dados, crie um âmbito de rastreio, configure-o para listar todos os projetos que armazenam os seus dados de rastreio e, em seguida, configure-o como o âmbito de rastreio predefinido. Quando concluir esses passos, a página Explorador de rastreios apresenta automaticamente os dados escritos pela sua aplicação, mesmo quando esses dados estão armazenados em projetos diferentes.

Crie o âmbito do rastreio personalizado no projeto a partir do qual vai ver os dados de registo. Este projeto é o projeto anfitrião do App Hub ou o projeto de gestão da sua pasta com apps ativadas. Por exemplo, se o nome a apresentar da pasta for My Folder, o nome a apresentar do projeto de gestão é 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.

    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 (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 Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. 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 (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 Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

    8.

  8. Para receber as autorizações de que precisa para criar e ver âmbitos de rastreio, peça ao seu administrador para lhe conceder a função IAM de editor de âmbitos de observabilidade (roles/observability.scopesEditor) no seu projeto. Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

    Também pode conseguir as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.

    A função de editor de âmbitos de observabilidade inclui autorizações privadas que lhe permitem criar e ver âmbitos de rastreio. Estas autorizações não estão disponíveis para inclusão em funções de IAM personalizadas.

  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 os exemplos da API REST nesta página num ambiente de desenvolvimento local, usa as credenciais que fornece à CLI gcloud.

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

      gcloud init

      Se estiver a usar um fornecedor de identidade (IdP) externo, primeiro tem de iniciar sessão na CLI gcloud com a sua identidade federada.

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

    Apresentar âmbitos de rastreio

    Consola

    Para listar os âmbitos de rastreio, faça o seguinte:

    1. Na Google Cloud consola, aceda à página  Definições:

      Aceda a Definições

      Se usar a barra de pesquisa para encontrar esta página, selecione o resultado cujo subtítulo é Monitorização.

    2. Na barra de ferramentas da Google Cloud consola, selecione o seu Google Cloud projeto. Para configurações do App Hub, selecione o projeto anfitrião do App Hub ou o projeto de gestão da pasta com apps ativadas.

    3. Selecione o separador Âmbitos de rastreio.

      A tabela apresenta os seus âmbitos de rastreio. Quando seleciona um Google Cloud projeto, é apresentada uma entrada com um ícone "Predefinição", , que indica que é o âmbito de rastreio predefinido. A página Explorador de rastreios pesquisa os projetos listados no âmbito de rastreio predefinido para dados de rastreio quando a página é aberta.

    gcloud

    Não suportado.

    REST

    Para apresentar uma lista de todos os âmbitos de rastreio num Google Cloud projeto, use o comando projects.locations.traceScopes.list. Tem de especificar um parâmetro de caminho.

    O parâmetro de caminho para este ponto final 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 anfitrião do App Hub ou o projeto de gestão da pasta com apps ativadas.
    • LOCATION_ID tem de ser definido como global.

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

    Para obter informações sobre um âmbito de rastreio específico, use o comando projects.locations.traceScopes.get.

    Crie um âmbito de rastreio

    Os intervalos apresentados na página Explorador de rastreios dependem dos projetos pesquisados, das suas funções da IAM nesses projetos, da definição do intervalo de tempo e dos filtros que aplica.

    Pode criar 100 âmbitos de rastreio por projeto. Um âmbito de rastreio pode incluir um total de 20 projetos.

    Consola

    Para criar um âmbito de rastreio, faça o seguinte:

    1. Na Google Cloud consola, aceda à página  Definições:

      Aceda a Definições

      Se usar a barra de pesquisa para encontrar esta página, selecione o resultado cujo subtítulo é Monitorização.

    2. Na barra de ferramentas da Google Cloud consola, selecione o seu Google Cloud projeto. Para configurações do App Hub, selecione o projeto anfitrião do App Hub ou o projeto de gestão da pasta com apps ativadas.
    3. Selecione o separador Âmbitos de rastreio e, de seguida, clique em Criar âmbito de rastreio.

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

      Se não souber que projetos incluir num âmbito, pode usar a página do Explorador de rastreio antigo para ajudar a identificá-los. Para mais informações, consulte a secção Migre para âmbitos de rastreio deste documento.

    5. Na secção Nome do âmbito do rastreio, introduza o nome e a descrição que quer apresentar no separador Âmbitos do rastreio.

      Não é possível modificar o nome de um âmbito de rastreio, e este tem de ser exclusivo no projeto.

    6. Clique em Criar âmbito do rastreio.

    gcloud

    Não suportado.

    REST

    Para criar um âmbito de rastreio, use o comando projects.locations.traceScopes.create. Tem de especificar um parâmetro de caminho e fornecer um objeto TraceScope. A resposta é um objeto TraceScope.

    O parâmetro de caminho para este ponto final 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 anfitrião do App Hub ou o projeto de gestão da pasta com apps ativadas.
    • LOCATION_ID tem de ser definido como global.

    Migre para âmbitos de rastreio

    A página Explorador de rastreios requer que especifique os Google Cloud projetos nos quais pesquisar dados de rastreio, o que representa uma alteração no comportamento em relação à página Explorador de rastreios antiga. A página Explorador de rastreios antigo pesquisa todos os projetos numa organização. Devido a estas diferenças, a página Explorador de rastreios pode não apresentar intervalos que as páginas do Explorador de rastreios antigo apresentam.

    Pode usar a secção do painel Detalhes do rastreio da página do Explorador de rastreios antigo para ajudar a compilar uma lista de Google Cloud projetos que armazenam os seus dados de rastreio:

    1. Aceda à página do Explorador de rastreios antigo:

      Aceda ao explorador de rastreios antigo

    2. Na barra de ferramentas da Google Cloud consola, selecione o seu Google Cloud projeto. Para configurações do App Hub, selecione o projeto anfitrião do App Hub ou o projeto de gestão da pasta com apps ativadas.

    3. Selecione um rastreio.

      Pode experimentar o seguinte:

      • Ver um rastreio introduzindo o respetivo ID no campo ID do rastreio.
      • Adicionar filtros.

    4. No painel Detalhes do rastreio, selecione o rastreio e, de seguida, aceda ao separador Projetos.

      Este separador apresenta os projetos que armazenam intervalos para o rastreio.

    5. Para criar um âmbito de rastreio que contenha os projetos indicados, aceda à barra de ferramentas do separador Projetos e selecione Criar âmbito com estes projetos e, de seguida, conclua a caixa de diálogo.

    6. Repita os passos anteriores até compilar uma lista de projetos.

    Depois de compilar uma lista de projetos, crie um âmbito de rastreio. Também pode defini-lo como o âmbito do rastreio predefinido.

    Modifique ou elimine um âmbito de rastreio

    Não pode eliminar nem modificar o âmbito do rastreio com o nome _Default. Pode modificar ou eliminar todos os outros âmbitos de rastreio.

    Consola

    Para modificar ou eliminar um âmbito de rastreio, faça o seguinte:

    1. Na Google Cloud consola, aceda à página  Definições:

      Aceda a Definições

      Se usar a barra de pesquisa para encontrar esta página, selecione o resultado cujo subtítulo é Monitorização.

    2. Na barra de ferramentas da Google Cloud consola, selecione o seu Google Cloud projeto. Para configurações do App Hub, selecione o projeto anfitrião do App Hub ou o projeto de gestão da pasta com apps ativadas.
    3. Selecione o separador Âmbitos de rastreio.

    4. Encontre o âmbito do rastreio que quer modificar ou eliminar, clique em  Mais e, em seguida, faça uma das seguintes ações:

      • Para modificar, selecione Editar âmbito e, de seguida, conclua a caixa de diálogo.
      • Para eliminar, selecione Eliminar âmbito e, de seguida, conclua a caixa de diálogo.

    gcloud

    Não suportado.

    REST

    Modifique um âmbito

    Para modificar um âmbito de rastreio, use o comando projects.locations.traceScopes.patch. Tem de especificar um parâmetro de caminho, parâmetros de consulta e fornecer um objeto TraceScope. Os parâmetros de consulta identificam os campos que são alterados. A resposta é um objeto TraceScope.

    O parâmetro de caminho para este ponto final 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 anfitrião do App Hub ou o projeto de gestão da pasta com apps ativadas.
    • LOCATION_ID tem de ser definido como global.
    • TRACE_SCOPE_NAME: o nome de um âmbito de rastreio. Por exemplo, my-trace-scope.

    Elimine um âmbito

    Para eliminar um âmbito de rastreio, use o comando projects.locations.traceScopes.delete. Tem de especificar um parâmetro de caminho.

    O parâmetro de caminho para este ponto final 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 anfitrião do App Hub ou o projeto de gestão da pasta com apps ativadas.
    • LOCATION_ID tem de ser definido como global.
    • TRACE_SCOPE_NAME: o nome de um âmbito de rastreio. Por exemplo, my-trace-scope.

    Configure o âmbito do rastreio predefinido

    Quando a página Explorador de rastreios é aberta, pesquisa os projetos listados no âmbito do rastreio predefinido para dados de rastreio. Se esse âmbito de rastreio não for acessível, o projeto é pesquisado quanto a dados de rastreio.

    Quando os projetos são criados, o âmbito do rastreio denominado _Default é criado e é designado como o âmbito do rastreio predefinido. No entanto, pode criar o seu próprio âmbito de rastreio e designá-lo como o âmbito de rastreio predefinido.

    Consola

    Para definir o âmbito do rastreio predefinido, faça o seguinte:

    1. Na Google Cloud consola, aceda à página  Definições:

      Aceda a Definições

      Se usar a barra de pesquisa para encontrar esta página, selecione o resultado cujo subtítulo é Monitorização.

    2. Na barra de ferramentas da Google Cloud consola, selecione o seu Google Cloud projeto. Para configurações do App Hub, selecione o projeto anfitrião do App Hub ou o projeto de gestão da pasta com apps ativadas.

    3. Selecione o separador Âmbitos de rastreio.

      O separador apresenta os âmbitos de rastreio e inclui um botão para criar um âmbito de rastreio personalizado. O âmbito do rastreio apresentado com um ícone "Predefinição", , é o âmbito do rastreio predefinido atual.

    4. Para alterar o âmbito do rastreio predefinido, encontre o âmbito do rastreio que quer designar como âmbito do rastreio predefinido, clique em  Mais e, de seguida, selecione Definir como predefinição.

      O âmbito do rastreio que selecionou é apresentado com um ícone "Predefinição", .

    gcloud

    Não suportado.

    REST

    Para obter e definir o âmbito do registo predefinido ou o âmbito do rastreio predefinido através de uma chamada API, configure o âmbito de observabilidade. O âmbito de observabilidade apresenta o âmbito de registo predefinido e o âmbito de rastreio predefinido:

    • Para obter o âmbito de observabilidade predefinido de um projeto, envie um pedido para o ponto final projects.locations.scopes.get. Tem de especificar um parâmetro de caminho. A resposta é um objeto Scope, que lista o âmbito do registo predefinido e o âmbito do rastreio predefinido.

    • Para atualizar o âmbito de observabilidade predefinido de um projeto, envie um pedido para o ponto final projects.locations.scopes.patch. Tem de especificar um parâmetro de caminho, parâmetros de consulta e fornecer um objeto Scope. Os parâmetros de consulta identificam os campos que foram alterados. A resposta é um objeto Scope.

    O parâmetro de caminho para ambos os pontos finais 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 anfitrião do App Hub ou o projeto de gestão da pasta com apps ativadas.
    • LOCATION: o campo de localização tem de estar definido como global.
    • OBSERVABILITY_SCOPE_ID: o nome de um objeto Scope. Este campo tem de ser definido como _Default. O objeto Scope com o nome _Default, que é criado automaticamente, armazena informações sobre o âmbito do registo predefinido e o âmbito do rastreio predefinido.

    Para enviar um comando para um ponto final da API, pode usar o Explorador de APIs, que lhe permite emitir um comando a partir de uma página de referência. Por exemplo, para obter o âmbito predefinido atual, pode fazer o seguinte:

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

    2. No widget Experimente este método, introduza o seguinte no campo nome:

      projects/PROJECT_ID/locations/global/scopes/_Default

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

    3. Selecione Executar.

    4. Na caixa de diálogo de autorização, conclua os passos necessários.

      A resposta é semelhante à seguinte:

      {
"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 âmbitos de rastreio

    Limites nos âmbitos de rastreio Valor
    Número máximo de âmbitos de rastreio por projeto 100
    Número máximo de projetos por âmbito de rastreio 20

    O que se segue?