Configurar buckets de registros

Neste documento, descrevemos como criar e gerenciar buckets do Cloud Logging usando o console do Google Cloud, a Google Cloud CLI e a API Logging. Ele também fornece instruções para criar e gerenciar buckets de registros no nível do projeto do Google Cloud. Não é possível criar buckets de registros no nível da pasta ou da organização. No entanto, o Cloud Logging cria automaticamente os buckets _Default e _Required no nível da pasta e da organização para você.

É possível fazer upgrade dos buckets de registro para usar a Análise de registros. A análise de registros permite executar consultas SQL nos dados de registro, o que ajuda a resolver problemas de aplicativos, segurança e rede. Também é possível usar o BigQuery para visualizar os dados armazenados em um bucket de registros quando ele é atualizado para usar a Análise de registros e quando existe um conjunto de dados vinculado do BigQuery. A criação de um conjunto de dados vinculado permite unir os dados de registro a outros dados armazenados no BigQuery e acessar dados de outras ferramentas, como o Looker Studio e o Looker.

Para uma visão geral conceitual dos buckets, consulte Visão geral de roteamento e armazenamento: buckets de registros.

Antes de começar

Para começar a usar buckets, faça o seguinte:

• Verifique se você ativou o faturamento para o projeto do Google Cloud.

• Verifique se o papel do Identity and Access Management (IAM) concede as permissões necessárias para criar, fazer upgrade e vincular buckets.

  O papel de gravador de configuração de registros (roles/logging.configWriter) é o papel mínimo predefinido que concede as permissões necessárias para gerenciar buckets. Para a lista completa de permissões e papéis, consulte Controle de acesso com o IAM.

• Entenda os requisitos de formatação do LogBucket, incluindo as regiões compatíveis em que é possível armazenar os registros.

• Considere definir um local de recurso padrão para aplicar uma região de armazenamento padrão aos buckets _Required e _Default em sua organização.

• Para usar o BigQuery para visualizar os dados armazenados em um bucket de registros, faça o seguinte:

  • Verifique se a API BigQuery está ativada. Para verificar se a API está ativada, liste os serviços disponíveis.

  • O papel do Identity and Access Management inclui as permissões que permitem a criação de um conjunto de dados vinculado. Para mais informações, consulte Permissões para conjuntos de dados vinculados do BigQuery.

• Para informações sobre como criar um bucket de registros que usa uma chave de criptografia gerenciada pelo cliente (CMEK, na sigla em inglês), consulte Configurar CMEK para armazenamento de registros.

Criar um bucket

É possível criar no máximo 100 buckets por projeto do Google Cloud.

Para criar um bucket de registros definido pelo usuário para seu projeto do Google Cloud, faça o seguinte:

Console do Google Cloud

Para criar um bucket de registros no seu projeto do Google Cloud, faça o seguinte:

1. No console do Google Cloud, selecione Logging e Armazenamento de registros ou clique no botão a seguir:

   Acessar o armazenamento de registros

2. Clique em Criar bucket de registros.

3. Insira um Nome e uma Descrição para o bucket.

4. Opcional: faça upgrade do bucket para usar a análise de registros.

   Aviso: o upgrade de um bucket para usar a análise de registros é permanente. Não é possível fazer downgrade do bucket de registros para remover o uso da análise de registros.

   1. Selecione Fazer upgrade para usar a análise de registros.

      Ao fazer upgrade de um bucket para usar a análise de registros, é possível consultar os registros na página Análise de registros com consultas SQL. Você também pode continuar visualizando seus registros usando o Explorador de registros.

      Nem todas as regiões são compatíveis com a análise de registros. Para mais informações, consulte Regiões compatíveis.

   2. Opcional: para visualizar os registros no BigQuery, selecione Criar um novo conjunto de dados do BigQuery vinculado a este bucket e insira um nome exclusivo.

      Quando você seleciona essa opção, o BigQuery pode ler os dados armazenados no bucket de registros. Agora é possível consultar na interface do BigQuery onde é possível mesclar os dados de registro e acessar dados de outras ferramentas, como Looker Studio e Looker.

5. Opcional: para selecionar a região de armazenamento dos registros, clique no menu Selecionar região do bucket de registros e escolha uma região. Se você não selecionar uma região, a região global será usada, o que significa que os registros poderão estar fisicamente localizados em qualquer uma das regiões.

   Observação: depois de criar o bucket de registros, não será possível alterar a região. Se você precisar de um bucket em uma região diferente, crie um novo bucket nessa região, redirecione os coletores apropriados para o novo bucket e exclua o bucket antigo

6. Opcional: para definir um período de retenção personalizada para os registros no bucket, clique em Próxima.

   No campo Período de armazenamento, digite o número de dias, entre 1 dia e 3.650 dias, que você quer que o Cloud Logging retenha seus registros. Se você não personalizar o período de retenção, o padrão será 30 days.

   Também é possível atualizar seu bucket para aplicar a retenção personalizada depois de criá-lo.

