Configurar escopos de observabilidade para consultas de vários projetos

Neste documento, descrevemos como criar gráficos ou visualizar dados de registro quando eles estão armazenados em vários projetos. Por padrão, apenas os dados que se originam 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 projeto doGoogle Cloud , não será necessário realizar nenhuma configuração.

Os escopos fornecem agregação em tempo de leitura

Os escopos permitem que as ferramentas de visualização e análise realizem 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 dependem de escopos para determinar onde pesquisar dados.

Os dados de métricas e de trace são sempre armazenados no projeto do Google Cloud em que os dados se originam. Para visualizar 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, ao criar um gráfico ou uma política de alertas, a consulta emitida por esses serviços vai retornar automaticamente os dados de métricas dos projetos listados. O comportamento é semelhante para dados de trace.

Por padrão, os dados de registro são armazenados no projeto, na conta de faturamento, na pasta ou na organização do Google Cloud em que os dados se originam. 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 registro personalizado. Recomendamos que o escopo do registro liste visualizações de registro em vez de projetos. Uma visualização de registro fornece 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, configure a visualização de registro para incluir a visualização _Default/_AllLogs de cada um desses projetos.

Como os escopos são usados pelo Google Cloud Observability

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

Exemplos:

  • Quando a página Análise de registros é aberta, o sistema consulta os recursos listados no escopo do registro padrão para dados de registro. Depois que essa página for aberta, use uma opção da barra de ferramentas para consultar os recursos em um escopo diferente.
  • Quando a página Explorador de traces é aberta, o sistema consulta os projetos listados no escopo de trace padrão para dados de trace. Depois que essa página for aberta, use uma opção da barra de ferramentas para consultar os recursos em um escopo diferente.
  • Quando você cria 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 um alerta deve ser criado.
  • Ao criar um gráfico usando a página do Metrics Explorer, você especifica uma métrica para o gráfico. O Monitoring consulta os projetos listados nas métricas de escopo para dados de métricas e, em seguida, exibe 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 registro especificar um projeto para o qual você não recebeu permissões para ler dados de registro, uma consulta a esse projeto não retornará dados.

O Monitoring verifica seu papel do IAM no projeto em que 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 exibem automaticamente os dados de métricas dos três projetos.

Escopos do Google Cloud Observability

Nesta seção, descrevemos os escopos usados pelo Google Cloud Observability.

Escopo de observabilidade

O escopo de observabilidade especifica o escopo do registro padrão e o escopo de trace padrão. Páginas como a Análise de registros e o Explorador de traces 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 trace em três projetos. É possível configurar a página do Explorador de traces 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 Análise de registros consulta seu projeto em busca de dados de registro.
  • A página Explorador de trace consulta seu projeto em busca de dados de trace.

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

Quando configurar o escopo de observabilidade

Configure o escopo de observabilidade nos seguintes cenários:

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

  • Você cria um escopo de trace personalizado e quer que os projetos listados nesse escopo 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 registro

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

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

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

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

Se você não configurar um escopo de registro personalizado, a página Análise de registros vai consultar seu projeto em busca de dados de registro.

Quando criar escopos de registro personalizados

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

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

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

Práticas recomendadas ao configurar escopos de registro

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

Limites associados aos escopos de registro

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

Para mais informações, consulte Criar e gerenciar escopos do registro.

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 gráficos, como o Metrics Explorer, emitem consultas para os projetos listados nas métricas de escopo.

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

Quando configurar os escopos de métricas

Configure o escopo de métricas quando qualquer uma das seguintes condições for verdadeira:

  • Você quer criar gráficos com dados armazenados em projetos diferentes.
  • Você quer que uma política de alertas monitore os dados armazenados em projetos diferentes.
  • Registre aplicativos com o App Hub. Para informações sobre esse cenário, consulte Aplicativos do App Hub e escopos de métricas.

Limites associados a escopos de métricas

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

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

Escopos de trace

A página Explorador de traces usa escopos do Trace. Quando essa página é aberta, o sistema consulta automaticamente as visualizações listadas no escopo de trace padrão para dados de trace. Essa 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 a visualização _AllSpans do projeto no conjunto de dados padrão para seus dados de trace.

Um escopo de trace lista visualizações, não Google Cloud projetos. Embora você selecione projetos ao configurar um escopo de trace, o sistema adiciona ao escopo a visualização de trace padrão desses projetos. A visualização de trace padrão de um projeto corresponde à visualização com o caminho _Trace/Spans/_AllSpans, em que os campos _Trace, Spans e _AllSpans se referem a um bucket, conjunto de dados e visualização de observabilidade. O conjunto de dados Spans armazena seus dados de trace.

