Registros de uso e de armazenamento

Neste documento, você aprenderá a fazer o download e conferir os registros de uso e as informações de armazenamento de buckets do Cloud Storage, além de analisar os registros usando o Google BigQuery.

Introdução

O Cloud Storage oferece registros de uso e de armazenamento na forma de arquivos CSV. É possível fazer o download deles e visualizá-los. Os registros de uso fornecem informações sobre todas as solicitações feitas em um bucket específico e são criados a cada hora. Os registros de armazenamento fornecem informações sobre o consumo de armazenamento desse bucket no último dia e são criados diariamente.

Depois de configurados, os registros de uso e de armazenamento são criados automaticamente como novos objetos em um bucket especificado por você.

Os registros de uso e de armazenamento estão sujeitos ao mesmo preço que outros objetos armazenados no Cloud Storage.

É melhor usar os registros de uso ou os registros de auditoria do Cloud?

Na maioria dos casos, os registros de auditoria do Cloud é o método recomendado para gerar registros que rastreiam as operações de API realizadas no Cloud Storage:

Os registros de auditoria do Cloud rastreiam o acesso de maneira contínua, com entrega de eventos em segundos de ocorrência.
Os registros de auditoria do Cloud são mais fáceis de trabalhar.
O registro de auditoria do Cloud pode ser usado para monitorar vários serviços do Google Cloud, não apenas o Cloud Storage.
Opcionalmente, os registros de auditoria do Cloud podem gravar informações detalhadas sobre solicitações e respostas.

Em alguns casos, você pode querer usar registros de uso em vez de ou além de usando os registros de auditoria do Cloud. Os registros de uso são recomendados nestes casos:

Você quer rastrear o acesso que ocorre porque um recurso tem allUsers ou allAuthenticatedUsers nas configurações de controle de acesso, como o acesso a recursos em um bucket que você configurou para ser um site estático.
Você quer rastrear as alterações feitas pelos recursos de Gerenciamento do ciclo de vida de objetos ou Classe automática.
Você quer usar downloads autenticados do navegador para acessar objetos no bucket.
Você quer que os registros incluam informações de latência, o tamanho da solicitação e da resposta de solicitações HTTP individuais ou o caminho do URL completo e todos os parâmetros de consulta.
Você quer rastrear o acesso apenas a determinados buckets no projeto e, portanto, não quer ativar os registros de auditoria de acesso a dados, que rastreiam o acesso a todos os buckets do projeto.

Os registros de uso são gerados apenas por hora e podem ser atrasados, especialmente quando os relatórios têm intervalos com altas taxas de solicitação.

É melhor usar os registros de armazenamento ou o Monitoring?

Geralmente, não convém usar os registros de armazenamento. A ferramenta recomendada para medir o consumo de armazenamento é o Monitoring, que fornece ferramentas de visualização e métricas adicionais relacionadas ao consumo de armazenamento que os registros de armazenamento não oferecem. Consulte a guia Console para determinar o tamanho de um bucket para instruções passo a passo sobre como usar o Monitoring.

Configurar entrega de registros

Quando você configura a entrega de registros, os registros de uso e de armazenamento são gerados para o bucket especificado. As etapas a seguir descrevem como configurar a entrega de registros para um bucket. Se você ainda não tiver um bucket que planeja usar para armazenar registros, crie-o.

Linha de comando

Atribua ao Cloud Storage o papel roles/storage.objectCreator para o bucket.
```
gcloud storage buckets add-iam-policy-binding gs://example-logs-bucket --member=group:cloud-storage-analytics@google.com --role=roles/storage.objectCreator
```
O papel concede ao Cloud Storage, na forma do grupo cloud-storage-analytics@google.com, permissão para criar e armazenar seus registros como novos objetos.

Os objetos de registro têm a ACL padrão de objetos do bucket de registro, a menos que o acesso uniforme no nível do bucket esteja ativado.
Ative a geração de registros para o bucket usando a flag --log-bucket:
```
gcloud storage buckets update gs://example-bucket --log-bucket=gs://example-logs-bucket [--log-object-prefix=log_object_prefix]
```
Também é possível definir um prefixo de objeto para os objetos de registro usando a sinalização --log-object-prefix. O prefixo do objeto forma o início do nome do objeto de registro. Ele pode ter no máximo 900 caracteres e precisa ser um nome de objeto válido. Por padrão, o prefixo do objeto é o nome do bucket em que os registros estão ativados.

APIs REST

API JSON

Atribua ao Cloud Storage o papel roles/storage.objectCreator para o bucket. Se houver vinculações adicionais de IAM no nível do bucket, inclua-as na solicitação.
```
POST /storage/v1/b/example-logs-bucket/iam
Host: storage.googleapis.com
{
  "bindings":[
    {
      "role": "roles/storage.objectCreator",
      "members":[
        "group-cloud-storage-analytics@google.com"
      ]
    }
  ]
}
```
O papel concede ao Cloud Storage, na forma do grupo cloud-storage-analytics@google.com, permissão para criar e armazenar seus registros como novos objetos.

Os objetos de registro têm a ACL padrão de objetos do bucket de registro, a menos que o acesso uniforme no nível do bucket esteja ativado.

Ative a geração de registros para seu bucket usando a seguinte solicitação:

PATCH /storage/v1/b/example-bucket
Host: storage.googleapis.com

{
 "logging": {
  "logBucket": "example-logs-bucket",
  "logObjectPrefix": "log_object_prefix"
 }
}

API XML

Defina permissões para conceder ao Cloud Storage a permissão WRITE ao bucket para criar e armazenar seus registros como novos objetos. É necessário adicionar uma entrada de ACL para o bucket que concede ao grupo cloud-storage-analytics@google.com acesso de gravação. Certifique-se de incluir na solicitação todas as ACLs atuais do bucket, além da nova.

PUT /example-logs-bucket?acl HTTP/1.1
Host: storage.googleapis.com

<AccessControlList>
  <Entries>
    <Entry>
      <Scope type="GroupByEmail">
        <EmailAddress>cloud-storage-analytics@google.com</EmailAddress>
      </Scope>
     <Permission>WRITE</Permission>
    </Entry>
    <!-- include other existing ACL entries here-->
  </Entries>
</AccessControlList>

Ative a geração de registros para seu bucket usando o parâmetro de consulta de geração de registros:

PUT /example-bucket?logging HTTP/1.1
Host: storage.googleapis.com

<Logging>
    <LogBucket>example-logs-bucket</LogBucket>
    <LogObjectPrefix>log_object_prefix</LogObjectPrefix>
</Logging>

Verificar o status do registro

Linha de comando

Verifique a geração de registros usando o comando buckets describe com a sinalização --format:

gcloud storage buckets describe gs://example-bucket --format="default(logging_config)"

Também é possível salvar as configurações de geração de registros em um arquivo:

gcloud storage buckets describe gs://example-bucket > your_logging_configuration_file --format="default(logging_config)"

Se a geração de registros estiver ativada, o servidor retornará a configuração da geração de registros na resposta:

logging:
  logBucket: example-logs-bucket
  logObjectPrefix: log_object_prefix

Se a geração de registros não estiver ativada, o que retornará é:

null

APIs REST

API JSON

Envie uma solicitação GET para a configuração da geração de registros do bucket, conforme mostrado no exemplo a seguir:

GET /storage/v1/b/example-bucket?fields=logging
Host: storage.googleapis.com

Se a geração de registros estiver ativada, o servidor enviará a configuração na resposta. A resposta pode ser semelhante a esta:

{
 "logging": {
  "logBucket": "example-logs-bucket",
  "logObjectPrefix": "log_object_prefix"
  }
}

Se a geração de registros não estiver ativada, será retornada uma configuração em branco:

{}

API XML

Envie uma solicitação GET Bucket para a configuração da geração de registros do bucket, conforme mostrado no exemplo a seguir:

GET /example-bucket?logging HTTP/1.1
Host: storage.googleapis.com

Se a geração de registros estiver ativada, o servidor enviará a configuração na resposta. A resposta pode ser semelhante a esta:

<?xml version="1.0" ?>
<Logging>
    <LogBucket>
        example-logs-bucket
    </LogBucket>
    <LogObjectPrefix>
        log_object_prefix
    </LogObjectPrefix>
</Logging>

Se a geração de registros não estiver ativada, será retornada uma configuração em branco:

<?xml version="1.0" ?>
<Logging/>

Download de registros

Os registros de armazenamento são gerados uma vez por dia e contêm a quantidade de armazenamento usada no dia anterior. Eles normalmente são criados antes das 16h (horário de Brasília).

Registros de consumo são gerados a cada hora quando há atividade para relatar no bucket monitorado. Registros de consumo geralmente são criados 15 minutos após o final da hora.

Observação:

Qualquer processamento de registros de consumo precisa considerar a possibilidade de que eles sejam entregues 15 minutos após o final de uma hora.
Normalmente, os objetos de registro de uso por hora contêm registros de todos os acessos que ocorreram durante essa hora. De vez em quando, um objeto de registro de consumo por hora pode conter registros referentes a uma hora anterior, mas nunca a uma hora posterior.
O Cloud Storage pode gravar vários objetos de registro para a mesma hora.
De vez em quando, um único registro pode aparecer duas vezes nos registros de uso. Nós nos esforçamos ao máximo para remover registros duplicados, mas seu processamento de registros precisa ser capaz de removê-los caso isso seja essencial para a análise de registros. É possível usar o campo s_request_id para detectar duplicações.

A maneira mais fácil de fazer o download dos registros de uso e de armazenamento do bucket em que estão armazenados é por meio doConsole do Google Cloud ou o gcloud storage CLI do Google Analytics. Os registros de uso estão no formato CSV e seguem a seguinte convenção de nomenclatura:

OBJECT_PREFIX_usage_TIMESTAMP_ID_v0

Registros de armazenamento seguindo a convenção de nomenclatura apresentada abaixo:

OBJECT_PREFIX_storage_TIMESTAMP_ID_v0

Por exemplo, o nome a seguir é o nome de um objeto de registro de uso que usa o prefixo de objeto padrão, informa o uso do bucket example-bucket e foi criado em 18 de junho de 2022 às 14h UTC :

example-bucket_usage_2022_06_18_14_00_00_1702e6_v0

Da mesma forma, veja a seguir o nome do objeto de registro do armazenamento que usa o prefixo de objeto padrão e foi criado em 18 de junho de 2022 para o mesmo bucket:

example-bucket_storage_2022_06_18_07_00_00_1702e6_v0

Para fazer o download de registros:

Console

No Console do Google Cloud, acesse a página Buckets do Cloud Storage.

Acessar buckets
Selecione o bucket em que os registros estão armazenados.
Faça o download ou visualize os registros clicando no objeto de registro apropriado.

Linha de comando

Execute este comando:

gcloud storage cp gs://BUCKET_NAME/LOGS_OBJECT DESTINATION

Em que:

BUCKET_NAME é o nome do bucket em que os registros são armazenados. Por exemplo, example-logs-bucket.
LOGS_OBJECT é o nome do registro de uso ou de armazenamento que você está fazendo o download. Por exemplo, example-bucket_usage_2022_06_18_14_00_00_1702e6_v0.
DESTINATION é o local em que o download do registro está sendo feito; Por exemplo, Desktop/Logs.

Analise registros no BigQuery

Para consultar o consumo do Cloud Storage e os registros de consumo, é possível usar o Google BigQuery, que permite consultas rápidas semelhantes a SQL em tabelas somente para anexação. A ferramenta de linha de comando do BigQuery, bq, é uma ferramenta baseada em Python para acessar o BigQuery a partir da linha de comando. Para informações sobre como usar e fazer o download da bq, consulte a página de referência da ferramenta de linha de comando bq.

Carregar registros no BigQuery

Selecione um projeto padrão.

Para detalhes sobre como selecionar um projeto, consulte Como trabalhar com projetos.

Crie um novo conjunto de dados.

$ bq mk storageanalysis
Dataset 'storageanalysis' successfully created.

Liste os conjuntos de dados do projeto:

$ bq ls
 
datasetId
-----------------
storageanalysis

Salve os esquemas de consumo e armazenamento em seu computador local para usá-los no comando de carregamento.