7. Clique em Criar bucket.

   Depois que o bucket de registros for criado, o Logging atualizará o bucket e criará o link do conjunto de dados, se essas opções estiverem selecionadas.

   Pode levar alguns instantes para que essas etapas sejam concluídas.

gcloud

Observação: não é possível criar um conjunto de dados vinculado do BigQuery ao criar o bucket de registros, a menos que você use o Console do Google Cloud. No entanto, se você criar e atualizar um bucket de registros, poderá usar o método de comando gcloud logging links create para criar um conjunto de dados vinculado.

Para criar apenas um bucket de registros, execute o comando gcloud logging buckets create. Se você quiser fazer upgrade do bucket de registros para usar a análise de registros, inclua as sinalizações --enable-analytics e --async e defina a variável LOCATION como uma região compatível com a análise de registros:

gcloud logging buckets create BUCKET_ID --location=LOCATION --enable-analytics --async OPTIONAL_FLAGS

A sinalização --async força o comando a ser assíncrono. O retorno de um método assíncrono é um objeto Operation. Ele contém informações sobre o progresso do método. Quando o método é concluído, o objeto Operation contém o status. Para mais informações, consulte Métodos de API assíncronas.

Se você não quiser fazer upgrade do bucket de registros para usar a análise de registros, omita as sinalizações --enable-analytics e --async. É possível definir a variável LOCATION como qualquer região compatível.

Por exemplo, se você quiser criar um bucket com a my-bucket BUCKET_ID na região asia-east2, seu comando será semelhante ao seguinte:

gcloud logging buckets create my-bucket --location asia-east2 --description "My first bucket"

Por exemplo, para criar um bucket com BUCKET_ID my-upgraded-bucket no local us e, em seguida, fazer upgrade do bucket de registros para usar a análise de registros, seu comando seria assim:

gcloud logging buckets create my-upgraded-bucket --location us \
      --description "My first upgraded bucket" \
      --enable-analytics --retention-days=45

Observação: depois de criar o bucket de registros, não será possível alterar a região. Se você precisar de um bucket em uma região diferente, crie um novo bucket nessa região, redirecione os coletores apropriados para o novo bucket e exclua o bucket antigo

API

Observação: não é possível criar um conjunto de dados vinculado do BigQuery como parte da operação de criação, a menos que você use o Console do Google Cloud. No entanto, se você criar e atualizar um bucket de registros, poderá usar o método projects.locations.buckets.links.create para criar um conjunto de dados vinculado.

Para criar um bucket, use o método projects.locations.buckets.create ou projects.locations.buckets.createAsync. Prepare os argumentos do método da seguinte maneira:

1. Defina o parâmetro parent como o recurso em que o bucket será criado: projects/PROJECT_ID/locations/LOCATION

   A variável LOCATION refere-se à região em que você quer que seus registros sejam armazenados. Nem todas as regiões são compatíveis com a análise de registros. Para mais informações, consulte Regiões compatíveis.

   Por exemplo, se você quiser criar um bucket para o projeto my-project na região asia-east2, seu parâmetro parent seria assim: projects/my-project/locations/asia-east2

2. Defina o parâmetro bucketId, por exemplo, my-bucket.

3. Siga uma das seguintes ações:

   • Para criar um bucket de registros e, em seguida, fazer upgrade dele para usar a análise de registros:

     1. Defina o booleano LogBucket.analyticsEnabled como true.

        Aviso: o upgrade de um bucket de registros para usar a análise de registros é irreversível.

     2. Chame o método assíncrono projects.locations.buckets.createAsync para criar o bucket.

        A resposta aos métodos assíncronos é um objeto Operation. Esse objeto contém informações sobre o progresso do método. Quando o método for concluído, o objeto Operation conterá o status. Para mais informações, consulte Métodos de API assíncronas.

        O método createAsync leva vários minutos para ser concluído. Esse método não gera uma mensagem de erro ou falha quando o booleano analyticsEnabled está definido como true e a região não é compatível com buckets atualizados. Por exemplo, se você definir o local como asia-east2, o bucket de registros será criado, mas não será feito upgrade dele para usar a análise de registros.

   • Caso contrário, chame o método síncrono projects.locations.buckets.create para criar o bucket.

Depois de criar um bucket, crie um coletor para encaminhar as entradas de registro para o bucket e configure as visualizações de registro para controlar quem pode acessar os registros no novo bucket e quais registros podem ser acessados por eles. Também é possível atualizar o bucket para configurar a retenção personalizada e os campos restritos.

Rastrear o volume de registros armazenados em buckets

A página Armazenamento de registros no Console do Google Cloud rastreia o volume de dados de registros armazenados em buckets:

No console do Google Cloud, selecione Logging e Armazenamento de registros ou clique no botão a seguir:

Acessar o armazenamento de registros

A página Armazenamento de registros exibe um resumo das estatísticas do seu projeto do Google Cloud:

As seguintes estatísticas são informadas:

• Ingestão do mês atual: a quantidade de dados de registros que o projeto do Google Cloud armazenou nos buckets desde o primeiro dia do mês atual.

• Ingestão do mês anterior: a quantidade de dados de registros que o projeto do Google Cloud armazenou nos buckets de registros no último mês.

• Projeção de ingestão por EOM: a quantidade estimada de dados de registros que seu projeto do Google Cloud armazenará nos buckets de registros até o final do mês atual, com base no uso atual.

• Armazenamento faturável do mês atual: a quantidade de dados de registros retidos por mais de 30 dias.

As estatísticas anteriores não incluem registros no bucket _Required. Não é possível excluir ou desativar os registros nesse bucket.

Na página Roteador de registros no Console do Google Cloud, há ferramentas que podem ser usadas para minimizar as cobranças de armazenamento de registros em buckets de registros ou de armazenamento que excede a cota mensal. Faça o seguinte:

• Desative o armazenamento de registros no nível do bucket.
• Impedir que determinadas entradas de registro sejam armazenadas em buckets de registros.

Para mais informações, consulte Gerenciar coletores.

Gerenciar buckets

Nesta seção, descrevemos como gerenciar os buckets de registros usando a Google Cloud CLI ou o console do Google Cloud.

Atualizar um bucket

Para atualizar as propriedades do bucket, como a descrição ou o período de armazenamento, faça o seguinte:

Console do Google Cloud

Para atualizar as propriedades do bucket, faça o seguinte:

1. No console do Google Cloud, selecione Logging e Armazenamento de registros ou clique no botão a seguir:

   Acessar o armazenamento de registros

2. No bucket que você quer atualizar, clique em Mais.

3. Selecione Editar bucket.

4. Edite o bucket conforme necessário.

5. Clique em Atualizar bucket.

gcloud

Para atualizar as propriedades do bucket, execute o comando gcloud logging buckets update:

gcloud logging buckets update BUCKET_ID --location=LOCATION UPDATED_ATTRIBUTES

Exemplo:

gcloud logging buckets update my-bucket --location=global --description "Updated description"

API

Para atualizar as propriedades do bucket, use projects.locations.buckets.patch na API Logging.

Fazer upgrade de um bucket para usar a análise de registros

Aviso: o upgrade de um bucket de registros para usar a análise de registros é irreversível. Somente as entradas de registro gravadas após a conclusão do upgrade estão disponíveis para análise.

Para fazer upgrade de um bucket atual para usar a análise de registros, as seguintes restrições se aplicam:

• O bucket de registros foi criado para envolvidos no projeto do Google Cloud.
• O bucket de registros está desbloqueado, a menos que seja o bucket _Required.
• Não há atualizações pendentes para o bucket.

• Nem todas as regiões são compatíveis com a análise de registros. Para mais informações, consulte Regiões compatíveis.

Console do Google Cloud

Para fazer upgrade de um bucket atual para usar a análise de registros, faça o seguinte:

1. No console do Google Cloud, selecione Logging e Armazenamento de registros ou clique no botão a seguir:

   Acessar o armazenamento de registros

2. Localize o bucket do qual você quer fazer upgrade.

3. Quando a coluna Análise de registros disponível exibir Upgrade, será possível fazer upgrade do bucket de registros para usar a análise de registros. Clique em Fazer upgrade.

   para abrir a caixa de diálogo. Clique em Confirmar.

gcloud

Para fazer upgrade do bucket de registros para usar a análise de registros, execute o comando gcloud logging buckets update. É necessário definir a sinalização --enable-analytics. Também recomendamos incluir a sinalização --async:

gcloud logging buckets update BUCKET_ID --location=LOCATION --enable-analytics --async

A sinalização --async força o comando a ser assíncrono. O retorno de um método assíncrono é um objeto Operation e contém informações sobre o progresso do método. Quando o método é concluído, o objeto Operation contém o status. Para mais informações, consulte Métodos de API assíncronas.

Observação: não atualize nenhuma outra propriedade de um bucket de registros ao fazer upgrade para usar a análise de registros. Por exemplo, uma chamada para o comando update que altera o período de armazenamento e atualiza o bucket de registros falha.

API

Para fazer upgrade de um bucket de registros para usar a análise de registros, use o método projects.locations.buckets.updateAsync da API Cloud Logging.

Prepare os argumentos do método da seguinte maneira:

1. Defina o booleano LogBucket.analyticsEnabled como true.
2. Para o parâmetro de consulta do comando, use updateMask=analyticsEnabled.

A resposta aos métodos assíncronos é um objeto Operation. Esse objeto contém informações sobre o progresso do método. Quando o método for concluído, o objeto Operation conterá o status. Para mais informações, consulte Métodos de API assíncronas.

O updateAsync pode levar vários minutos para ser concluído.

