Configurar escopos de observabilidade

Este documento descreve como configurar um projeto Google Cloud para monitorar ou mostrar dados de telemetria de vários projetos Google Cloud . Se você quiser apenas monitorar ou ver dados armazenados em um projeto doGoogle Cloud , não é necessário fazer nenhuma configuração. As ferramentas de visualização e análise são configuradas para usar os dados armazenados no projeto do Google Cloud selecionado pelo seletor de projetos. No entanto, se os dados de telemetria que você quer visualizar ou analisar forem de vários projetos, será necessário realizar algumas atividades de configuração para ter uma visão agregada desses dados.

Sobre os escopos de observabilidade

As ferramentas de análise e visualização do Google Cloud Observability dependem de escopos específicos do tipo de dados para determinar quais dados mostrar ou analisar. Um escopo define os recursos que são pesquisados para um tipo específico de dados. Com exceção dos dados de métricas, seus papéis do gerenciamento de identidade e acesso (IAM) nos projetos pesquisados e nas visualizações de registros determinam quais dados são mostrados.

O restante desta seção descreve os escopos que podem ser visualizados e configurados.

Escopo de observabilidade

Esse escopo controla como as páginas do explorador e do painel pesquisam os dados a serem mostrados. Cada projeto Google Cloud contém um único escopo de observabilidade, que lista o escopo de registros padrão, o escopo de métricas e o escopo de rastreamento padrão.

Recomendamos configurar os componentes do escopo de observabilidade nos seguintes cenários:

  • Você registra aplicativos com o App Hub. Podem ser aplicativos que você registrou ou aqueles implantados usando a central de design de aplicativos.
  • Quando você quer uma visão unificada dos dados de telemetria armazenados em diferentes projetos do Google Cloud .

Não é necessário configurar os componentes do escopo de observabilidade de um projeto. Se você usa os padrões do sistema, acontece o seguinte:

  • A página Análise de registros mostra os dados de registro originados no projeto.
  • As páginas Metrics Explorer e Trace Explorer mostram os dados de métricas e rastreamentos armazenados no projeto.
  • As políticas de alertas monitoram os dados de métricas armazenados no projeto.

Escopos de registros

Configure o escopo de registro padrão de um projeto para que, ao abrir a página Análise de registros, os dados que você costuma querer ver sejam exibidos. Um escopo de registro pode listar projetos, pastas, organizações e visualizações de registro. Por exemplo, é possível definir o escopo de registro padrão para listar uma visualização de registros que, quando consultada, retorna os dados de registro de um aplicativo do App Hub.

É possível criar vários escopos de registro. Ao usar a página Análise de registros, é possível selecionar um escopo de registro diferente, o que faz com que a página pesquise os recursos listados no escopo selecionado e atualize a exibição.

Recomendamos configurar o escopo de registro padrão nos seguintes cenários:

  • Você encaminha dados de registro para um bucket de registros centralizado.
  • Você encaminha dados de registros para outros projetos ou para buckets de registros armazenados por outro projeto.
  • Você usa visualizações de registros.

Para mais informações, consulte Criar e gerenciar escopos de registros.

Escopo de métricas

Configure o escopo de métricas para listar todos os projetos que armazenam dados de métricas. Assim, seus gráficos e políticas de alertas podem mostrar ou monitorar uma visão agregada dos dados de métricas.

Cada projeto Google Cloud contém um único escopo de métricas, que, por padrão, lista apenas o projeto.

Recomendamos configurar o escopo de métricas quando qualquer uma das condições a seguir for verdadeira:

  • Você quer criar um gráfico com dados armazenados em projetos diferentes.
  • Você quer uma política de alertas para monitorar dados armazenados em projetos diferentes.
  • Você registra aplicativos com o App Hub. Para mais informações sobre esse cenário, consulte Escopos de métricas para projetos de gerenciamento.

Para mais informações, consulte Visão geral dos escopos de métricas.

Escopos de trace

Configure o escopo de trace padrão para listar todos os projetos que armazenam dados de trace. Assim, quando você abrir a página Explorador de traces, terá uma visualização agregada dos dados de trace.

É possível criar vários escopos de rastreamento. Ao usar a página Trace Explorer, você pode selecionar um escopo de trace diferente. Isso faz com que a página pesquise os projetos listados no escopo selecionado e atualize a exibição.

Recomendamos configurar os escopos de rastreamento quando você quiser uma visão unificada dos dados de rastreamento armazenados em diferentes projetos.

Para mais informações, consulte Criar e gerenciar escopos de rastreamento.

Configurar o escopo de observabilidade

Esta seção não se aplica a pastas ou organizações.

Para dados de registros e rastreamentos, seus papéis do gerenciamento de identidade e acesso (IAM) no projeto que você está visualizando e em todos os projetos e visualizações de registros pesquisados afetam os dados retornados pela consulta. Se você emitir uma consulta para ver dados de registro sem permissão, ela não vai retornar nada.

