Cloud Logging para operações em lote de armazenamento

É possível configurar e visualizar registros de operação em lote do Storage no Cloud Logging. Ao configurar o Cloud Logging, um job de operações em lote gera entradas de registro para cada job de transformação, com cada entrada correspondendo à transformação tentada de um objeto.

As operações em lote do Storage oferecem suporte à geração de registros no Cloud Logging e nos Registros de auditoria do Cloud Storage. Embora as duas opções capturem ações de operação em lote do Storage, recomendamos o uso do Cloud Logging. O Cloud Logging oferece uma plataforma centralizada para análise de registros, monitoramento em tempo real e filtragem avançada, oferecendo uma solução robusta para gerenciar e entender a atividade de operações em lote.

Antes de começar

Verifique se você tem acesso ao Cloud Logging. Para usar o Cloud Logging, recomendamos conceder o papel Logs Viewer (roles/logging.viewer) do Identity and Access Management. O papel Logs Viewer (roles/logging.viewer) do Identity and Access Management fornece as permissões do Identity and Access Management necessárias para visualizar os dados do Cloud Logging. Para mais informações sobre as permissões de acesso ao Logging, consulte Controle de acesso com o IAM.

Para verificar e conceder as permissões do IAM, siga estas etapas:

Entender os detalhes do registro

Quando a geração de registros está ativada, as operações em lote do Storage capturam os seguintes detalhes:

  • Ação registrável: o valor da ação registrável é sempre transform.

  • Estados registráveis: para cada ação, é possível registrar um ou ambos os estados a seguir:

    • SUCCEEDED: a ação foi bem-sucedida.
    • FAILED: a ação falhou.

Ativar a geração de registros

Para ativar a geração de registros, especifique as ações e os estados a serem registrados.

Linha de comando

Ao criar um job de operação em lote do Storage com gcloud storage batch-operations jobs create, use as flags --log-actions e --log-action-states para ativar a geração de registros.

gcloud storage batch-operations jobs create JOB_NAME \
  --manifest-location=MANIFEST_LOCATION \
  --delete-object \
  --log-actions=transform \
  --log-action-states=LOG_ACTION_STATES

Em que:

  • JOB_NAME é o nome que você quer dar ao job. Por exemplo, my-job.
  • MANIFEST_LOCATION é o local do manifesto. Por exemplo, gs://my-bucket/manifest.csv.
  • LOG_ACTION_STATES é uma lista separada por vírgulas de estados a serem registrados. Por exemplo, succeeded,failed.

API REST

Crie um job de operação em lote do Storage com um LoggingConfig.

{
   "loggingConfig": {
      "logActions": ["TRANSFORM"],
      "logActionStates": ["LOG_ACTION_STATES"],
        }
}

Em que:

LOG_ACTION_STATES é uma lista separada por vírgulas de estados a serem registrados. Por exemplo, "SUCCEEDED","FAILED".

Ver registros

Para visualizar os registros de operação em lote do Storage, faça o seguinte:

Console

  1. Acesse o Cloud de Confiance menu de navegação e selecione Geração de registros > Análise de registros :<br></br>

    Acessar a Análise de registros.

  2. Selecionar um Cloud de Confiance projeto do

  3. No menu Upgrade, alterne de Visualizador de registros legados para Análise de registros.

  4. Para filtrar seus registros e mostrar apenas entradas de operações em lote de armazenamento, digite storage_batch_operations_job no campo de consulta e clique em Executar consulta.

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

Linha de comando

Para usar a CLI gcloud para pesquisar registros de operações em lote do Storage, use o gcloud logging read comando.

Especifique um filtro para limitar os resultados aos registros de operações em lote do Storage.

gcloud logging read "resource.type=storage_batch_operations_job"

API REST

Use o método entries.list da API Cloud Logging.

Para filtrar os resultados e incluir apenas entradas relacionadas a operações em lote do Storage, use o campo filter. Confira abaixo um exemplo de objeto de solicitação JSON:

{
"resourceNames":
  [
    "projects/my-project-name"
  ],
  "orderBy": "timestamp desc",
  "filter": "resource.type=\"storage_batch_operations_job\""
}

Em que:

my-project-name é o nome do projeto.

Formato de registro de operações em lote do Storage

Todos os campos específicos de operação em lote do Storage estão contidos em um objeto jsonPayload. Embora o conteúdo exato de jsonPayload varie de acordo com o tipo de serviço, há uma estrutura comum compartilhada em todas as TransformActivityLog entradas. Esta seção descreve os campos de registro comuns e detalha os campos específicos da operação.

  • Campos de registro comuns

    Os campos a seguir aparecem em todos os registros:

    jsonPayload: {
"@type": "type.googleapis.com/google.cloud.storagebatchoperations.logging.TransformActivityLog",
"completeTime": "YYYY-MM-DDTHH:MM:SS.SSSSSSSSSZ",
"status": {
  "errorMessage": "String indicating error",
  "errorType": "ENUM_VALUE",
  "statusCode": "ENUM_VALUE"
},
"logName": "projects/PROJECT_ID/logs/storagebatchoperations.googleapis.com%2Ftransform_activity",
"receiveTimestamp": "YYYY-MM-DDTHH:MM:SS.SSSSSSSSSZ",
"resource": {
  "labels": {
    "location":"us-central1",
    "job_id": "BATCH_JOB_ID",
    "resource_container": "RESOURCE_CONTAINER",
    // ... other labels
  },
  "type": "storagebatchoperations.googleapis.com/Job"
},
// Operation-specific details will be nested here (for example,
// "DeleteObject", "PutObjectHold", "RewriteObject", "PutMetadata")
// Each operation-specific object will also contain the following
// object: "objectMetadataBefore": {
//   "gcsObject": {
//     "bucket": "BUCKET_NAME",
//     "generation": "GENERATION_NUMBER",
//     "objectKey": "OBJECT_PATH"
//   }
// }
}

    A tabela a seguir descreve cada um dos campos de registro comuns:

    Campos de registro comuns Tipo Descrição
    @type String Especifica o tipo de payload da entrada de registro e indica que o registro representa um TransformActivityLog para operações em lote do Storage.
    completeTime Carimbo de data/hora O carimbo de data e hora em conformidade com a ISO 8601 em que a operação foi concluída.
    status Objeto Fornece informações sobre o resultado da atividade de operação em lote.
    status.errorMessage String Uma mensagem de erro se a operação falhar. A mensagem de erro aparece apenas se o valor de status.statusCode não for OK.
    status.errorType String O tipo de erro. O tipo de erro aparece apenas se o valor de status.statusCode não for OK.
    status.statusCode String O código de status da operação. A operação será bem-sucedida se o valor for OK. Qualquer outro valor indica falha.
    logName String O nome completo do recurso do registro, indicando o projeto e o fluxo de registro.
    receiveTimestamp Carimbo de data/hora O carimbo de data/hora em que a entrada de registro foi recebida pelo sistema de registro.
    resource Objeto Informações sobre o recurso que gerou a entrada de registro.
    resource.labels Objeto Pares de chave-valor que fornecem informações de identificação adicionais sobre o recurso.
    resource.type String O tipo de recurso que gerou o registro.
    objectMetadataBefore Objeto Contém metadados do objeto antes da tentativa de operação em lote.
    objectMetadataBefore.gcsObject Objeto Detalhes sobre o objeto.
    objectMetadataBefore.gcsObject.bucket String O nome do bucket onde o objeto reside.
    objectMetadataBefore.gcsObject.generation String O número de geração do objeto antes da operação.
    objectMetadataBefore.gcsObject.objectKey String O caminho completo do objeto no bucket.

  • Conteúdo de jsonPayload específico da operação

    A diferença entre as entradas de registro para diferentes operações em lote está no objeto de nível superior aninhado no jsonPayload. Apenas um dos objetos a seguir está disponível em uma determinada entrada de registro, correspondente à operação em lote específica realizada:

    • Excluir objeto (DeleteObject)

      jsonPayload:
{
"DeleteObject": {
  "objectMetadataBefore": {
    "gcsObject": {
      "bucket": "test-bucket",
      "generation": "1678912345678901",
      "objectKey": "test_object.txt"
    }
  }
  }
}

    • Colocar retenção de objeto (PutObjectHold)

      jsonPayload:
{
"PutObjectHold": {
  "objectMetadataBefore": {
    "gcsObject": {
      "bucket": "test-bucket",
      "generation": "1678912345678901",
      "objectKey": "test_object.txt"
    }
  },
  "temporaryHoldAfter": True,
  "eventBasedHoldAfter": True
}
}

    • Reescrever objeto (RewriteObject)

      jsonPayload:
{
"RewriteObject": {
  "objectMetadataBefore": {
    "gcsObject": {
      "bucket": "test-bucket",
      "generation": "1678912345678901",
      "objectKey": "test_object.txt"
    }
  },
  "kmsKeyVersionAfter": "projects/my-gcp-project/locations/us-central1/keyRings/my-keyring-01/cryptoKeys/my-encryption-key/cryptoKeyVersions/1"
}
}

    • Colocar metadados (PutMetadata)

      jsonPayload:
{
"PutMetadata": {
  "objectMetadataBefore": {
    "gcsObject": {
      "bucket": "test-bucket",
      "generation": "1678912345678901",
      "objectKey": "test_object.txt"
    }
  },
  "content_disposition_after": "attachment; filename=\"report_final.pdf\"",
  "content_encoding_after": "gzip",
  "content_language_after": "en-US",
  "content_type_after": "application/pdf",
  "cache_control_after": "public, max-age=3600",
  "custom_time_after": "2025-06-27T10:00:00Z",
  "custom_metadata_after": {
    "project": "marketing",
    "version": "2.0",
    "approvedBy": "Admin"
  }
}
}

    A tabela a seguir descreve os campos de registro específicos da operação:

    Campos de registro específicos da operação Tipo Descrição
    PutObjectHold Objeto Indica uma operação de retenção em um objeto.
    PutObjectHold.temporaryHoldAfter Booleano Se o valor for True, isso indica que uma retenção temporária foi aplicada ao objeto após a conclusão do job de operação em lote do Storage. Os valores válidos são True ou False.
    PutObjectHold.eventBasedHoldAfter Booleano Se o valor for True, isso indica que uma retenção baseada em eventos foi aplicada ao objeto após a conclusão do job de operação em lote do Storage. Os valores válidos são True ou False.
    RewriteObject Objeto Indica uma operação de reescrita em um objeto.
    RewriteObject.kmsKeyVersionAfter String A versão da chave do Cloud Key Management Service usada após o job de reescrita. O campo kmsKeyVersionAfter é preenchido se a chave de criptografia do objeto tiver sido alterada como resultado da reescrita. É um campo opcional, o que significa que ele pode não estar presente se a versão da chave do Cloud KMS permanecer inalterada após a reescrita.
    PutMetadata Objeto Indica uma operação de atualização de metadados em um objeto.
    PutMetadata.content_disposition_after String Especifica o valor do cabeçalho Content-Disposition após a conclusão do job PutMetadata. É um campo opcional e só é preenchido se a disposição do conteúdo tiver sido definida ou modificada.
    PutMetadata.content_encoding_after String Especifica o valor do cabeçalho Content-Encoding após a conclusão do job PutMetadata. É um campo opcional e só é preenchido se a codificação de conteúdo tiver sido definida ou modificada.
    PutMetadata.content_language_after String Especifica o valor do cabeçalho Content-Language após a conclusão do job PutMetadata. É um campo opcional e só é preenchido se o idioma do conteúdo tiver sido definido ou modificado.
    PutMetadata.content_type_after String Especifica o valor do cabeçalho Content-Type após a conclusão do job PutMetadata. É um campo opcional e só é preenchido se o tipo de conteúdo tiver sido definido ou modificado.
    PutMetadata.cache_control_after String Especifica o Cache-Control valor do cabeçalho após a conclusão do PutMetadata job. É um campo opcional e só é preenchido se o controle de cache tiver sido definido ou modificado.
    PutMetadata.custom_time_after String Especifica o valor do cabeçalho Custom-Time após a conclusão do job PutMetadata. É um campo opcional e só é preenchido se o horário personalizado tiver sido definido ou modificado.
    PutMetadata.custom_metadata_after Mapa (chave: string, valor: string) Contém um mapa de Custom- Metadata pares de chave-valor após a transformação. Esse campo inclui todos os metadados definidos pelo usuário que foram definidos ou modificados no objeto. Ele permite o armazenamento flexível de metadados adicionais.