Criar um conjunto de dados vinculado do BigQuery

Quando você quiser usar os recursos do BigQuery para analisar os dados de registro, faça upgrade de um bucket de registros para usar a análise de registros e crie um conjunto de dados vinculado. Com essa configuração, é possível usar o BigQuery para ler os registros armazenados no bucket de registros.

Observação: um bucket de registros pode ser vinculado a, no máximo, um conjunto de dados do BigQuery.

Console do Google Cloud

Para criar um link para um conjunto de dados do BigQuery para um bucket de registros atual, faça o seguinte:

1. Revise a seção Antes de começar deste documento.

2. No console do Google Cloud, selecione Logging e Armazenamento de registros ou clique no botão a seguir:

   Acessar o armazenamento de registros

3. Localize o bucket de registros e verifique se a coluna Análise de registros disponível exibe Abrir.

   Se essa coluna exibir Upgrade, isso significa que o upgrade do bucket de registros não foi feito para usar a análise de registros. Configure a análise de registros:

   1. Clique em Fazer upgrade.
   2. Clique em Confirmar na caixa de diálogo.

   Após a conclusão do upgrade, vá para a próxima etapa.

4. No bucket de registros, clique em Mais e em Editar bucket.

   A caixa de diálogo Editar bucket de registros é aberta.

5. Selecione Criar um novo conjunto de dados do BigQuery vinculado a esse bucket e insira o nome do novo conjunto de dados.

   O nome do conjunto de dados precisa ser exclusivo para cada projeto do Google Cloud. Se você inserir o nome de um conjunto de dados existente, receberá o seguinte erro: Dataset name must be unique in the selected region.

6. Clique em Concluído e em Atualizar bucket.

   Depois que o Logging exibe o nome do conjunto de dados vinculado na página Armazenamento de registros, pode levar alguns minutos para que o BigQuery reconheça o conjunto de dados.

gcloud

Para criar um conjunto de dados vinculado para um bucket de registros que foi atualizado para usar a análise de registros, execute o comando gcloud logging links create:

gcloud logging links create LINK_ID --bucket=BUCKET_ID --location=LOCATION

O campo LINK_ID precisa ser exclusivo para seu projeto do Google Cloud.

O comando links create é assíncrono. O retorno de um método assíncrono é um objeto Operation e contém informações sobre o progresso do método. Quando o método é concluído, o objeto Operation contém o status. Para mais informações, consulte Métodos de API assíncronas.

O comando links create leva alguns minutos para ser concluído.

Por exemplo, o comando a seguir cria um conjunto de dados vinculado para o bucket com o nome my-bucket:

gcloud logging links create mylink --bucket=my-bucket --location=global

O nome do conjunto de dados precisa ser exclusivo para cada projeto do Google Cloud. Se você tentar criar um conjunto de dados com o mesmo nome de um conjunto de dados existente, receberá o seguinte erro:

BigQuery dataset with name "my-bucket" already exists.

Se você tentar criar um conjunto de dados vinculado para um bucket de registros que não está atualizado para usar a análise de registros, o seguinte erro será relatado:

A link can only be created for an analytics-enabled bucket.

API

Para criar um conjunto de dados vinculado do BigQuery a um bucket de registros atual atualizado com a Análise de registros, chame o método assíncrono projects.locations.buckets.links.create da API Cloud Logging.

Prepare os argumentos do método da seguinte maneira:

1. Crie o corpo da solicitação para o comando create. O corpo da solicitação é formatado como um objeto Link.
2. Para o parâmetro de consulta do comando, use linkId=LINK_ID. O LINK_ID fornecido é usado como o nome do conjunto de dados. Portanto, LINK_ID compartilha o mesmo valor que o DATASET_ID de saída.

A resposta aos métodos assíncronos é um objeto Operation. Esse objeto contém informações sobre o progresso do método. Quando o método é concluído, o objeto Operation contém o status. Para mais informações, consulte Métodos de API assíncronas.

O método links.create leva vários minutos para ser concluído.

O nome do conjunto de dados precisa ser exclusivo para cada projeto do Google Cloud. Se você tentar criar um conjunto de dados com o mesmo nome de um conjunto de dados existente, receberá o seguinte erro:

BigQuery dataset with name "my-bucket" already exists.

Se você tentar criar um conjunto de dados vinculado para um bucket de registros que não está atualizado para usar a análise de registros, o seguinte erro será relatado:

A link can only be created for an analytics-enabled bucket.

Bloquear um bucket

Aviso: o bloqueio de um bucket de registro é irreversível.

Quando você bloqueia as atualizações de um bucket, a política de armazenamento do bucket também é bloqueada. Depois que uma política de armazenamento estiver bloqueada, você não poderá excluir o bucket até que todos os registros nele atendam ao período de armazenamento.

Para impedir que alguém atualize ou exclua um bucket de registros, bloqueie-o. Para bloquear o bucket, faça o seguinte:

Console do Google Cloud

O console do Google Cloud não é compatível com o bloqueio de um bucket de registros.

gcloud

Para bloquear o bucket, execute o comando gcloud logging buckets update com a sinalização --locked:

gcloud logging buckets update BUCKET_ID --location=LOCATION --locked

Exemplo:

gcloud logging buckets update my-bucket --location=global --locked

API

Para bloquear os atributos do bucket, use projects.locations.buckets.patch na API Logging. Defina o parâmetro locked como true.

Listar buckets

Para listar os buckets de registro associados a um projeto do Google Cloud e ver detalhes como configurações de retenção, faça o seguinte:

Console do Google Cloud

No console do Google Cloud, selecione Logging e Armazenamento de registros ou clique no botão a seguir:

Acessar o armazenamento de registros

A tabela Buckets de registros lista os buckets associados ao projeto atual do Google Cloud.

A tabela lista os seguintes atributos para cada bucket de registro:

• Nome: o nome do bucket de registros.
• Descrição: a descrição do bucket.
• Período de armazenamento: o número de dias em que os dados do bucket são armazenados pelo Cloud Logging.
• Região: a localização geográfica em que os dados do bucket são armazenados.
• Status: indica se o bucket está bloqueado ou desbloqueado.

Se um bucket estiver com a exclusão pendente do Cloud Logging, a entrada da tabela dele será anotada com um símbolo de aviso.

gcloud

Execute o comando gcloud logging buckets list:

gcloud logging buckets list

Você verá os seguintes atributos dos buckets de registro:

• LOCATION: a região em que os dados do bucket são armazenados.
• BUCKET_ID: o nome do bucket de registros.
• RETENTION_DAYS: o número de dias em que os dados do bucket serão armazenados pelo Cloud Logging.
• LIFECYCLE_STATE: indica se o bucket está exclusão pendente pelo Cloud Logging.
• LOCKED: se o bucket está bloqueado ou desbloqueado.
• CREATE_TIME: um carimbo de data/hora que indica quando o bucket foi criado.
• UPDATE_TIME: um carimbo de data/hora que indica quando o bucket foi modificado pela última vez.

Também é possível visualizar os atributos de apenas um bucket. Por exemplo, para ver os detalhes do bucket de registros _Default na região global, execute o comando gcloud logging buckets describe:

gcloud logging buckets describe _Default --location=global

API

Para listar os buckets de registro associados a um projeto do Google Cloud, use projects.locations.buckets.list na API Logging.

Ver os detalhes de um intervalo

Para ver os detalhes de um único bucket de registro, faça o seguinte:

Console do Google Cloud

No console do Google Cloud, selecione Logging e Armazenamento de registros ou clique no botão a seguir:

Acessar o armazenamento de registros

No bucket de registros, clique em Mais e selecione Ver detalhes do bucket.

A caixa de diálogo lista os seguintes atributos para o bucket de registro:

• Nome: o nome do bucket de registros.
• Descrição: a descrição do bucket de registros.
• Período de armazenamento: o número de dias em que os dados do bucket são armazenados pelo Cloud Logging.
• Região: a localização geográfica em que os dados do bucket são armazenados.
• Análise de registros: indica se o bucket foi atualizado para usar a análise de registros.
• Análise do BigQuery: indica se um conjunto de dados do BigQuery está vinculado ao bucket.
• Conjunto de dados do BigQuery: fornece um link para o conjunto de dados do BigQuery, que é aberto na página Espaço de trabalho SQL do BigQuery. A data em que a vinculação do BigQuery foi ativada também é exibida.

gcloud

Execute o comando gcloud logging buckets describe.

Por exemplo, o comando a seguir informa os detalhes do bucket _Default:

gcloud logging buckets describe _Default --location=global

Você verá os seguintes atributos para o bucket de registros:

• createTime: um carimbo de data/hora que indica quando o bucket foi criado.
• description: a descrição do bucket de registros.
• lifecycleState: indica se o bucket está exclusão pendente pelo Cloud Logging.
• name: o nome do bucket de registros.
• retentionDays: o número de dias em que os dados do bucket serão armazenados pelo Cloud Logging.
• updateTime: um carimbo de data/hora que indica quando o bucket foi modificado pela última vez.

API

Para ver os detalhes de um único bucket de registros, use projects.locations.buckets.get na API Logging.

Excluir um bucket

Para excluir um bucket de registro, faça o seguinte:

Console do Google Cloud

Para excluir um bucket de registro, faça o seguinte:

1. No console do Google Cloud, selecione Logging e Armazenamento de registros ou clique no botão a seguir:

   Acessar o armazenamento de registros

2. Localize o bucket que você quer excluir e clique em Mais.