Quando criar escopos de trace personalizados

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

Práticas recomendadas ao configurar escopos de trace

Limites associados a escopos de trace

Descrição Valor máximo
Número de escopos de trace por projeto 100
Número de visualizações por escopo de trace 20

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

Configurar o escopo de observabilidade

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

Para dados de registro e trace, os papéis do Identity and Access Management (IAM) no projeto que você está visualizando, bem como os projetos e as visualizações de registro pesquisados, afetam os dados retornados pela consulta. Se você emitir uma consulta para visualizar dados de registro que não tem permissão para acessar, a consulta não vai retornar nenhum dado de registro.

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 que permite visualizar dados de métricas em um projeto, ele pode visualizar os dados de métricas disponíveis para o projeto.

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

Antes de começar

Configure o projeto, os papéis do IAM e selecione a interface que você planeja usar.

Configurar o projeto e os papéis

  1. Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloudagora, crie uma conta para avaliar o desempenho dos nossos produtos em situações reais. Clientes novos também recebem US $300 em créditos para executar, testar e implantar cargas de trabalho sem custos financeiros.

  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 role (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, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). 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 role (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, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

    8.

  8. Para receber 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 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 acessar 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:

    • logging.logScopes.{create, delete, get, list, update}
    • monitoring.metricsscopes.{link, get, list}
    • observability.traceScopes.{create, delete, get, list, update}
    • observability.scopes.{get, update}

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

Selecione a interface que você quer usar

Console

Quando você usa o console do Google Cloud para acessar os serviços e as APIs do Google Cloud , não é necessário configurar a autenticação.

gcloud

No console do Google Cloud , ative o Cloud Shell.

Ativar o Cloud Shell

Na parte inferior do console do Google Cloud , uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a CLI do Google Cloud já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.

REST

Para usar as amostras da API REST desta página em um ambiente de desenvolvimento local, use as credenciais fornecidas para a CLI gcloud.

    Instale a CLI do Google Cloud.

    Ao usar um provedor de identidade (IdP) externo, primeiro faça login na CLI gcloud com sua identidade federada.

Saiba mais em 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 do registro padrão, o métricas de escopo e o escopo de trace padrão:

  1. No console do Google Cloud , 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 do Google Cloud , selecione seu projeto do Google Cloud . Para configurações do App Hub, selecione o projeto host ou de gerenciamento do App Hub.

  3. Configure o escopo do registro padrão:

    1. Selecione a guia Escopos de registro.

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

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

  4. Configure o escopo de métricas:

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

  5. Configure o escopo de trace padrão:

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

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

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

gcloud

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

  1. Para ver 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. Este 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, é possível incluir a flag --log-scope, a flag --trace-scope ou ambas.

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

    • OBSERVABILITY_SCOPE_ID: o nome de um objeto Scope. Este valor precisa ser definido como _Default.
    • LOG_SCOPE_FQN_ID: o nome totalmente qualificado do recurso do escopo do 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 do registro. Por exemplo, my-scope.

    • TRACE_SCOPE_FQN_ID: o nome totalmente qualificado do recurso do escopo do trace. Esse campo tem o seguinte formato: 
      projects/PROJECT_ID/locations/LOCATION/traceScopes/TRACE_SCOPE_NAME

      Na expressão anterior, TRACE_SCOPE_NAME é o nome do escopo do trace. Por exemplo, my-trace-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\
   --trace-scope=TRACE_SCOPE_FQN_ID\
   --location=LOCATION\
   --project=PROJECT_ID

    Windows (PowerShell)

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

    Windows (cmd.exe)

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

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

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

REST

Para acessar e definir o escopo do registro padrão ou o escopo de trace padrão usando uma chamada de API, configure o escopo de observabilidade. O escopo de observabilidade lista o escopo do registro padrão e o escopo de trace 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 do registro padrão e o escopo de trace padrão.
  • Para atualizar o escopo de observabilidade padrão de um projeto, envie uma solicitação para o 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 são alterados. A resposta é um objeto Scope.

O parâmetro de caminho para os dois 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 ou de gerenciamento do App Hub.
  • 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 do registro padrão e o escopo de trace 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 ver 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 nome: 
        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.

    O resultado parecido com este:

        {
    "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: