Configurar escopos de observabilidade para consultas de vários projetos

Neste documento, descrevemos como criar gráficos ou visualizar dados de registros quando eles estão armazenados em vários projetos. Por padrão, apenas os dados originados em um projeto estão disponíveis para as ferramentas de visualização. No entanto, se você configurar um escopo, as ferramentas de visualização e análise poderão consultar dados armazenados em vários projetos.

Se você quiser apenas monitorar ou visualizar dados armazenados em um projetoGoogle Cloud , não será necessário fazer nenhuma configuração.

Os escopos fornecem agregação no tempo de leitura

Os escopos permitem que as ferramentas de visualização e análise façam a agregação em tempo de leitura de dados armazenados em vários locais. Os escopos não controlam onde os dados são armazenados. Em vez disso, os mecanismos de consulta usam escopos para determinar onde pesquisar dados.

Os dados de métricas e rastreamentos são sempre armazenados no projeto Google Cloud de origem. Para ver dados de métricas armazenados em vários projetos em um único gráfico, configure um escopo de métricas para listar esses projetos. Depois de configurar esse escopo, quando você criar um gráfico ou uma política de alertas, a consulta emitida por esses serviços vai retornar automaticamente dados de métricas dos projetos listados. O comportamento é semelhante para dados de rastreamento.

Por padrão, os dados de registro são armazenados no projeto, na conta de faturamento, na pasta ou na organização Google Cloud de origem dos dados. No entanto, é possível configurar o Logging para rotear dados de registro do recurso de origem para outro local, como outro projeto ou um bucket de registros centralizado. Em todos os casos, configure um escopo de registros personalizado. Recomendamos que seus escopos de registros listem visualizações de registros em vez de projetos. Uma visualização de registros oferece acesso de leitura a um subconjunto de entradas de registro em um bucket de registros. Por exemplo, se você tiver dados de registro armazenados em três projetos, poderá configurar a visualização de registros para incluir a visualização _Default/_AllLogs de cada um deles.

Como os escopos são usados pelo Google Cloud Observability

As ferramentas de análise e visualização do Google Cloud Observability dependem de escopos específicos do tipo de dados para determinar quais recursos consultar para os dados que a ferramenta vai mostrar ou analisar.

Exemplos:

  • Quando a página Análise de registros é aberta, o sistema consulta os recursos listados no escopo de registro padrão para dados de registro. Depois que a página for aberta, use uma opção da barra de ferramentas para consultar os recursos em um escopo diferente.
  • Quando a página Trace Explorer é aberta, o sistema consulta os projetos listados no escopo de trace padrão para dados de trace. Depois que esta página for aberta, use uma opção da barra de ferramentas para consultar os recursos em um escopo diferente.
  • Ao criar uma política de alertas, o Monitoring consulta os projetos listados no escopo de métricas para dados de métricas. Em seguida, ele analisa a resposta da consulta e determina se é necessário criar um incidente.
  • Ao criar um gráfico usando a página Metrics Explorer, você especifica uma métrica para representar. O Monitoring consulta os projetos listados no escopo de métricas para dados de métricas e mostra os resultados da consulta.

O Logging e o Trace verificam seus papéis do Identity and Access Management (IAM) em um recurso antes que uma consulta retorne dados. Por exemplo, se um escopo de registros especificar um projeto para o qual você não tem permissões de leitura de dados de registros, uma consulta a esse projeto não vai retornar dados.

O Monitoring verifica seu papel do IAM no projeto de onde a consulta é emitida. Suponha que o escopo de métricas de um projeto chamado AllEnv liste os seguintes projetos: AllEnv, Prod e Staging. Além disso, suponha que você tenha recebido o papel de leitor do Monitoring no projeto AllEnv. Os gráficos criados com a página Metrics Explorer ao usar o projeto AllEnv mostram automaticamente os dados de métricas dos três projetos.

Escopos do Google Cloud Observability

Esta seção descreve os escopos usados pelo Google Cloud Observability.

Escopo de observabilidade