3. Se a coluna Conjunto de dados vinculado no BigQuery exibir um link, exclua o conjunto de dados vinculado do BigQuery:

   1. Clique em Editar bucket.

   2. Desmarque Criar um novo conjunto de dados do BigQuery vinculado a esse bucket, clique em Concluído e em Atualizar bucket.

      Depois de voltar à página Armazenamento de registros, clique em Mais no bucket que você quer excluir e prossiga para as próximas etapas.

4. Selecione Excluir bucket.

5. No painel de confirmação, clique em Excluir.

6. Na página Armazenamento de registros, o bucket tem um indicador mostrando que a exclusão está pendente. O bucket e todos os registros contidos nele são excluídos após sete dias.

gcloud

Para excluir um bucket de registros, execute o comando gcloud logging buckets delete:

gcloud logging buckets delete BUCKET_ID --location=LOCATION

Não é possível excluir um bucket de registros quando esse bucket tem um conjunto de dados do BigQuery vinculado:

• Para listar os links associados a um bucket de registros, execute o comando gcloud logging links list.
• Para excluir um conjunto de dados vinculado, execute o comando gcloud logging links delete.

API

Para excluir um bucket, use projects.locations.buckets.delete na API Logging.

É um erro excluir um bucket de registros se esse bucket tiver um conjunto de dados do BigQuery vinculado. É preciso excluir o conjunto de dados vinculado antes de excluir o bucket de registros:

• Para listar os links associados a um bucket de registros, execute o método projects.locations.buckets.links.list.
• Para excluir um conjunto de dados vinculado, execute o método projects.locations.buckets.links.delete.

Um bucket excluído permanece nesse estado pendente por sete dias, e o Logging continua a rotear registros para ele durante esse período. Para interromper o roteamento de registros para um bucket excluído, exclua os coletores de registro que têm esse bucket como destino ou modifique o filtro dos coletores para interromper o roteamento para o bucket excluído.

Observação: buckets com exclusão pendente contam para a cota de buckets por projeto do Google Cloud até que sejam totalmente excluídos.

Restaurar um bucket excluído

É possível restaurar ou cancelar a exclusão de um bucket que esteja no estado de exclusão pendente. Para restaurar um bucket de registro, faça o seguinte:

Console do Google Cloud

Para restaurar um bucket de registros com exclusão pendente, faça o seguinte:

1. No console do Google Cloud, selecione Logging e Armazenamento de registros ou clique no botão a seguir:

   Acessar o armazenamento de registros

2. No bucket que você quer restaurar, clique em Mais e selecione Restaurar bucket excluído.

3. No painel de confirmação, clique em Restaurar.

4. Na página Armazenamento de registros, o indicador de exclusão pendente é removido do bucket.

gcloud

Para restaurar um bucket de registros com exclusão pendente, execute o comando gcloud logging buckets undelete:

gcloud logging buckets undelete BUCKET_ID --location=LOCATION

API

Para restaurar um bucket com exclusão pendente, use projects.locations.buckets.undelete na API Logging.

Alerta sobre bytes de registro mensais armazenados em buckets

Para criar uma política de alertas, na página Armazenamento de registros no Console do Google Cloud, clique em Criar alerta de uso. Esse botão abre a página Criar política de alertas no Monitoring e preenche o campo de tipo de métrica com logging.googleapis.com/billing/bytes_ingested.

Para criar uma política de alertas acionada quando o número de bytes de registro gravados nos buckets exceder o limite definido pelo usuário do Cloud Logging, use as configurações a seguir.

Etapas para criar uma política de alertas

Para criar uma política de alertas, siga estas etapas:

1. No Console do Google Cloud, selecione Monitoring e clique em  Alertas ou clique no botão a seguir:

   Acessar o alerta

2. Se você não tiver criado seus canais de notificação e quiser receber uma notificação, clique em Editar canais de notificação e adicione-os. Volte para a página Alertas depois de adicionar seus canais.
3. Na página Alertas, clique em Criar política.
4. Para selecionar o recurso, a métrica e os filtros, expanda o menu Selecionar uma métrica e use os valores na tabela Nova condição:
   1. (Opcional) Para limitar o menu a entradas relevantes, insira o nome do recurso ou da métrica na barra de filtro.
   2. Selecione um Tipo de recurso. Por exemplo, selecione Instância de VM.
   3. Selecione uma Categoria de métrica. Por exemplo, selecione instância.
   4. Selecione uma Métrica. Por exemplo, selecione CPU Utilization.
   5. Selecione Apply.
5. Clique em Avançar e configure o acionador da política de alertas. Para preencher esses campos, use os valores na tabela Configurar gatilho de alerta.
6. Clique em Próxima.

7. Opcional: para adicionar notificações à sua política de alertas, clique em Canais de notificação. Na caixa de diálogo, selecione um ou mais canais de notificação no menu e clique em OK.

   (Opcional) Para receber uma notificação quando os incidentes forem abertos ou fechados, marque Notificar sobre o fechamento de incidentes. Por padrão, as notificações são enviadas apenas quando incidentes são abertos.

