Cloud Logging para operações em lote de armazenamento

É possível configurar e visualizar os registros de operações em lote do Storage no Cloud Logging para monitorar o progresso do job, filtrar eventos de transformação e resolver problemas de operações de objeto com falha. Quando ativada, essa geração de registros cria uma entrada para cada objeto que um job em lote tenta transformar.

Embora as operações em lote do Storage também enviem registros para os Registros de auditoria do Cloud, recomendamos usar o Cloud Logging para análise centralizada de registros e monitoramento em tempo real.

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 do Identity and Access Management Logs Viewer (roles/logging.viewer) 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 do Logging, consulte Controle de acesso com o IAM.

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

Entender os detalhes da geração de registros

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ções 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ções 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".

Como visualizar registros

Para ver os registros de operações 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 projeto do Cloud de Confiance

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

  4. Para filtrar seus registros e mostrar apenas entradas de operações em lote do Storage, 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 comando gcloud logging read.

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 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 das operações em lote do Storage

Todos os campos específicos de operações 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 entre todas as entradas TransformActivityLog. Nesta seção, descrevemos os campos de registro comuns e, em seguida, detalhamos os campos específicos da operação.

  • Campos de registro comuns

    Os seguintes campos 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 só vai aparecer se o valor de status.statusCode não for OK.
    status.errorType String O tipo de erro. O tipo de erro só aparece 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 registros.
    receiveTimestamp Carimbo de data/hora O carimbo de data/hora de quando a entrada de registro foi recebida pelo sistema de geração de registros.
    resource Objeto Informações sobre o recurso que gerou a entrada de registro.
    resource.labels Objeto Pares de chave-valor que fornecem mais informações de identificação sobre o recurso.
    resource.type String O tipo de recurso que gerou o registro.
    objectMetadataBefore Objeto Contém os 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 em que o objeto está.
    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ções 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 evento foi aplicada ao objeto após a conclusão do job de operações 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 será preenchido se a chave de criptografia do objeto tiver sido alterada como resultado da regravação. É 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 regravação.
    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 foi 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 foi 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 foi 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 foi definido ou modificado.
    PutMetadata.cache_control_after String Especifica o valor do cabeçalho Cache-Control após a conclusão do job PutMetadata. É 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 pares de chave-valor Custom- Metadata 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.