Criar e gerenciar escopos de registro

bookmark_border Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Este documento descreve como criar e gerenciar escopos de registro, que podem ser usados para encontrar de forma eficiente as entradas de registro que você quer visualizar ou analisar. Se você só quer visualizar e analisar as entradas de registro que originam em um projeto, uma pasta ou uma organização, este documento não é para você. No entanto, se você usa coletores de registros para rotear registros para outros projetos ou para buckets de registro definidos pelo usuário, ou se você usa visualizações de registro, as informações neste documento podem ajudar a encontrar entradas de registro específicas de maneira eficiente.

Este documento não descreve como conferir seus registros. Para saber mais sobre esse assunto, consulte Conferir registros usando o Explorador de registros.

Sobre os escopos de registro

Os escopos de registro são recursos persistentes no nível do projeto que listam um conjunto de recursos. Esses recursos podem ser projetos, pastas, organizações e visualizações de registro. Por exemplo, é possível definir um escopo de registro que liste os projetos que contêm recursos usados para produção ou que liste as visualizações de registro que incluem entradas de registro para um tipo de recurso específico.

Quando você cria um projeto, uma pasta ou um recurso de organização do Google Cloud, o Logging cria um escopo de registro chamado _Default. Esse escopo inclui o projeto, a pasta ou a organização que foi criado. Quando o recurso pesquisado é um projeto, uma pasta ou uma organização do Google Cloud, os resultados incluem as entradas de registro que se originam no recurso e são armazenadas em um bucket de registro. Quando um projeto é pesquisado, os resultados também incluem entradas de registro que são roteadas para o projeto por um coletor em outro projeto e armazenadas em um bucket de registro.

Você pode criar escopos de registro. Também é possível editar e excluir os escopos de registro criados. No entanto, não é possível editar ou excluir o escopo de registro com o nome _Default.

Você usa um escopo de registro para controlar quais recursos a página do Explorador de registros pesquisa para dados de registro. Quando você abre essa página e seleciona um escopo de registro, ela pesquisa os recursos listados nesse escopo e atualiza a exibição.

Também é possível usar um escopo de registro para controlar quais recursos um painel de registros procura para dados de registro. Um painel de registros é um widget de painel personalizado que mostra dados de registro. Cada painel de registros tem a própria configuração, que permite criar um painel com vários painéis de registros em que cada painel exibe dados de registro diferentes. Para mais informações, consulte Exibir registros e erros em um painel personalizado.

Para projetos, o escopo de registro padrão determina o conjunto de recursos que a página Análise de registros pesquisa quando é aberta. No entanto, seus papéis de gerenciamento de identidade e acesso (IAM) nos recursos pesquisados e a configuração do período determinam quais entradas de registro são extraídas do armazenamento. Quando os projetos são criados, o escopo de registro chamado _Default é designado como o escopo de registro padrão. É possível definir qual escopo de registro é o padrão.

Diferenças entre os escopos de registro e o armazenamento centralizado de registros

O armazenamento de registros centralizado e os escopos de registro oferecem uma maneira de acessar dados de registro originados em projetos diferentes.

Quando você configura um bucket de registro centralizado, as entradas de registro são recebidas por Google Cloude roteadas para um único local de armazenamento. O armazenamento centralizado oferece um único local para consultar dados de registro, o que simplifica as consultas quando você está procurando tendências ou investigando problemas. Do ponto de vista da segurança, você também tem um local de armazenamento, o que pode simplificar as tarefas dos analistas de segurança.

Quando uma consulta é emitida para os recursos listados em um escopo de registro, os resultados de consultas individuais são combinados. Um escopo de registro facilita a agregação de dados de registro no momento da leitura, que podem ser armazenados em locais diferentes. No entanto, um escopo de registro também pode ser usado para fornecer acesso de leitura a uma ou mais visualizações de registro em um bucket de registro centralizado.

Quando a página Análise de registros é aberta, ela emite consultas aos recursos listados no escopo de registro padrão. Portanto, configure o escopo padrão para que a página mostre os dados que você geralmente quer ver. Por exemplo, você pode definir o escopo de registro padrão para listar uma visualização de registro, que, quando consultada, retorna os dados de registro de um aplicativo do App Hub.

Práticas recomendadas

Como os escopos de registro oferecem uma maneira de definir e salvar uma configuração para uso futuro, recomendamos que você crie escopos de registro para configurações de pesquisa complexas.

Por exemplo, suponha que você esteja solucionando um problema e queira conferir as entradas de registro de todas as instâncias de máquina virtual (VM) da sua equipe. Para isso, faça o seguinte:

1. Você determina que as entradas de registro que você quer acessar estão armazenadas em vários buckets de registro e em vários projetos. Na maioria dos buckets de registro, existe uma visualização de registro que inclui as entradas que você quer analisar. Se uma visualização de registro não existir, você pode criar uma.

2. Você decide criar um escopo de registro porque espera ter uma tarefa de solução de problemas semelhante no futuro.