8. Opcional: Atualize a Duração do fechamento automático do incidente. Este campo determina quando o Monitoring fecha incidentes na ausência de dados de métrica.
9. Opcional: clique em Documentação e adicione as informações que quer incluir em uma mensagem de notificação.
10. Clique em Nome e digite um nome para a política de alertas.
11. Clique em Criar política.

Novo estado Campo	Valor
Recurso e métrica	No menu Recursos, selecione Global. No menu Categorias de métrica, selecione Métrica com base em registros. No menu Métricas, selecione Bytes de registro mensais ingeridos.
Filtrar	Nenhuma.
Várias séries Agregação de série temporal	sum
Janela contínua	60 m
Função de janela contínua	max

Campo Configurar gatilho de alerta	Valor
Tipo de condição	Threshold
Acionador de alerta	Any time series violates
Posição do limite	Above threshold
Valor do limite	Você determina o valor aceitável.
Teste a janela novamente	O valor mínimo aceitável é de 30 minutos.

Para mais informações sobre políticas de alertas, consulte Visão geral de alertas.

Gravar em um bucket

Os registros não são gravados diretamente em um bucket de registros. Em vez disso, você grava registros no recurso do Google Cloud: um projeto, uma pasta ou uma organização do Google Cloud. Os coletores no recurso pai então roteiam os registros para destinos, incluindo buckets de registro. Um coletor encaminha registros para um destino de bucket de registro quando os registros correspondem ao filtro do coletor e o coletor tem permissão para rotear os registros para o bucket de registros.

Ler em um bucket

Cada bucket de registros tem um conjunto de visualizações. Para ler registros de um bucket de registro, é preciso ter acesso a uma visualização no bucket. Para mais informações sobre visualizações de registro, consulte Configurar o acesso no nível do bucket.

Para ler registros de um bucket de registro, faça o seguinte:

Console do Google Cloud

É possível refinar o escopo dos registros exibidos no Explorador de registros por meio do painel Refinar escopo. É possível pesquisar apenas registros no projeto atual do Google Cloud ou pesquisar registros em uma ou mais visualizações de armazenamento. Para refinar o escopo do Explorador de registros, faça o seguinte:

1. No console do Google Cloud, selecione Logging e Navegador de Registros ou clique no seguinte botão:

   Acesse o Explorador de registros

2. Selecione Refinar escopo.

3. No painel Refinar escopo, selecione uma opção Escopo por.

4. Selecione Escopo por armazenamento e escolha um ou mais buckets que você quer ver.

   O console lista as visualizações de armazenamento que atendem às seguintes condições:

   • Você tem acesso à visualização de armazenamento.
   • Os buckets de registro pertencem ao projeto do Google Cloud selecionado ou o projeto do Google Cloud selecionado roteou os registros para os buckets de armazenamento.

gcloud

Para ler registros de um bucket de registros, use o comando gcloud logging read e adicione um LOG_FILTER para selecionar dados:

gcloud logging read LOG_FILTER --bucket=BUCKET_ID --location=LOCATION --view=VIEW_ID

API

Para ler registros de um bucket de registros, use o método entries.list. Defina resourceNames para especificar o bucket e a visualização de registro apropriados e defina filter para selecionar dados.

Para informações detalhadas sobre a sintaxe de filtragem, consulte Linguagem de consulta do Logging.

Configurar retenção personalizada

Observação : a partir de 1o de abril de 2023, os custos de retenção se aplicam a dados de registros retidos por mais tempo do que o período de armazenamento padrão do bucket de registros. Para detalhes sobre preços, consulte Resumo dos preços do Cloud Logging. Para revisar o armazenamento faturável para seus buckets de registro, acesse a página Armazenamento de registros do Console do Google Cloud.

Ao criar um bucket de registro, você tem a opção de personalizar o período de armazenamento dos registros do bucket pelo Cloud Logging. É possível configurar o período de armazenamento para qualquer bucket de registros definido pelo usuário e também para o bucket de registros _Default.

Se você encurtar a retenção do bucket, haverá um período de carência de sete dias em que os registros expirados não serão excluídos. Não é possível consultar ou visualizar esses registros expirados. No entanto, nesses sete dias, é possível restaurar o acesso total estendendo a retenção do bucket. Os registros armazenados durante o período de carência são contabilizados nos custos de armazenamento.

Para atualizar o período de armazenamento de um bucket de registro, siga estas etapas:

Console do Google Cloud

Para atualizar o período de armazenamento de um bucket de registros, faça o seguinte:

1. No console do Google Cloud, selecione Logging e Armazenamento de registros ou clique no botão a seguir:

   Acessar o armazenamento de registros

2. No bucket que você quer atualizar, clique em Mais e selecione Editar bucket.

3. No campo Retenção, insira o número de dias, entre 1 e 3650 dias, que você quer que o Cloud Logging armazene seus registros.