O escopo de observabilidade especifica o escopo de registro e o escopo de rastreamento padrão. Páginas como a Análise de registros e o Buscador de trace usam os escopos padrão para determinar quais recursos consultar quando a página é aberta. Por exemplo, suponha que você tenha um aplicativo que gera dados de rastreamento em três projetos. É possível configurar a página do Buscador de trace para consultar automaticamente esses três projetos definindo o escopo de trace padrão.

Se você não configurar o escopo de observabilidade, vai acontecer o seguinte:

  • A página Explorador de registros consulta seu projeto para dados de registro.
  • A página Buscador de trace consulta seu projeto para dados de trace.

O escopo de observabilidade não se aplica a dados de métricas.

Quando configurar o escopo de observabilidade

Configure o escopo de observabilidade nos seguintes cenários:

  • Você cria um escopo de registros personalizado e quer que os recursos listados nele sejam consultados por padrão.

  • Você cria um escopo de rastreamento personalizado e quer que os projetos listados nele sejam consultados por padrão.

Limites associados aos escopos de observabilidade

Descrição Valor máximo
Número de escopos de observabilidade por projeto 1

Escopos de registros

Os escopos de registros são usados pela página Análise de registros e pelos painéis que mostram dados de registros:

  • Quando a página Análise de registros é aberta, o sistema consulta automaticamente os recursos listados no escopo de registro padrão para dados de registro. Esta página também oferece controles que permitem alternar entre escopos.

  • Para painéis, a implementação determina se o sistema consulta o projeto ou os recursos listados no escopo de registro padrão.

Um escopo de registro pode listar visualizações de registro, projetos, pastas e organizações.

Se você não configurar um escopo de registros personalizado, a página do Explorador de registros vai consultar seu projeto para dados de registros.

Quando criar escopos de registros personalizados

Crie escopos de registros personalizados para as seguintes configurações:

Em todos os casos, configure os escopos de registro personalizados para listar uma ou mais visualizações de registros. Essas visualizações podem estar em um bucket de registros centralizado ou em buckets diferentes. Se você usa um bucket de registros centralizado, pode criar vários escopos de registros personalizados, cada um com seu próprio conjunto de visualizações de registros.

Se você criar escopos de registros personalizados, considere atualizar o escopo de registros padrão.

Práticas recomendadas ao configurar escopos de registros

  • Inclua apenas visualizações de registros.
  • Não configure um escopo que liste projetos e visualizações de registros.

Limites associados a escopos de registros

Descrição Valor máximo
Número de escopos de registros por projeto 100
Número de projetos por escopo de registro 5
Número de visualizações de registros ou projetos por escopo de registro 100

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

Escopo de métricas

O escopo de métricas é usado por todas as consultas emitidas pelo Cloud Monitoring. Por exemplo, as políticas de alertas e as ferramentas de criação de gráficos, como o Metrics Explorer, emitem consultas de problemas para os projetos listados no escopo de métricas.

Se você não configurar o escopo de métricas, os serviços do Monitoring vão consultar seu projeto para dados de métricas.

Quando configurar os escopos de métricas

Configure o escopo de métricas quando alguma das seguintes condições 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.

Limites associados aos escopos de métricas

Descrição Valor máximo
Número de escopos de métricas por projeto 1
Número de projetos por escopo de métricas 375

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

Escopos de trace

Os escopos de rastreamento são usados pela página Explorador de rastreamento. Quando essa página é aberta, o sistema consulta automaticamente os projetos listados no escopo de trace padrão para dados de trace. Esta página também oferece controles que permitem alternar entre escopos.

Se você não configurar um escopo de trace personalizado, a página do Buscador de trace vai consultar seu projeto para dados de trace.

Quando criar escopos de rastreamento personalizados

Crie escopos de rastreamento personalizados quando tiver aplicativos que dependem de recursos em diferentes projetos do Google Cloud .

Limites associados aos escopos de rastreamento

Descrição Valor máximo
Número de escopos de rastreamento por projeto 100
Número de projetos por escopo de rastreamento 20

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 a que não tem permissão de acesso, 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.

Para configurar o escopo de observabilidade, defina o escopo de registro e o escopo de rastreamento padrão. O restante desta seção descreve como concluir essas ações.

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 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 gcloud CLI.

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

    Saiba mais sobre escopos

    Para mais informações sobre escopos, consulte os seguintes documentos: