Configure âmbitos de observabilidade para consultas de vários projetos

Este documento descreve como pode criar gráficos ou ver dados de registo quando esses dados são armazenados em vários projetos. Por predefinição, apenas os dados originados num projeto estão disponíveis para as ferramentas de visualização. No entanto, se configurar um âmbito, as ferramentas de visualização e análise podem consultar dados armazenados em vários projetos.

Se quiser apenas monitorizar ou ver dados armazenados num Google Cloud projeto, não tem de fazer nenhuma configuração.

Os âmbitos fornecem agregação em tempo de leitura

Os âmbitos permitem que as ferramentas de visualização e análise realizem a agregação em tempo de leitura dos dados armazenados em várias localizações. Os âmbitos não controlam onde os dados são armazenados. Em vez disso, os motores de consulta baseiam-se em âmbitos para determinar onde pesquisar dados.

Os dados de métricas e rastreios são sempre armazenados no Google Cloud projeto onde os dados têm origem. Para ver dados de métricas armazenados em vários projetos num único gráfico, configure um âmbito de métricas para listar esses projetos. Depois de configurar este âmbito, quando cria um gráfico ou uma política de alerta, a consulta emitida por estes serviços devolve automaticamente dados de métricas dos projetos indicados. O comportamento é semelhante para os dados de rastreio.

Por predefinição, os dados de registo são armazenados no Google Cloud projeto, na conta de faturação, na pasta ou na organização onde os dados têm origem. No entanto, pode configurar o Logging para encaminhar dados de registo do recurso de origem para outra localização, como outro projeto ou um contentor de registos centralizado. Em todos os casos, configure um âmbito de registo personalizado. Recomendamos que o âmbito dos registos liste vistas de registos em vez de projetos; uma vista de registos fornece acesso de leitura a um subconjunto de entradas de registos num contentor de registos. Por exemplo, se tiver dados de registo armazenados em três projetos, pode configurar a visualização de registos para incluir a visualização _Default/_AllLogs para cada um desses projetos.

Como os âmbitos são usados pela Google Cloud Observability

As ferramentas de análise e visualização do Google Cloud Observability baseiam-se em âmbitos específicos do tipo de dados para determinar que recursos consultar para os dados que a ferramenta deve apresentar ou analisar.

Exemplos:

  • Quando a página do Explorador de registos é aberta, o sistema consulta os recursos indicados no âmbito do registo predefinido para obter dados de registo. Depois de abrir esta página, pode usar uma opção da barra de ferramentas para consultar os recursos num âmbito diferente.
  • Quando a página Trace Explorer é aberta, o sistema consulta os projetos indicados no âmbito do rastreio predefinido para dados de rastreio. Depois de abrir esta página, pode usar uma opção da barra de ferramentas para consultar os recursos num âmbito diferente.
  • Quando cria uma política de alertas, o Monitoring consulta os projetos indicados no âmbito das métricas para obter dados de métricas. Em seguida, analisa a resposta à consulta e determina se deve criar um incidente.
  • Quando cria um gráfico através da página Explorador de métricas, especifica uma métrica para representar graficamente. Monitorizar consultas aos projetos listados no âmbito das métricas para dados de métricas e, em seguida, apresentar os resultados da consulta.

O registo e o rastreio validam as suas funções de gestão de identidade e de acesso (IAM) num recurso antes de uma consulta devolver dados. Por exemplo, se um âmbito de registo especificar um projeto para o qual não lhe foram concedidas as autorizações para ler dados de registo, uma consulta a esse projeto não devolve dados.

A monitorização valida a sua função de IAM no projeto a partir do qual a consulta é emitida. Suponhamos que o âmbito das métricas de um projeto denominado AllEnv apresenta os seguintes projetos: AllEnv, Prod e Staging. Além disso, parta do princípio de que lhe foi atribuída a função de leitor do Monitoring no projeto AllEnv. Os gráficos que cria com a página Explorador de métricas quando usa o projeto AllEnv apresentam automaticamente dados de métricas para os três projetos.

Âmbitos da observabilidade do Google Cloud

Esta secção descreve os âmbitos usados pelo Google Cloud Observability.

Âmbito da observabilidade

O âmbito de observabilidade especifica o âmbito de registo predefinido e o âmbito de rastreio predefinido. As páginas como o Explorador de registos e o Explorador de rastreios usam os âmbitos predefinidos para determinar que recursos consultar quando a página é aberta. Por exemplo, suponha que tem uma aplicação que gera dados de rastreio em três projetos. Pode configurar a página Explorador de rastreios para consultar automaticamente esses três projetos definindo o âmbito do rastreio predefinido.