4. Clique em Atualizar bucket. A nova duração de retenção aparece na lista Bucket de registros.

gcloud

Para atualizar o período de armazenamento de um bucket de registros, execute o comando gcloud logging buckets update, depois de definir um valor para RETENTION_DAYS:

gcloud logging buckets update BUCKET_ID  --location=LOCATION --retention-days=RETENTION_DAYS

Por exemplo, para manter os registros no bucket _Default no local global por um ano, o comando será semelhante a este:

gcloud logging buckets update _Default --location=global --retention-days=365

Se você prolongar o período de armazenamento de um bucket, as regras de retenção serão aplicadas a partir de agora, não retroativamente. Não é possível recuperar os registros após o término do período de armazenamento aplicável.

Métodos de API assíncronos

A resposta de um método assíncrono, como projects.locations.buckets.createAsync, é um objeto Operation.

Os aplicativos que chamam um método de API assíncrona precisam pesquisar o endpoint operation.get até que o valor do campo Operation.done seja true:

• Quando done é false, a operação está em andamento.

  Para atualizar as informações de status, envie uma solicitação GET para o endpoint operation.get.

• Quando done é true, a operação é concluída e o campo error ou response está definido:

  • error: quando definida, a operação assíncrona falha. O valor desse campo é um objeto Status que contém um código de erro gRPC e uma mensagem de erro.
  • response: quando definido, a operação assíncrona é concluída e o valor reflete o resultado.

Para pesquisar um comando assíncrono usando a Google Cloud CLI, execute o seguinte comando:

gcloud logging operations describe OPERATION_ID --location=LOCATION --project=PROJECT_ID

Para ver mais informações, consulte gcloud logging operations describe.

Resolver problemas comuns

Se você tiver problemas ao usar buckets de registros, consulte as etapas de solução de problemas e respostas a perguntas comuns a seguir.

Por que não consigo excluir esse bucket?

Se você estiver tentando excluir um bucket, faça o seguinte:

• Verifique se você tem as permissões corretas para excluir o bucket. Para ver a lista das permissões necessárias, consulte Controle de acesso com o IAM.

• Determine se o bucket está bloqueado listando os atributos do bucket. Se o bucket estiver bloqueado, verifique o período de armazenamento do bucket. Não é possível excluir um bucket bloqueado até que todos os registros nele tenham cumprido o período de armazenamento.

• Verifique se o bucket de registros não tem um conjunto de dados vinculado do BigQuery. Não é possível excluir um bucket de registros com um conjunto de dados vinculado.

  O erro a seguir é mostrado em resposta a um comando delete em um bucket de registros que tem um conjunto de dados vinculado:

  FAILED_PRECONDITION: This bucket is used for advanced analytics and has an active link. The link must be deleted first before deleting the bucket
  

  Para listar os links associados a um bucket de registros, execute o comando gcloud logging links list ou o método da API projects.locations.buckets.links.list.

Quais contas de serviço estão roteando registros para meu bucket?

Para determinar se alguma conta de serviço tem permissões de IAM para rotear registros para o bucket, faça o seguinte:

1. No Console do Google Cloud, selecione IAM ou clique no botão a seguir:

   Acessar IAM

2. Na guia Permissões, visualize por Papéis. Você verá uma tabela com todos os papéis e principais do IAM associados ao projeto do Google Cloud.

3. No campoFiltro caixa de texto, digiteGravador de bucket de registros.

   Você verá todos os principais com o papel de Gravador de bucket de registros. Se um principal for uma conta de serviço, o ID conterá a string gserviceaccount.com.

4. Opcional: se quiser remover uma conta de serviço para impedir a capacidade de rotear registros para seu projeto do Google Cloud, marque a caixa de seleção da conta de serviço e clique em Remover.

Por que vejo registros de um projeto do Google Cloud mesmo que os tenha excluído do meu coletor _Default?

É possível ver os registros em um bucket de registros em um projeto centralizado do Google Cloud, que agrega registros de toda a organização.

Se você estiver usando o Explorador de registros para acessar esses registros e ver os registros excluídos do coletor _Default, talvez sua visualização esteja no escopo do nível do projeto do Google Cloud.

Para corrigir esse problema, selecione Escopo por armazenamento no painel Refinar escopo e, em seguida, selecione o bucket _Default no projeto do Google Cloud. Você não verá mais os registros excluídos.

Por que não consigo criar métricas com base em registros para um bucket?

As métricas com base em registros se aplicam apenas a um único projeto do Google Cloud. Não é possível criá-los para buckets de registros ou para outros recursos do Google Cloud, como pastas ou organizações.

A seguir

Para mais informações sobre os métodos da API Logs Bucket, consulte a documentação de referência de LogBucket.

Para informações sobre como lidar com casos de uso comuns com buckets de registro, consulte os tópicos a seguir:

• Agregar e armazenar os registros da sua organização.

• Geração de registros multilocatário no GKE.

• Regionalize seus registros.