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ê.

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

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

  • O registro de auditoria do Cloud rastreia o acesso de maneira contínua.
  • O registro de auditoria do Cloud é mais fácil 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, é melhor utilizar os registros de uso. Os registros de uso são recomendados nestes casos:

  • Você quer rastrear o acesso a objetos públicos, como os ativos em um bucket configurado para ser um site estático.
  • Você quer rastrear as alterações feitas pelo recurso Gerenciamento do ciclo de vida de objetos.
  • Você quer usar downloads autenticados do navegador para acessar objetos no bucket.
  • Você quer que os registros incluam informações de latência ou o tamanho da solicitação e da resposta de solicitações HTTP individuais.

É 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 Como determinar o tamanho de um bucket para instruções passo a passo sobre como usar o Monitoring.

Como configurar a entrega de registros

Nas etapas a seguir, descrevemos como configurar o envio de registros para um bucket específico usando a ferramenta gsutil, a API XML e a API JSON. Se você não tem a ferramenta gsutil, poderá fazer o download e a instalação dela como parte do pacote SDK do Google Cloud ou como um produto independente.

gsutil

  1. Crie um bucket para armazenar os registros usando este comando:

    gsutil mb gs://example-logs-bucket
  2. Atribua o papel roles/storage.legacyBucketWriter ao bucket do Cloud Storage:

    gsutil iam ch group:cloud-storage-analytics@google.com:legacyBucketWriter gs://example-logs-bucket

    O papel concede ao Cloud Storage, na forma do alias 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.

  3. Ative a geração de registros para seu bucket usando o comando logging:

    gsutil logging set on -b gs://example-logs-bucket [-o log_object_prefix ] gs://example-bucket

    Opcionalmente, você pode definir um prefixo de objeto para registrar objetos usando 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.

API XML

  1. Crie um bucket para armazenar registros usando esta solicitação:

    PUT /example-logs-bucket HTTP/1.1
    Host: storage.googleapis.com
    
  2. 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>
    
  3. 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>
    

API JSON

  1. Crie um bucket para armazenar registros usando esta solicitação:

    POST /storage/v1/b?project=project-id
    Host: storage.googleapis.com
    
    {
      "name": "example-logs-bucket"
    }
    
  2. Atribua ao Cloud Storage o papel roles/storage.legacyBucketWriter 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.legacyBucketWriter",
          "members":[
            "group-cloud-storage-analytics@google.com"
          ]
        }
      ]
    }
    

    O papel concede ao Cloud Storage, na forma do alias 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.

  3. 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"
     }
    }
    

Como verificar o status do registro

gsutil

Use a gsutil para verificar a geração de registros com o comando logging get:

gsutil logging get gs://example-bucket

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

gsutil logging get gs://example-bucket > your_logging_configuration_file

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

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

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

gs://example-bucket/ has no logging configuration.

API XML

É possível enviar uma solicitação GET Bucket para a configuração da geração de registros do bucket usando a API XML do Cloud Storage, 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. Essa resposta pode ser similar a:

<?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/>

API JSON

É possível enviar uma solicitação GET para a configuração da geração de registros do intervalo usando a API JSON do Cloud Storage, 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. Essa resposta pode ser similar a:

{
 "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:

{
}

Como fazer o 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.

O acesso a seus registros é controlado pela ACL nos objetos de registro. Os objetos de registro têm a ACL padrão de objetos do bucket de registros.

A maneira mais fácil de fazer o download de registros de uso e de armazenamento é por meio do Console do Google Cloud ou usando a ferramenta gsutil. Os registros de uso estão no formato CSV e seguem a seguinte convenção de nomenclatura:

gs://<bucket_name>/<object_prefix>_usage_<timestamp>_<id>_v0

Por exemplo, este é um objeto de registros de uso de um bucket chamado gs://example-bucket, criado em 18 de junho de 2013 às 14h UTC e armazenado no bucket gs://example-logs-bucket:

gs://example-logs-bucket/example-bucket_usage_2013_06_18_14_00_00_1702e6_v0

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

gs://<bucket_name>/<object_prefix>_storage_<timestamp>_<id>_v0

Por exemplo, veja a seguir um objeto de registro de armazenamento para o mesmo bucket em 18 de junho de 2013:

gs://example-logs-bucket/example-bucket_storage_2013_06_18_07_00_00_1702e6_v0

Para fazer o download de registros:

Console

  1. Abra o navegador do Cloud Storage no Console do Google Cloud.
    Abrir o navegador do Cloud Storage
  2. Selecione o bucket de registro.

  3. Faça o download ou visualize os registros clicando no objeto de registro apropriado.

gsutil

Execute este comando:

gsutil cp <logs_object> <destination_uri>

Como analisar registros no BigQuery

Para consultar os registros de uso e de armazenamento do Cloud Storage, use o Google BigQuery, que permite consultas rápidas, semelhantes ao 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.

Como carregar registros no BigQuery

  1. Selecione um projeto padrão.

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

  2. Crie um novo conjunto de dados.

    $ bq mk storageanalysis
    Dataset 'storageanalysis' successfully created.
    
  3. Liste os conjuntos de dados do projeto:

    $ bq ls
     
    datasetId
    -----------------
    storageanalysis
    
  4. Salve os esquemas de uso 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.

  5. 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.

Como alterar 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.

  1. Modifique o esquema atual, cloud_storage_storage_schema_v0, para adicionar 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"}
    ]
    
  2. 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):

    gsutil 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 gsutil 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"
    
  3. 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
    

Como consultar registros 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.

  1. Na ferramenta do bq, entre no modo interativo.

    $ bq shell
    
  2. 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
    
  3. 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 |
    +-----------+-------+
    
  4. Saia do shell interativo da ferramenta do bq.

    project-name> quit
    

Como desativar a geração de registros

gsutil

Use gsutil para desativar a geração de registros com o comando logging:

gsutil logging set off gs://example-bucket

Para verificar se a geração de registros foi desativada, execute uma solicitação logging get:

gsutil logging get gs://example-bucket

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

gs://example-bucket/ has no logging configuration.

API XML

Use a API XML do Cloud Storage para desativar a geração de registros, enviando uma solicitação PUT para a configuração de geração de registros do intervalo, como mostra o exemplo a seguir:

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

<Logging/>

API JSON

Use a API JSON do Cloud Storage para desativar a geração de registros. Para isso, envie uma solicitação PATCH para a configuração de geração de registros do intervalo, como mostra o exemplo a seguir:

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

{
 "logging": null
}

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 (em inglês).
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.
cs_bucket string O bucket especificado na solicitação. Se for uma solicitação de listagem de buckets, esse valor poderá ser nulo.
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.