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 visualizar 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 Identity and Access Management (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ê depender dos padrões do sistema, vai acontecer 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 traces 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 das 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 Identity and Access Management (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 Identity and Access Management (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. Enable the Observability API.

    Enable the API

    Antes de ativar a API, verifique se o projeto correto está selecionado. Para configurações do App Hub, selecione o projeto host do App Hub ou o projeto de gerenciamento da pasta com app ativado.

  2. 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 e receber o escopo de rastreamento padrão: Usuário do Cloud Trace (roles/cloudtrace.user) no seu projeto
    • Para receber e definir escopos 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 escopos. 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:

    • Para configurar escopos de registros: logging.logScopes.{create, delete, get, list, update}
    • Para configurar um escopo de métricas: monitoring.metricsscopes.{link, get, list}
    • Para configurar escopos de rastreamento: cloudtrace.traceScopes.{create, delete, get, list, update}
    • Para receber e definir escopos padrão: observability.scopes.{get, update}

    Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.

  3. 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 Google Cloud CLI executando o seguinte comando: 

      gcloud init

      Se você estiver usando um provedor de identidade externo (IdP), primeiro faça login na CLI gcloud 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 registro 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 padrão, faça o seguinte:

    1. Para conferir as configurações do escopo padrão, 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
name: projects/my-project/locations/global/scopes/_Default

    2. Para atualizar o escopo padrão, execute o comando gcloud observability scopes update.

      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 usar a API Observability e receber ou definir o escopo de registro padrão, faça o seguinte:

    • Para receber o escopo de registros 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 registro padrão.

    • Para atualizar o escopo de registro 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 armazena informações sobre o escopo de registros padrão e é criado automaticamente.

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