3. Abra a página Análise de registros no console do Google Cloud e use o menu Refine scope para selecionar o novo escopo de registro.

4. Você analisa as entradas de registro e encontra as informações necessárias para resolver o problema que estava investigando.

5. Depois de resolver o problema, você compartilha a causa da falha com seus colegas. Você também compartilha que espera falhas semelhantes no futuro. Por isso, criou um escopo de registro que permite que você ou qualquer pessoa que esteja investigando a falha encontre rapidamente as entradas de registro relevantes.

Aplicativos do App Hub e escopos de registro

Seus aplicativos do App Hub podem gravar dados de registro em vários projetos. Os dados de registro podem ser armazenados no projeto em que são originados ou um administrador da organização pode ter configurado o armazenamento centralizado. Para conferir os dados de registro do aplicativo, no projeto do host do App Hub, crie um escopo de registro e configure-o para listar os projetos ou visualizações de registro que armazenam os dados de registro do aplicativo. Recomendamos que você defina o escopo de registro personalizado como o padrão. Depois de concluir essas etapas, a página Logs Explorer vai mostrar automaticamente os dados gravados pelo aplicativo, mesmo que eles estejam armazenados em projetos diferentes ou em um bucket de registros centralizado.

Limitações

• Não é possível excluir ou modificar o escopo de registro com o nome _Default.
• Somente projetos do Google Cloud oferecem suporte a um escopo de registro padrão.
• Não é possível adicionar pastas ou organizações a um escopo de registro definido pelo usuário.
• Os escopos de registro são criados no local global.

Antes de começar

• Para receber as permissões necessárias para criar e visualizar escopos de registro e definir o escopo de registro padrão, peça ao administrador para conceder a você os seguintes papéis do IAM:

  • Para criar e conferir os escopos de registro ou receber o escopo de registro padrão: Gravador de configuração de registros (roles/logging.configWriter) no projeto, na pasta ou na organização
  • Para definir ou conferir o escopo de registro padrão: Editor de observabilidade (roles/observability.editor) no projeto, na pasta ou na organização

  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 os escopos de registro e definir o escopo de registro padrão. 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 de registro e definir o escopo de registro padrão:

  • Para definir o escopo de registro padrão: observability.scopes.{get, update}
  • Para criar e gerenciar escopos de registro: logging.logScopes.{create, delete, get, list, update}

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

• Select the tab for how you plan to use the samples on this page:

  Consolegcloud

  When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

  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.

  Terraform

  Para usar os exemplos do Terraform nesta página em um ambiente de desenvolvimento local, instale e inicialize a gcloud CLI e, em seguida, configure o Application Default Credentials com suas credenciais de usuário.

  1. Install the Google Cloud CLI.

  2. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  3. To initialize the gcloud CLI, run the following command:

     gcloud init

  4. If you're using a local shell, then create local authentication credentials for your user account:

     gcloud auth application-default login

     You don't need to do this if you're using Cloud Shell.

     If an authentication error is returned, confirm that you have configured the gcloud CLI to use Workforce Identity Federation.

  Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local na documentação de autenticação do Google Cloud.

  REST

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

  After installing the Google Cloud CLI, initialize it by running the following command:

  gcloud init

  If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  Para mais informações, consulte Autenticar para usar REST na documentação de autenticação do Google Cloud.

Listar escopos de registro

 gcloud logging scopes list --project=PROJECT_ID

 gcloud logging scopes describe LOG_SCOPE --project=PROJECT_ID

Definir o escopo de registro padrão

Esta seção não se aplica a pastas ou organizações. Para pastas e organizações, quando a página Logs Explorer é aberta, ela procura as entradas de registro que se originam na pasta ou organização.

Quando um projeto é criado, um escopo de registro chamado _Default é criado. Esse escopo lista um recurso, que é seu projeto, e é designado como o escopo de registro padrão. Se você criar um projeto e não modificar o escopo de registro padrão, a página Logs Explorer vai pesquisar todas as entradas de registro que se originam no projeto quando for aberta.

Você pode criar seu próprio escopo de registro e designá-lo como o padrão. Esse recurso permite configurar quais recursos a página Análise de registros pesquisa para encontrar entradas de registro.

Criar um escopo de registro

É possível criar 100 escopos de registro por projeto. Um escopo de registro pode incluir um total de 100 visualizações e projetos de registro. No entanto, ele só pode incluir cinco projetos. Não é possível adicionar pastas ou organizações a um escopo de registro.

 gcloud logging scopes create LOG_SCOPE --project=PROJECT_ID \
   --description=DESCRIPTION \
   --resource-names=RESOURCE_NAMES

Modificar ou excluir um escopo de registro

 gcloud logging scopes update LOG_SCOPE --project=PROJECT_ID \
   --description=DESCRIPTION \
   --resource-names=RESOURCE_NAMES

 gcloud logging scopes delete LOG_SCOPE --project=PROJECT_ID

A seguir

• Ver registros usando o Explorador de registros
• Configurar visualizações de registros em um bucket de registro