Se não configurar o âmbito da observabilidade, ocorre o seguinte:

  • A página Explorador de registos consulta o seu projeto para obter dados de registo.
  • A página Explorador de rastreios consulta o seu projeto para obter dados de rastreio.

O âmbito de observabilidade não se aplica aos dados de métricas.

Quando configurar o âmbito de observabilidade

Configure o âmbito da observabilidade nos seguintes cenários:

  • Cria um âmbito de registo personalizado e quer que os recursos listados nesse âmbito sejam consultados por predefinição.

  • Cria um âmbito de rastreio personalizado e quer que os projetos listados nesse âmbito sejam consultados por predefinição.

Limites associados aos âmbitos de observabilidade

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

Âmbitos de registo

Os âmbitos dos registos são usados pela página Explorador de registos e pelos painéis de controlo que apresentam dados de registos:

  • Quando a página Explorador de registos é aberta, o sistema consulta automaticamente os recursos indicados no âmbito do registo predefinido para dados de registo. Esta página também oferece controlos que lhe permitem alternar entre âmbitos.

  • Para os painéis de controlo, a implementação determina se o sistema consulta o projeto ou os recursos indicados no âmbito do registo predefinido.

Um âmbito de registo pode listar vistas de registos, projetos, pastas e organizações.

Se não configurar um âmbito do registo personalizado, a página Explorador de registos consulta o seu projeto para obter dados de registo.

Quando criar âmbitos de registo personalizados

Crie âmbitos de registo personalizados para as seguintes configurações:

Em todos os casos, configure os âmbitos dos registos personalizados para listar uma ou mais vistas de registos. Essas visualizações de registos podem estar num contentor de registos centralizado ou podem ser visualizações de registos em diferentes contentores de registos. Se usar um contentor de registos centralizado, pode criar vários âmbitos de registos personalizados, cada um com o seu próprio conjunto de vistas de registos.

Se criar âmbitos de registo personalizados, pondere atualizar o âmbito de registo predefinido.

Práticas recomendadas para a configuração de âmbitos de registo

  • Inclua apenas visualizações de registos.
  • Não configure um âmbito que liste projetos e visualizações de registos.

Limites associados aos âmbitos dos registos

Descrição Valor máximo
Número de âmbitos de registo por projeto 100
Número de projetos por âmbito do registo 5
Número de visualizações de registos ou projetos por âmbito de registo 100

Para mais informações, consulte o artigo Crie e faça a gestão de âmbitos de registo.

Âmbito das métricas

O âmbito das métricas é usado por todas as consultas emitidas pelo Cloud Monitoring. Por exemplo, as políticas de alerta e as ferramentas de criação de gráficos, como o Explorador de métricas, enviam consultas de problemas para os projetos listados no âmbito das métricas.

Se não configurar o âmbito das métricas, os serviços de monitorização consultam o seu projeto para obter dados de métricas.

Quando configurar os âmbitos das métricas

Configure o âmbito das métricas quando ocorrer alguma das seguintes situações:

  • Quer criar gráficos de dados armazenados em projetos diferentes.
  • Quer uma política de alertas para monitorizar os dados armazenados em diferentes projetos.
  • Regista aplicações com o App Hub. Para obter informações acerca deste cenário, consulte Âmbitos das métricas para projetos de gestão.

Limites associados aos âmbitos das métricas

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

Para mais informações, consulte o artigo Vista geral dos âmbitos das métricas.

Âmbitos do rastreio

Os âmbitos de rastreio são usados pela página Explorador de rastreio. Quando esta página é aberta, o sistema consulta automaticamente os projetos listados no âmbito do rastreio predefinido para obter dados de rastreio. Esta página também oferece controlos que lhe permitem alternar entre âmbitos.

Se não configurar um âmbito de rastreio personalizado, a página Explorador de rastreios consulta o seu projeto para obter dados de rastreio.

Quando criar âmbitos de rastreio personalizados

Crie âmbitos de rastreio personalizados quando tiver aplicações que dependam de recursos em diferentes Google Cloud projetos.

Limites associados aos âmbitos de rastreio

Descrição Valor máximo
Número de âmbitos de rastreio por projeto 100
Número de projetos por âmbito de rastreio 20

