Esta página foi traduzida pela API Cloud Translation.

Criar e gerenciar escopos de registro

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 visualizar 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 registros. 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 registros.

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 da Análise 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 do Identity and Access Management (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.

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:

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. Para a maioria dos buckets de registro, existe uma visualização de registro que inclui as entradas de registro que você quer analisar. Se uma visualização de registro não existir, você pode criar uma.
Você decide criar um escopo de registro porque espera ter uma tarefa de solução de problemas semelhante no futuro.
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.
Você analisa as entradas de registro e encontra as informações necessárias para resolver o problema que estava investigando.
Depois de resolver o problema, você compartilha a causa da falha com seus colegas. Você também compartilha que espera ver 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.

Limitações

Não é possível excluir ou modificar o escopo de registro chamado _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 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 receber e definir o escopo de registro padrão: observability.scopes.{get, 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:
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.
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. To initialize the gcloud CLI, run the following command:
  
  gcloud init
3. 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.
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.
Para mais informações, consulte Autenticar para usar REST na documentação de autenticação do Google Cloud.

Listar escopos de registro

Console

Para listar os escopos de registro, faça o seguinte:

No console do Google Cloud, abra 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 Monitoramento.
Selecione a guia Log Scopes.

A tabela lista seus escopos de registro. Quando você seleciona um projeto do Google Cloud, uma entrada na tabela é mostrada com um ícone "Padrão", , que indica que esse escopo de registro lista os recursos que o Logs Explorer pesquisa quando essa página é aberta.

gcloud

Para listar os escopos de registro em um projeto, use o comando gcloud logging scopes list:

 gcloud logging scopes list --project=PROJECT_ID

Antes de executar o comando, atualize os seguintes campos:

PROJECT_ID: o identificador do projeto.

Para conferir os detalhes de um escopo de registro em um projeto, use o comando gcloud logging scopes describe:

 gcloud logging scopes describe LOG_SCOPE --project=PROJECT_ID

Antes de executar o comando, atualize os seguintes campos:

PROJECT_ID: o identificador do projeto.
LOG_SCOPE: o nome do escopo do registro. Por exemplo, my-scope.

Terraform

É possível usar o Terraform para criar e modificar um escopo de registro. No entanto, não é possível usar o Terraform para listar os escopos de registro.

REST

A API Cloud Logging contém comandos que listam os escopos de registro em um recurso ou que informam os detalhes de um escopo de registro específico. Para uma lista completa de comandos, consulte a documentação de referência da API.

Para projetos do Google Cloud, use os seguintes comandos:

No comando da API, defina o campo locations como global.

Definir o escopo de registro padrão

O escopo de registro padrão lista os recursos pesquisados pela página Análise de registros quando ela é aberta. Se um escopo de registro padrão não existir ou não for acessível, essa página vai pesquisar automaticamente entradas de registro que se originam do projeto, da pasta ou da organização selecionada. As entradas de registro exibidas pela página Logs Explorer dependem dos recursos pesquisados, da configuração do período e das suas funções do IAM nos recursos pesquisados.

Quando os projetos são criados, o escopo de registro com o nome _Default é criado e designado como o escopo de registro padrão. No entanto, você pode criar seu próprio escopo de registro e designá-lo como o escopo de registro padrão.

Console

Para definir o escopo de registro padrão, faça o seguinte:

No console do Google Cloud, abra 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 Monitoramento.
Selecione a guia Log Scopes.
Encontre o escopo de registro que você quer designar como padrão, clique em Mais e selecione Definir como padrão.

O escopo de registro selecionado é mostrado com um ícone "Padrão", .

gcloud

Incompatível.

Terraform

É possível usar o Terraform para criar e modificar um escopo de registro. No entanto, não é possível usar o Terraform para definir o escopo de registro padrão.

REST

Incompatível.

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.

Console

Para criar um escopo de registro, faça o seguinte:

No console do Google Cloud, abra 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 Monitoramento.
Selecione a guia Log scopes e clique em Create log scope.
Para adicionar um ou mais projetos, clique em Adicionar projetos e preencha a caixa de diálogo.

Depois de adicionar um projeto, suas funções do IAM nesse projeto determinam quais entradas de registro você pode visualizar. Por exemplo, sua função do IAM pode permitir que você visualize apenas as entradas de registro que são acessíveis por uma visualização de registro específica em um bucket de registros. Para mais informações sobre papéis, consulte Registro de papéis.
Para adicionar uma ou mais visualizações de registro, clique em Adicionar visualizações de registro e preencha a caixa de diálogo.

A caixa de diálogo lista todas as visualizações de registro que têm entradas de registro originadas no projeto atual ou que foram roteadas para o projeto atual por um sink em outro projeto. Por exemplo, se você não tiver configurado nenhum coletor, essa caixa de diálogo vai listar as visualizações de registro no seu projeto atual.

Para listar as visualizações de registro armazenadas em outro projeto do Google Cloud, clique em Import project e selecione o projeto do Google Cloud.

Depois de adicionar uma visualização de registro, suas funções do IAM na visualização de registro ou no projeto que armazena a visualização de registro determinam quais entradas de registro você pode acessar. Para mais informações, consulte Controlar o acesso a uma visualização de registro.
Na seção Nome do escopo de registro, insira o nome e a descrição que você quer que apareçam na guia Escopos de registro.

O nome de um escopo de registro não pode ser modificado e precisa ser exclusivo no projeto.
Clique em Criar escopo de registro.

gcloud

Para criar um escopo de registro em um projeto, use o comando gcloud logging scopes create:

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

Antes de executar o comando, atualize os seguintes campos:

PROJECT_ID: o identificador do projeto.
LOG_SCOPE: o nome do escopo do registro. Por exemplo, my-scope.
DESCRIPTION: opcional. A descrição do escopo do registro. Formate a descrição como uma string.
RESOURCE_NAMES: uma lista separada por vírgulas dos nomes totalmente qualificados de projetos ou visualizações de registro. Por exemplo, para incluir my-project no escopo do registro, especifique projects/my-project.

Terraform

Para saber como aplicar ou remover uma configuração do Terraform, consulte Comandos básicos do Terraform. Para mais informações, consulte a documentação de referência do provedor Terraform.

Para criar um escopo de registro em um projeto, pasta ou organização usando o Terraform, use o recurso google_logging_log_scope do Terraform.

No comando, defina os seguintes campos:

parent: o nome completo do projeto, da pasta ou da organização. Por exemplo, você pode definir esse campo como "projects/PROJECT_ID", em que PROJECT_ID é o ID do seu projeto do Google Cloud.
Defina locations como "global".
name: definido como o nome totalmente qualificado do escopo de registro. Para projetos, o formato desse campo é:
```
"projects/PROJECT_ID/locations/global/logScopes/LOG_SCOPE"
```
Na expressão anterior, LOG_SCOPE é o nome de um escopo de registro, como "produção".
resource_names: uma matriz de projetos e visualizações de registro, em que cada projeto e visualização de registro é especificado usando o nome totalmente qualificado.
description: uma breve descrição. Por exemplo, "Escopo para recursos de produção".

REST

A API Cloud Logging também oferece suporte à criação de escopos de registro em uma pasta ou organização. Para mais informações, consulte a documentação de referência da API.

Para projetos do Google Cloud, use o seguinte comando:

projects.locations.logScopes.create.

No comando da API, defina o campo locations como global.

Modificar ou excluir um escopo de registro

Console

Para modificar ou excluir um escopo de registro que você ou um colega criou, faça o seguinte:

No console do Google Cloud, abra 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 Monitoramento.
Selecione a guia Log Scopes.
Encontre os Log Scopes que você quer modificar ou excluir, clique em Mais e faça um destes procedimentos:
- Para modificar, selecione Editar escopo e preencha a caixa de diálogo.
- Para excluir, selecione Excluir escopo e preencha a caixa de diálogo.

gcloud

Para modificar a descrição da lista de recursos em um escopo de registro em um projeto, use o comando gcloud logging scopes update:

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

Antes de executar o comando, atualize os seguintes campos:

PROJECT_ID: o identificador do projeto.
LOG_SCOPE: o nome do escopo do registro. Por exemplo, my-scope.
DESCRIPTION: a descrição do escopo do registro. Formate a descrição como uma string. Omita esse campo quando não quiser mudar a descrição do escopo do registro.
RESOURCE_NAMES: uma lista separada por vírgulas dos nomes totalmente qualificados de projetos ou visualizações de registro. Omita esse campo quando não quiser mudar a lista de recursos.

Para excluir um escopo de registro em um projeto, use o comando gcloud logging scopes delete:

 gcloud logging scopes delete LOG_SCOPE --project=PROJECT_ID

Antes de executar o comando, atualize os seguintes campos:

PROJECT_ID: o identificador do projeto.
LOG_SCOPE: o nome do escopo do registro. Por exemplo, my-scope.

Terraform

Para saber como aplicar ou remover uma configuração do Terraform, consulte Comandos básicos do Terraform. Para mais informações, consulte a documentação de referência do provedor Terraform.

Para modificar um escopo de registro em um projeto, pasta ou organização usando o Terraform, use o recurso google_logging_log_scope do Terraform.

REST

A API Cloud Logging contém comandos que podem modificar ou excluir um escopo de registro. Para uma lista completa de comandos, consulte a documentação de referência da API.

Para projetos do Google Cloud, use os seguintes comandos:

No comando da API, defina o campo locations como global.

Criar e gerenciar escopos de registro

Sobre os escopos de registro

Práticas recomendadas

Limitações

Antes de começar

Permissões necessárias

Console

gcloud

Terraform

REST

Listar escopos de registro

Console

gcloud

Terraform

REST

Definir o escopo de registro padrão

Console

gcloud

Terraform

REST

Criar um escopo de registro

Console

gcloud

Terraform

REST

Modificar ou excluir um escopo de registro

Console

gcloud

Terraform

REST

A seguir