Criar e gerenciar escopos de registro

Neste documento, descrevemos como criar e gerenciar escopos de registros, que podem ser usados para encontrar com eficiência as entradas de registro que você quer visualizar ou analisar. Se você quiser apenas ver e analisar as entradas de registro que se 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 registros, as informações neste documento podem ajudar você a encontrar entradas de registro específicas com eficiência.

Este documento não descreve como visualizar seus registros. Para mais informações sobre esse assunto, consulte Ver registros usando o Explorador de registros.

Sobre escopos de registros

Os escopos de registros 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 registros. Por exemplo, é possível definir um escopo de registro que liste os projetos que contêm recursos usados para produção ou um que liste as visualizações de registros que incluem entradas de registro para um tipo de recurso específico.

Quando você cria um recurso de projeto, pasta ou organização do Trusted Cloud , o Logging cria um escopo de registros chamado _Default. Esse escopo inclui o projeto, a pasta ou a organização que foi criada. Quando um recurso pesquisado é um projeto, uma pasta ou uma organização do Trusted Cloud , os resultados incluem as entradas de registro originadas no recurso e armazenadas em um bucket de registros. O bucket de registros pode estar em qualquer projeto. 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.

É possível criar escopos de registros. Também é possível editar e excluir os escopos de registro que você cria. No entanto, não é possível editar ou excluir o escopo de registro chamado _Default.

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

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, suas funções do Identity and Access Management (IAM) nos recursos pesquisados e a configuração de período determinam quais entradas de registro são buscadas do armazenamento. Quando os projetos são criados, o escopo de registros chamado _Default é designado como o padrão.

Como os escopos de registros são diferentes do armazenamento centralizado de registros

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

Ao centralizar o armazenamento de registros, você configura os coletores em uma organização ou pasta para encaminhar entradas de registro a um único local de armazenamento. O armazenamento centralizado oferece um único lugar para consultar dados de registro, o que simplifica suas consultas ao pesquisar tendências ou investigar problemas. Do ponto de vista da segurança, você também tem um local de armazenamento, o que simplifica as tarefas dos seus analistas de segurança.

Quando uma consulta é emitida para os recursos listados em um escopo de registros, os resultados individuais são combinados. Um escopo de registro facilita a agregação de dados de registro em tempo de 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 registros centralizado.

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

Práticas recomendadas

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

Por exemplo, suponha que você esteja resolvendo um problema e queira ver as entradas de registro de todas as instâncias de máquina virtual (VM) pertencentes à sua equipe. Para realizar essa tarefa, faça o seguinte:

  1. Você determina que as entradas de registro que quer ver estão armazenadas em vários buckets e projetos. Para a maioria dos buckets de registros, existe uma visualização que inclui as entradas que você quer analisar. Se não houver uma visualização de registros, você poderá criar uma.

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

  3. Abra a página Explorador de registros no console do Trusted Cloud e use o menu Refinar escopo para selecionar o novo escopo de registros.

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

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

Aplicativos e escopos de registros do App Hub

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 foram gerados ou um administrador da organização pode ter configurado o armazenamento centralizado. Para ver os dados de registro do seu aplicativo, crie um escopo de registros, configure para listar os projetos ou visualizações de registros que armazenam os dados de registro do aplicativo e, em seguida, configure como o escopo de registros padrão. Quando você conclui essas etapas, a página do Explorador de registros mostra automaticamente os dados gravados pelo aplicativo, mesmo que eles estejam armazenados em projetos diferentes ou em um bucket de registros centralizado.

Crie o escopo de registro personalizado no projeto em que você vai ver os dados de registro. Esse projeto é o host do App Hub ou o projeto de gerenciamento da sua pasta habilitada para gerenciar apps. Por exemplo, se o nome de exibição da pasta for My Folder, o nome de exibição do projeto de gerenciamento será My Folder-mp.

Limitações

  • Não é possível excluir ou modificar o escopo de registro chamado _Default.
  • Apenas projetos Trusted Cloud são compatíveis com um escopo de registros padrão.
  • Não é possível adicionar pastas ou organizações a um escopo de registros definido pelo usuário.
  • Os escopos de registros são criados no local global.

Antes de começar

Listar escopos de registros

gcloud

Para listar os escopos de registros 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 configurações do App Hub, selecione o projeto host do App Hub ou o projeto de gerenciamento da pasta com app ativado.

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

 gcloud logging scopes describe LOG_SCOPE_ID --project=PROJECT_ID

Antes de executar o comando, atualize os seguintes campos:

  • PROJECT_ID: o identificador do projeto.
  • LOG_SCOPE_ID: o ID do escopo de registro. Por exemplo, my-scope.

Terraform

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

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 Trusted Cloud , use os seguintes comandos:

Nos comandos anteriores, o campo parent tem a seguinte sintaxe:

projects/PROJECT_ID/locations/LOCATION_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_ID precisa ser definido como global.

Criar um escopo de registro

É possível criar 100 escopos de registros por projeto. Um escopo de registro pode incluir um total de 100 visualizações de registro e projetos, mas apenas 5 projetos. Não é possível adicionar pastas ou organizações a um escopo de registros.

gcloud

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

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

Antes de executar o comando, atualize os seguintes campos:

  • 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.
  • LOG_SCOPE_ID: o ID do escopo de registro. Por exemplo, my-scope.

  • DESCRIPTION: opcional. A descrição do escopo de 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 registros. Por exemplo, para incluir my-project no escopo de registros, 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 registros em um projeto, pasta ou organização usando o Terraform, use o recurso google_logging_log_scope.

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 Trusted Cloud . Para configurações do App Hub, selecione o projeto host do App Hub ou o projeto de gerenciamento da pasta com app ativado.
  • 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_ID"

    Na expressão anterior, LOG_SCOPE_ID é o nome de um escopo de registro, como "production".

  • resource_names: uma matriz de projetos e visualizações de registros, em que cada projeto e visualização de registros é 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 permite criar escopos de registros em uma pasta ou organização. Para mais informações, consulte a documentação de referência da API.

Para projetos Trusted Cloud , use o seguinte comando:

Nos comandos anteriores, o campo parent tem a seguinte sintaxe:

projects/PROJECT_ID/locations/LOCATION_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_ID precisa ser definido como global.

Modificar ou excluir um escopo de registros

gcloud

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

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

Antes de executar o comando, atualize os seguintes campos:

  • 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.
  • LOG_SCOPE_ID: o ID do escopo de 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 de registro.

  • RESOURCE_NAMES: uma lista separada por vírgulas dos nomes totalmente qualificados de projetos ou visualizações de registros. Omita esse campo quando não quiser mudar a lista de recursos.

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

 gcloud logging scopes delete LOG_SCOPE_ID --project=PROJECT_ID

Antes de executar o comando, atualize os seguintes campos:

  • 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.
  • LOG_SCOPE_ID: o ID do escopo de 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 registros em um projeto, pasta ou organização usando o Terraform, use o recurso do Terraform google_logging_log_scope.

REST

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

Para projetos Trusted Cloud , use os seguintes comandos:

Nos comandos anteriores, o campo parent tem a seguinte sintaxe:

projects/PROJECT_ID/locations/LOCATION_ID/logScopes/LOG_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_ID precisa ser definido como global.
  • LOG_SCOPE_ID: o ID do escopo de registro. Por exemplo, my-scope.

A seguir