Para dados de métricas, quando o escopo de métricas de um projeto é configurado, o projeto recebe acesso de leitura aos dados de métricas armazenados pelos projetos listados no escopo de métricas. Quando um usuário recebe um papel do gerenciamento de identidade e acesso (IAM) que permite visualizar dados de métricas em um projeto, ele pode acessar os dados de métricas disponíveis para o projeto.

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 ter as permissões necessárias para criar e visualizar escopos, peça ao administrador para conceder a você os seguintes papéis do IAM:

    • Para criar e visualizar escopos de registros e receber o escopo de registros padrão: Gravador de configuração de registros (roles/logging.configWriter) no seu projeto
    • Para modificar um escopo de métricas: Administrador do Monitoring (roles/monitoring.admin) no seu projeto e em cada projeto que você quer adicionar aos escopos de métricas
    • Para criar e visualizar escopos de rastreamento, além de receber e definir escopos padrão: 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 .

    Ver e definir o escopo padrão

    Console

    Para configurar o escopo de observabilidade, configure os componentes dele, que são o escopo de registros padrão, o escopo de métricas e o escopo de rastreamento padrão:

    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. Configure o escopo de registros padrão:

      1. Selecione a guia Escopos de registros.

        Os escopos de registros atuais são listados. A entrada com o ícone "Padrão", , é o escopo de registro padrão. Se você quiser criar um escopo de registros, clique em Criar escopo de registros e preencha a caixa de diálogo. Para mais informações, consulte Criar e gerenciar escopos de registros.

      2. Encontre a entrada que você quer designar como padrão, clique em  Mais e selecione Definir como padrão.

    4. Configure o escopo das métricas:

      1. Selecione a guia "Escopo de métricas".
      2. No painel Projetos do Google Cloud, clique em Adicionar projetos e preencha a caixa de diálogo. Para mais informações, consulte Configurar escopos de métricas.

    5. Configure o escopo de rastreamento padrão:

      1. Selecione a guia Escopos de rastreamento e faça o seguinte:

        Os escopos de rastreamento atuais são listados. A entrada com o ícone "Padrão", , é o escopo de rastreamento padrão. Se você quiser criar um escopo de rastreamento, clique em Criar escopo de registros e preencha a caixa de diálogo. Para mais informações, consulte Criar e gerenciar escopos de rastreamento.

      2. Encontre a entrada que você quer designar como padrão, clique em  Mais e selecione Definir como padrão.

    gcloud

    Para conferir e definir o escopo de observabilidade, faça o seguinte:

    1. Para conferir as configurações do escopo de observabilidade, execute o comando gcloud observability scopes describe.

      Antes de usar os dados do comando abaixo, faça estas substituições:

      • OBSERVABILITY_SCOPE_ID: o nome de um objeto Scope. Esse valor precisa ser definido como _Default.
      • LOCATION: o campo de local precisa ser definido como global.
      • PROJECT_ID: o identificador do projeto.

      Execute o comando gcloud observability scopes describe:

      Linux, macOS ou Cloud Shell

      gcloud observability scopes describe OBSERVABILITY_SCOPE_ID \
   --location=LOCATION\
   --project=PROJECT_ID

      Windows (PowerShell)

      gcloud observability scopes describe OBSERVABILITY_SCOPE_ID `
   --location=LOCATION`
   --project=PROJECT_ID

      Windows (cmd.exe)

      gcloud observability scopes describe OBSERVABILITY_SCOPE_ID ^
   --location=LOCATION^
   --project=PROJECT_ID

      A resposta ao comando é semelhante a esta: 

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

    2. Para atualizar o escopo de observabilidade, execute o comando gcloud observability scopes update. No comando update, inclua a flag --log-scope para atualizar o escopo de registro padrão.

      Antes de usar os dados do comando abaixo, faça estas substituições:

      • OBSERVABILITY_SCOPE_ID: o nome de um objeto Scope. Esse valor precisa ser definido como _Default.
      • LOG_SCOPE_FQN_ID: o ID totalmente qualificado do escopo de registro. Esse campo tem o seguinte formato: 
        logging.googleapis.com/projects/PROJECT_ID/locations/LOCATION/logScopes/LOG_SCOPE_ID

        Na expressão anterior, LOG_SCOPE_ID é o ID do escopo de registros. Por exemplo, my-scope.

      • LOCATION: o campo de local precisa ser definido como global.
      • PROJECT_ID: o identificador do projeto.

      Execute o comando gcloud observability scopes update:

      Linux, macOS ou Cloud Shell

      gcloud observability scopes update OBSERVABILITY_SCOPE_ID \
   --log-scope=LOG_SCOPE_FQN_ID\
   --location=LOCATION\
   --project=PROJECT_ID

      Windows (PowerShell)

      gcloud observability scopes update OBSERVABILITY_SCOPE_ID `
   --log-scope=LOG_SCOPE_FQN_ID`
   --location=LOCATION`
   --project=PROJECT_ID

      Windows (cmd.exe)

      gcloud observability scopes update OBSERVABILITY_SCOPE_ID ^
   --log-scope=LOG_SCOPE_FQN_ID^
   --location=LOCATION^
   --project=PROJECT_ID

      Por exemplo, se o valor de LOG_SCOPE_ID for my-scope, a resposta será semelhante a esta: 

      Updated scope [_Default].
logScope: logging.googleapis.com/projects/my-project/locations/global/logScopes/my-scope
name: projects/my-project/locations/global/scopes/_Default

    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"
}