Para mais informações, consulte o artigo Crie e faça a gestão de âmbitos de rastreio.

Configure o âmbito da observabilidade

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

Para dados de registo e rastreio, as suas funções de gestão de identidade e acesso (IAM) no projeto que está a ver e em quaisquer projetos e vistas de registos pesquisados afetam os dados devolvidos pela consulta. Se emitir uma consulta para ver dados de registo para os quais não tem autorização, a consulta não devolve dados de registo.

Para dados de métricas, quando o âmbito das métricas de um projeto é configurado, o projeto recebe acesso de leitura aos dados de métricas armazenados pelos projetos indicados no respetivo âmbito das métricas. Quando é concedida a um utilizador uma função de gestão de identidades e acessos que lhe permite ver dados de métricas num projeto, este pode ver os dados de métricas disponíveis para o projeto.

Para configurar o âmbito de observabilidade, defina o âmbito de registo predefinido e o âmbito de rastreio predefinido. O resto desta secção descreve como concluir estas 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 receber as autorizações de que precisa para criar e ver âmbitos, peça ao seu administrador que lhe conceda as seguintes funções do IAM:

    • Para criar e ver âmbitos de registo e obter o âmbito de registo predefinido: Logs Configuration Writer (roles/logging.configWriter) no seu projeto
    • Para modificar os âmbitos das métricas: Administrador de monitorização (roles/monitoring.admin) no seu projeto e em cada projeto que quer adicionar aos âmbitos das métricas
    • Para criar e ver âmbitos de rastreio, bem como obter e definir âmbitos predefinidos: 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.

    Veja e defina o âmbito predefinido

    Consola

    Para configurar o âmbito de observabilidade, configure os respetivos componentes, que são o âmbito de registo predefinido, o âmbito de métricas e o âmbito de rastreio predefinido:

    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. Configure o âmbito do registo predefinido:

      1. Selecione o separador Âmbitos de registo.

        Os âmbitos de registo existentes são apresentados. A entrada com o ícone "Predefinição", , é o âmbito do registo predefinido. Se quiser criar um âmbito do registo, clique em Criar âmbito do registo e, de seguida, conclua a caixa de diálogo. Para mais informações, consulte o artigo Crie e faça a gestão de âmbitos de registo.

      2. Encontre a entrada que quer designar como predefinição, clique em  Mais e, de seguida, selecione Definir como predefinição.

    4. Configure o âmbito das métricas:

      1. Selecione o separador Âmbito das métricas.
      2. No painel Projetos do Google Cloud, clique em Adicionar projetos e, de seguida, conclua a caixa de diálogo. Para mais informações, consulte o artigo Configure âmbitos de métricas.

    5. Configure o âmbito do rastreio predefinido:

      1. Selecione o separador Trace Scopes e, de seguida, faça o seguinte:

        São apresentados os âmbitos de rastreio existentes. A entrada com o ícone "Predefinição", , é o âmbito do rastreio predefinido. Se quiser criar um âmbito de rastreio, clique em Criar âmbito de registo e, de seguida, conclua a caixa de diálogo. Para mais informações, consulte o artigo Crie e faça a gestão de âmbitos de rastreio.

      2. Encontre a entrada que quer designar como predefinição, clique em  Mais e, de seguida, selecione Definir como predefinição.

    gcloud

    Para ver e definir o âmbito da observabilidade, faça o seguinte:

    1. Para ver as definições do âmbito de observabilidade, execute o comando gcloud observability scopes describe.

      Antes de usar qualquer um dos dados de comandos abaixo, faça as seguintes substituições:

      • OBSERVABILITY_SCOPE_ID: o nome de um objeto Scope. Este valor tem de ser definido como _Default.
      • LOCATION: o campo de localização tem de estar 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 à seguinte: 

      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 âmbito da observabilidade, execute o comando gcloud observability scopes update. No comando update, pode incluir a flag --log-scope para atualizar o âmbito do registo predefinido.

      Antes de usar qualquer um dos dados de comandos abaixo, faça as seguintes substituições:

      • OBSERVABILITY_SCOPE_ID: o nome de um objeto Scope. Este valor tem de ser definido como _Default.
      • LOG_SCOPE_FQN_ID: o ID totalmente qualificado do âmbito do registo. Este 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 âmbito do registo. Por exemplo, my-scope.

      • LOCATION: o campo de localização tem de estar 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 é semelhante à seguinte: 

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

    Saiba mais sobre os âmbitos

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