Encontre os esquemas nestes locais: cloud_storage_usage_schema_v0 e cloud_storage_storage_schema_v0. Os esquemas também estão descritos na seção Formato de registros de uso e de armazenamento.
Carregue os registros de uso no conjunto de dados.
```
$ bq load --skip_leading_rows=1 storageanalysis.usage \
      gs://example-logs-bucket/example-bucket_usage_2014_01_15_14_00_00_1702e6_v0 \
      ./cloud_storage_usage_schema_v0.json
$ bq load --skip_leading_rows=1 storageanalysis.storage \
      gs://example-logs-bucket/example-bucket_storage_2014_01_05_14_00_00_091c5f_v0 \
      ./cloud_storage_storage_schema_v0.json
```
Esses comandos fazem o seguinte:
- Carregamento dos registros de uso e armazenamento do bucket example-logs-bucket.
- Criação das tabelas usage e storage no conjunto de dados storageanalysis.
- Leitura dos dados do esquema (arquivo .json) do mesmo diretório em que o comando bq é executado.
- Desvio da primeira linha de cada arquivo de registros por conter descrições de colunas.
Como essa foi a primeira vez que o comando de carregamento foi executado no exemplo, foram criadas as tabelas usage e storage. É possível continuar anexando a essas tabelas usando comandos de carregamento subsequentes com diferentes nomes de arquivos de registros de uso ou caracteres curinga. Por exemplo, o comando a seguir inclui dados de todos os registros que começam com "bucket_usuage_2014" à tabela storage:
```
$ bq load --skip_leading_rows=1 storageanalysis.usage \
      gs://example-logs-bucket/bucket_usage_2014* \
      ./cloud_storage_usage_schema.json
```
Ao usar caracteres curinga, recomenda-se mover os registros já enviados ao BigQuery para outro diretório (por exemplo, gs://example-logs-bucket/processed) para evitar que o upload de dados de um registro seja feito mais de uma vez.

A funcionalidade do BigQuery também pode ser acessada usando a ferramenta de navegação do BigQuery. Com a ferramenta de navegação, é possível carregar dados por meio do processo de criação de tabelas.

Para mais informações sobre como carregar dados do Cloud Storage, incluindo carregar dados programaticamente, consulte Como carregar dados do Cloud Storage.

Modificar o esquema do registro de uso

Em algumas situações, pode ser útil pré-processar os registros de uso antes de carregar no BigQuery. Por exemplo, é possível adicionar mais informações aos registros de uso para facilitar a análise de consultas no BigQuery. Nesta seção, mostraremos como adicionar ao registro o nome do arquivo de cada registro de uso do armazenamento. Isso exige a modificação do esquema atual e de cada arquivo de registros.

Modifique o esquema existente, cloud_storage_storage_schema_v0, para incluir o nome do arquivo, conforme mostrado abaixo. Renomeie o esquema, por exemplo, cloud_storage_storage_schema_custom.json, para diferenciá-lo do original.
```
[  {"name": "bucket", "type": "string", "mode": "REQUIRED"},
{"name": "storage_byte_hours","type": "integer","mode": "REQUIRED"},
{"name": "filename","type": "string","mode": "REQUIRED"}
]
```
Pré-processe os arquivos de registro de uso de armazenamento com base no novo esquema, antes de carregá-los no BigQuery.

Por exemplo, os comandos a seguir podem ser usados em um ambiente Linux, macOS ou Windows (Cygwin):
```
gcloud storage cp gs://example-logs-bucket/example-bucket_storage\* .
for f in example-bucket_storage\*; do sed -i -e "1s/$/,\"filename\"/" -e "2s/$/,\""$f"\"/" $f; done
```
O comando gcloud storage copia os arquivos para o diretório de trabalho. O segundo comando percorre os arquivos de registros e adiciona "filename" à linha de descrição (primeira linha) e o nome real do arquivo à linha de dados (segunda linha). Aqui está um exemplo de arquivo de registros modificado:
```
"bucket","storage_byte_hours","filename"
"example-bucket","5532482018","example-bucket_storage_2014_01_05_08_00_00_021fd_v0"
```

Ao carregar os registros de uso de armazenamento no BigQuery, carregue os registros modificados localmente e use o esquema personalizado.

for f in example-bucket_storage\*; \
do ./bq.py load --skip_leading_rows=1 storageanalysis.storage $f ./cloud_storage_storage_schema_custom.json; done

Registros de consulta no BigQuery

Depois que os registros forem carregados no BigQuery, consulte os registros de uso para retornar informações sobre os intervalos registrados. O exemplo a seguir mostra como usar a ferramenta bq em uma situação em que há registros de uso de um bucket de vários dias, e os registros foram carregados conforme mostrado em Como carregar registros de uso no BigQuery Também é possível executar as consultas abaixo usando a ferramenta de navegação do BigQuery.

Na ferramenta do bq, entre no modo interativo.
```
$ bq shell
```

Execute uma consulta na tabela de registros de armazenamento.

Por exemplo, a consulta a seguir mostra como o armazenamento de um bucket registrado muda ao longo do tempo. Nela, supõe-se que os registros de uso de armazenamento foram alterados conforme descrito em Como modificar o esquema de registro de uso e que os arquivos de registros foram nomeados como "logstorage*".

project-name>SELECT SUBSTRING(filename, 13, 10) as day, storage_byte_hours/24 as size FROM [storageanalysis.storage] ORDER BY filename LIMIT 100

Exemplo de saída da consulta:

Waiting on bqjob_r36fbf5c164a966e8_0000014379bc199c_1 ... (0s) Current status: DONE
+------------+----------------------+
|    day     |         size         |
+------------+----------------------+
| 2014_01_05 | 2.3052008408333334E8 |
| 2014_01_06 | 2.3012297245833334E8 |
| 2014_01_07 | 3.3477797120833334E8 |
| 2014_01_08 | 4.4183686058333334E8 |
+-----------------------------------+

Se o esquema não foi modificado e o esquema padrão estiver sendo usado, é possível executar a seguinte consulta:

project-name>SELECT storage_byte_hours FROM [storageanalysis.storage] LIMIT 100

Execute uma consulta na tabela de registro de consumo.

Por exemplo, a consulta a seguir mostra como resumir os métodos de solicitação usados pelos clientes para acessar recursos no bucket registrado.

project-name>SELECT cs_method, COUNT(*) AS count FROM [storageanalysis.usage] GROUP BY cs_method

Exemplo de saída da consulta:

Waiting on bqjob_r1a6b4596bd9c29fb_000001437d6f8a52_1 ... (0s) Current status: DONE
+-----------+-------+
| cs_method | count |
+-----------+-------+
| PUT       |  8002 |
| GET       | 12631 |
| POST      |  2737 |
| HEAD      |  2173 |
| DELETE    |  7290 |
+-----------+-------+

Saia do shell interativo da ferramenta bq.
```
project-name> quit
```

Desative a geração de registros

Linha de comando

Desative a geração de registros com a sinalização --clear-log-bucket no comando buckets update:

gcloud storage buckets update gs://example-bucket --clear-log-bucket

Para verificar se a geração de registros foi desativada, use o comando buckets describe:

gcloud storage buckets describe gs://example-bucket --format="default(logging_config)"

Se a geração de registros estiver desativada, será retornada a seguinte resposta:

null

APIs REST

API JSON

Desative a geração de registros enviando uma solicitação PATCH para a configuração da geração de registros do bucket, conforme mostrado no exemplo a seguir.

PATCH /example-bucket?logging HTTP/1.1
Host: storage.googleapis.com

{
 "logging": null
}

API XML

Desative a geração de registros enviando uma solicitação PUT para a configuração da geração de registros do bucket, conforme mostrado no exemplo a seguir:

PUT /example-bucket?logging HTTP/1.1
Host: storage.googleapis.com

<Logging/>

Formato dos registros de uso e de armazenamento

Os registros de uso e de armazenamento podem fornecer uma enorme quantidade de informações. Use as tabelas a seguir para identificar todas as informações fornecidas nesses registros.

Campos de registro de uso:

Campo	Tipo	Descrição
`time_micros`	número inteiro	A hora em que a solicitação foi concluída, em microssegundos, a partir da Era Unix.
`c_ip`	string	O endereço IP a partir do qual a solicitação foi feita. O prefixo "c" indica que são informações sobre o cliente.
`c_ip_type`	número inteiro	O tipo de IP no campo c_ip: O valor 1 indica um endereço IPV4. O valor 2 indica um endereço IPV6.
`c_ip_region`	string	Reservado para uso futuro.
`cs_method`	string	O método HTTP desta solicitação. O prefixo "cs" indica que essas informações foram enviadas do cliente para o servidor.
`cs_uri`	string	O URI da solicitação.
`sc_status`	número inteiro	O código do status HTTP enviado pelo servidor em resposta. O prefixo "sc" indica que essas informações foram enviadas do servidor para o cliente.
`cs_bytes`	número inteiro	O número de bytes enviados na solicitação.
`sc_bytes`	número inteiro	O número de bytes enviados na resposta.
`time_taken_micros`	número inteiro	O tempo, em microssegundos, que levou para a solicitação ser atendida a partir do momento em que o primeiro byte foi recebido até o momento em que a resposta foi enviada. Observe que, para uploads recuperáveis, o ponto final é determinado pela resposta à solicitação de upload final que fazia parte do upload recuperável.
`cs_host`	string	O host na solicitação original.
`cs_referer`	string	O referenciador HTTP (em inglês) da solicitação.
`cs_user_agent`	string	O User-Agent (em inglês) da solicitação. O valor é `GCS Lifecycle Management` para as solicitações feitas pelo gerenciamento do ciclo de vida.
`s_request_id`	string	O identificador da solicitação.
`cs_operation`	string	A operação do Cloud Storage, por exemplo, `GET_Object`. Ela pode ser nula.
`cs_bucket`	string	O bucket especificado na solicitação.
`cs_object`	string	O objeto especificado nessa solicitação. Pode ser nulo.

Campos de registro de armazenamento:

Campo	Tipo	Descrição
`bucket`	string	O nome do bucket.
`storage_byte_hours`	número inteiro	O tamanho médio em byte por hora durante um período de 24 horas do bucket. Para calcular o tamanho total do bucket, divida os bytes/hora por 24.