Nesta página, descrevemos como configurar o Serviço de transferência do Cloud Storage para gerar dados de registro que registram ações e estados. É possível visualizar e analisar os dados de registro usando o Cloud Logging.
O Serviço de transferência do Cloud Storage pode gerar dados de registro para todas as transferências. No entanto, as operações FIND
não são registradas para transferências baseadas em agentes.
As transferências do sistema de arquivos também podem configurar registros de transferência do sistema de arquivos.
Antes de começar
Antes de começar, verifique se você tem acesso ao Cloud Logging. Recomendamos o visualizador de registros (roles/logging.viewer) Identity and Access Management. Para mais informações sobre o acesso ao Logging, consulte Controle de acesso com o IAM.
Os documentos a seguir descrevem como verificar seu acesso atual e como conceder papéis do IAM:
- Veja o acesso atual para verificar o acesso que cada principal tem.
- Conceda um papel aos principais relevantes do projeto.
Ações registráveis
As seguintes ações podem ser registradas:
FIND: buscar trabalho a fazer, como listar arquivos em um diretório, listar objetos em um bucket ou listar pastas gerenciadas em um bucket. Não compatível com transferências baseadas em agente.COPY: copiar arquivos ou objetos para o destino (Cloud Storage ou um sistema de arquivos).DELETE: excluir arquivos ou objetos na origem ou no destino. Para transferências entre dois sistemas de arquivos, também registra a exclusão de arquivos do bucket do Cloud Storage intermediário.
Estados registráveis
Para cada ação, também é possível registrar um ou mais dos seguintes estados:
SUCCEEDED: a ação foi bem-sucedida.FAILED: a ação falhou.SKIPPED: aplica-se apenas à ação COPY e é compatível apenas com jobs de transferência baseados em agente. Precisa ser definido usandogcloudou a API REST. Esse estado significa que a cópia foi ignorada. Isso ocorre quando o arquivo já existe no coletor e o job de transferência está configurado para ignorar arquivos existentes.
Práticas recomendadas
Ativar a geração de registros para a ação FIND ou para o estado SUCCEEDED pode
resultar em um alto volume de dados de registro.
Use as estratégias a seguir para reduzir o volume de dados de registro armazenados:
Registrar apenas falhas. Se você não precisar de uma auditoria de conformidade completa no nível do objeto, configure o job para gravar registros apenas para ações de cópia e exclusão e somente quando ocorrer uma falha.
Use dados de métricas para monitorar a capacidade, as contagens de bytes e os objetos ignorados ou com falha. É possível criar gráficos e monitorar dados de métricas usando uma política de alertas. Para ver uma lista de métricas disponíveis, consulte Monitorar jobs de transferência.
Configure o Cloud Logging para descartar dados de registro de alto volume e baixo valor. Para fazer essa mudança, atualize os coletores de registros no projeto para excluir dados de registro de baixo valor do Serviço de transferência do Cloud Storage. Como todos os coletores de registros em um projeto avaliam todas as entradas de registro, talvez seja necessário atualizar vários coletores de registros.
Use o filtro de exclusão a seguir para excluir entradas de registro do Serviço de transferência do Cloud Storage que registram ações de sucesso:
resource.type="storage_transfer_job" AND jsonPayload.status.statusCode="OK"Para saber como encontrar e modificar seus coletores de registros, consulte Rotear registros para destinos compatíveis.
Ativar a geração de registros
Para configurar o Serviço de transferência do Cloud Storage para gerar dados de registro, especifique as ações e os estados a serem registrados.
CLI da gcloud
Ao criar um job de transferência com gcloud transfer jobs create, use as
seguintes flags para ativar a geração de registros:
gcloud transfer jobs create SOURCE DESTINATION \
--log-actions=copy,delete \
--log-action-states=succeeded,failed
É preciso especificar pelo menos um valor para cada flag. É possível adicionar find a
--log-actions apenas para transferências sem agente e skipped a
--log-action-states apenas para transferências baseadas em agente. Não é possível
combinar as duas no mesmo job.
REST
Para criar uma configuração de geração de registros, use
transferJobs.create com um
LoggingConfig:
{
"name": "transferJobs/myFirstTransfer",
"status": "ENABLED",
"projectId": "test-id-001",
"loggingConfig": {
"logActions": ["FIND", "DELETE", "COPY"],
"logActionStates": ["SUCCEEDED", "FAILED"]
},
"transferSpec": {
"gcsDataSource": {
"bucketName": "source_bucket"
},
"gcsDataSink": {
"bucketName": "destination_bucket",
"path": "foo/bar/"
}
}
}
Para transferências baseadas em agentes, omita "FIND" de logActions. Se quiser, inclua "SKIPPED" em logActionStates.
Ajuste loggingConfig para incluir os logActions e
logActionStates específicos a serem registrados. Por exemplo, para registrar quando as ações de copiar e buscar falharem,
forneça o seguinte loggingConfig:
"loggingConfig": {
"logActions": ["COPY", "FIND"],
"logActionStates": ["FAILED"]
}
Atualizar uma configuração de geração de registros
CLI gcloud
Para atualizar a configuração de geração de registros de um job, use as flags apropriadas com o comando gcloud transfer jobs update:
gcloud transfer jobs update NAME \
--log-actions=copy,delete \
--log-action-states=succeeded,failed
Para desativar a geração de registros para esse job, especifique --clear-log-config:
gcloud transfer jobs update NAME --clear-log-config
REST
Para atualizar uma configuração de geração de registros de uma transferência atual, use
transferJobs.patch com
LoggingConfig:
{
"projectId": "test-id-001",
"transferJob": {
"loggingConfig": {
"logActions": ["FIND", "DELETE", "COPY"],
"logActionStates": ["SUCCEEDED", "FAILED"]
}
},
"updateTransferJobFieldMask": "loggingConfig"
}
O updateTransferJobFieldMask especifica o campo que está sendo atualizado nesta solicitação e é obrigatório.
Para desativar a geração de registros para esse job, envie um loggingConfig com listas vazias para
logActions e logActionStates:
{
"projectId": "test-id-001",
"transferJob": {
"loggingConfig": {
"logActions": [],
"logActionStates": []
}
},
"updateTransferJobFieldMask": "loggingConfig"
}
Ver registros
Para ver os registros de transferência, faça o seguinte:
Console do Google Cloud
Acesse o menu de navegação do Google Cloud menu e selecione Logging > Análise de registros :
Selecionar um projeto do Google Cloud
Para filtrar seus registros e mostrar apenas entradas do Serviço de transferência do Cloud Storage, digite
storage_transfer_jobno campo de consulta e clique em Executar consulta.No painel Resultados da consulta, clique em Editar hora para alterar o período de retorno dos resultados.
Veja mais informações em Como usar a Análise de registros.
CLI gcloud
Para usar a CLI gcloud para pesquisar registros do Serviço de transferência do Cloud Storage, use o
comando
gcloud logging read.
Especifique um filtro para limitar os resultados aos registros do Serviço de transferência do Cloud Storage.
gcloud logging read "resource.type=storage_transfer_job"
API Cloud Logging
Use o método entries.list
da API Cloud Logging.
Para filtrar os resultados e incluir apenas entradas relacionadas ao Serviço de transferência do Cloud Storage,
use o campo filter. Veja abaixo um exemplo de objeto de solicitação JSON.
{
"resourceNames":
[
"projects/my-project-name"
],
"orderBy": "timestamp desc",
"filter": "resource.type=\"storage_transfer_job\""
}
Formato do registro de transferência
A tabela a seguir descreve os campos para os registros do Serviço de transferência do Cloud Storage:
Todos os campos específicos do Serviço de transferência do Cloud Storage estão contidos em um
objeto jsonPayload.
FIND ações
{ "jsonPayload": { "@type": "type.googleapis.com/google.storagetransfer.logging.TransferActivityLog", "action": "FIND", "completeTime": "2021-12-16T18:58:49.344509695Z", "destinationContainer": { "gcsBucket": { "bucket": "my-bucket-2" }, "type": "GCS" }, "operation": "transferOperations/transferJobs-7876027868280507149--3019866490856027148", "sourceContainer": { "gcsBucket": { "bucket": "my-bucket-1" }, "type": "GCS" }, "status": { "statusCode": "OK" } } }
Ações COPY e DELETE
{ "jsonPayload": { "@type": "type.googleapis.com/google.storagetransfer.logging.TransferActivityLog", "action": "COPY", "completeTime": "2021-12-16T18:59:00.510509049Z", "destinationObject": { "gcsObject": { "bucket": "my-bucket-2", "objectKey": "README.md" }, "type": "GCS" }, "operation": "transferOperations/transferJobs-7876027868280507149--3019866490856027148", "sourceObject": { "gcsObject": { "bucket": "my-bucket-1", "lastModifiedTime": "2021-12-07T16:41:09.456Z", "md5": "WgnCOIdfCXNTUDpQJSKb2w==", "objectKey": "README.md" }, "type": "GCS" }, "status": { "statusCode": "OK" } } }
| Campo de registro | Descrição |
|---|---|
@type |
O valor sempre é
type.googleapis.com/google.storagetransfer.logging.TransferActivityLog.
|
action |
Descreve a ação dessa tarefa específica. Opções:
|
findAction |
Especifica se o assunto da ação de localização era um objeto ou uma pasta gerenciada. |
completeTime |
O carimbo de data e hora em conformidade com a ISO 8601 em que a operação foi concluída. |
destinationContainer |
Presente apenas para operações O contêiner de destino dessa transferência. Contém dois subcampos:
|
destinationObject |
presente apenas para operações Informações sobre o objeto no destino. Contém dois subcampos:
Exemplo: "destinationObject": { "type": "POSIX_FS", "posixFile": { "crc32c": "0", "path": "/tmp/data/filename.txt", "lastModifiedTime": "2022-09-22T04:33:45Z" } } |
operation |
O nome totalmente qualificado de
transferOperations. |
sourceContainer |
Presente apenas para operações O contêiner de origem dessa transferência. Contém dois subcampos:
Exemplo: "sourceContainer": { "gcsBucket": { "bucket": "my-bucket-1" }, "type": "GCS" } |
sourceObject |
presente apenas para operações Informações sobre o objeto de origem. Contém dois subcampos:
Exemplo: "sourceObject": { "gcsObject": { "bucket": "my-bucket-1", "lastModifiedTime": "2021-12-07T16:41:09.456Z", "md5": "WgnCOIdfCXNTUDpQJSKb2w==", "objectKey": "README.md" }, "type": "GCS" } |
status |
O status da ação. Se |
Além disso, o campo resource de nível superior contém os seguintes campos.
"resource": {
"labels": {
"job_id": "transferJobs/7876027868280507149",
"project_id": "my-project-id"
},
"type": "storage_transfer_job"
}
| Campo de registro | Descrição |
|---|---|
resource.labels.job_id |
O nome do job do Serviço de transferência do Cloud Storage a que o registro pertence. |
resource.labels.project_id |
O ID do projeto do Google Cloud para essa transferência. |