Cloud Logging per le operazioni batch di archiviazione

Puoi configurare e visualizzare i log delle operazioni batch di archiviazione in Cloud Logging per monitorare l'avanzamento dei job, filtrare gli eventi di trasformazione e risolvere i problemi relativi alle operazioni sugli oggetti non riusciti. Se abilitato, questo logging genera una voce per ogni oggetto che un job batch tenta di trasformare.

Sebbene le operazioni batch di archiviazione inviino log anche ad Cloud Audit Logs, consigliamo di utilizzare Cloud Logging per l'analisi centralizzata dei log e il monitoraggio in tempo reale.

Prima di iniziare

Verifica di avere accesso a Cloud Logging. Per utilizzare Cloud Logging, ti consigliamo di concedere il ruolo Identity and Access Management Logs Viewer (roles/logging.viewer). Il ruolo Identity and Access Management Logs Viewer (roles/logging.viewer) fornisce le autorizzazioni Identity and Access Management necessarie per visualizzare i dati di Cloud Logging. Per saperne di più sulle autorizzazioni di accesso a Logging, consulta Controllo dell'accesso con IAM.

Per verificare e concedere le autorizzazioni IAM, completa i seguenti passaggi:

Informazioni sui dettagli di logging

Quando il logging è abilitato, le operazioni batch di archiviazione acquisiscono i seguenti dettagli:

  • Azione registrabile: il valore dell'azione registrabile è sempre transform.

  • Stati registrabili: per ogni azione, puoi scegliere di registrare uno o entrambi i seguenti stati:

    • SUCCEEDED: l'azione è stata eseguita correttamente.
    • FAILED: l'azione non è riuscita.

Abilita il logging

Per attivare il logging, specifica le azioni e gli stati da registrare.

Riga di comando

Quando crei un job di operazioni batch di archiviazione con gcloud storage batch-operations jobs create, utilizza i flag --log-actions e --log-action-states per abilitare il logging.

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

Dove:

  • JOB_NAME è il nome che vuoi assegnare al job. Ad esempio, my-job.
  • MANIFEST_LOCATION è la posizione del manifest. Ad esempio, gs://my-bucket/manifest.csv.
  • LOG_ACTION_STATES è un elenco separato da virgole di stati da registrare. Ad esempio, succeeded,failed.

API REST

Crea un job di operazioni batch di archiviazione con un LoggingConfig.

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

Dove:

LOG_ACTION_STATES è un elenco separato da virgole di stati da registrare. Ad esempio, "SUCCEEDED","FAILED".

Visualizza i log

Per visualizzare i log delle operazioni batch di archiviazione:

Console

  1. Vai al menu di navigazione Google Cloud e seleziona Logging > Esplora log :<br\></br\>

    Vai a Esplora log

  2. Seleziona un Google Cloud progetto.

  3. Dal menu Esegui l'upgrade, passa da Visualizzatore log legacy a Esplora log.

  4. Per filtrare i log in modo da visualizzare solo le voci delle operazioni batch di archiviazione, digita storage_batch_operations_job nel campo della query e fai clic su Esegui query.

  5. Nel riquadro Risultati delle query, fai clic su Modifica data/ora per modificare il periodo di tempo per cui restituire i risultati.

Per saperne di più sull'utilizzo di Esplora log, consulta Utilizzo di Esplora log.

Riga di comando

Per utilizzare gcloud CLI per cercare i log delle operazioni batch di archiviazione, utilizza il comando gcloud logging read.

Specifica un filtro per limitare i risultati ai log delle operazioni batch di archiviazione.

gcloud logging read "resource.type=storage_batch_operations_job"

API REST

Utilizza il metodo dell'API Cloud Logging entries.list.

Per filtrare i risultati in modo da includere solo le voci relative alle operazioni batch di archiviazione, utilizza il campo filter. Di seguito è riportato un esempio di oggetto richiesta JSON:

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

Dove:

MY_PROJECT_NAME è il nome del progetto.

Formato dei log delle operazioni batch di archiviazione

Tutti i campi specifici delle operazioni batch di archiviazione sono contenuti in un oggetto jsonPayload. Sebbene i contenuti esatti di jsonPayload varino in base al tipo di prestazione, esiste una struttura comune condivisa tra tutte le voci TransformActivityLog. Questa sezione descrive i campi di log comuni e poi i campi specifici delle operazioni.

  • Campi di log comuni

    I seguenti campi vengono visualizzati in tutti i log:

    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"
//   }
// }
}

    La tabella seguente descrive ciascuno dei campi di log comuni:

    Campi di log comuni Tipo Descrizione
    @type Stringa Specifica il tipo di payload della voce di log e indica che il log rappresenta un TransformActivityLog per le operazioni batch di archiviazione.
    completeTime Timestamp Il timestamp conforme allo standard ISO 8601 in cui è stata completata l'operazione.
    status Oggetto Fornisce informazioni sul risultato dell'attività dell'operazione batch.
    status.errorMessage Stringa Un messaggio di errore se l'operazione non va a buon fine. Il messaggio di errore viene visualizzato solo se il valore status.statusCode non è OK.
    status.errorType Stringa Il tipo di errore. Il tipo di errore viene visualizzato solo se il valore status.statusCode non è OK.
    status.statusCode Stringa Il codice di stato dell'operazione. L'operazione ha esito positivo se il valore è OK; qualsiasi altro valore indica un errore.
    logName Stringa Il nome completo della risorsa del log, che indica il progetto e lo stream di log.
    receiveTimestamp Timestamp Il timestamp di ricezione della voce di log da parte del sistema di logging.
    resource Oggetto Informazioni sulla risorsa che ha generato la voce di log.
    resource.labels Oggetto Coppie chiave-valore che forniscono informazioni identificative aggiuntive sulla risorsa.
    resource.type Stringa Il tipo di risorsa che ha generato il log.
    objectMetadataBefore Oggetto Contiene i metadati dell'oggetto prima del tentativo di operazione batch.
    objectMetadataBefore.gcsObject Oggetto Dettagli sull'oggetto.
    objectMetadataBefore.gcsObject.bucket Stringa Il nome del bucket in cui si trova l'oggetto.
    objectMetadataBefore.gcsObject.generation Stringa Il numero di generazione dell'oggetto prima dell'operazione.
    objectMetadataBefore.gcsObject.objectKey Stringa Il percorso completo dell'oggetto all'interno del bucket.

  • Contenuti jsonPayload specifici dell'operazione

    La differenza tra le voci di log per le diverse operazioni batch risiede nell'oggetto di primo livello nidificato all'interno di jsonPayload. In una determinata voce di log è disponibile solo uno dei seguenti oggetti, corrispondente alla specifica operazione batch eseguita:

    • Elimina oggetto (DeleteObject)

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

    • Imposta blocco oggetto (PutObjectHold)

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

    • Riscrivi oggetto (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"
}
}

    • Inserisci metadati (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"
  }
}
}

    La tabella seguente descrive i campi di log specifici per l'operazione:

    Campi di log specifici per l'operazione Tipo Descrizione
    PutObjectHold Oggetto Indica un'operazione di blocco su un oggetto.
    PutObjectHold.temporaryHoldAfter Booleano Se il valore è True, significa che è stato applicato un blocco temporaneo all'oggetto dopo il completamento del job di operazioni batch di archiviazione. I valori validi sono True o False.
    PutObjectHold.eventBasedHoldAfter Booleano Se il valore è True, significa che è stato applicato un blocco basato su eventi all'oggetto dopo il completamento del job di operazioni batch di archiviazione. I valori validi sono True o False.
    RewriteObject Oggetto Indica un'operazione di riscrittura su un oggetto.
    RewriteObject.kmsKeyVersionAfter Stringa La versione della chiave Cloud Key Management Service utilizzata dopo il job di riscrittura. Il campo kmsKeyVersionAfter viene compilato se la chiave di crittografia dell'oggetto è cambiata in seguito alla riscrittura. Si tratta di un campo facoltativo, il che significa che potrebbe non essere presente se la versione della chiave Cloud KMS è rimasta invariata dopo la riscrittura.
    PutMetadata Oggetto Indica un'operazione di aggiornamento dei metadati su un oggetto.
    PutMetadata.content_disposition_after Stringa Specifica il valore dell'intestazione Content-Disposition dopo il completamento del job PutMetadata. Si tratta di un campo facoltativo che viene compilato solo se la disposizione dei contenuti è stata impostata o modificata.
    PutMetadata.content_encoding_after Stringa Specifica il valore dell'intestazione Content-Encoding dopo il completamento del job PutMetadata. Si tratta di un campo facoltativo che viene compilato solo se la codifica dei contenuti è stata impostata o modificata.
    PutMetadata.content_language_after Stringa Specifica il valore dell'intestazione Content-Language dopo il completamento del job PutMetadata. Si tratta di un campo facoltativo che viene compilato solo se la lingua dei contenuti è stata impostata o modificata.
    PutMetadata.content_type_after Stringa Specifica il valore dell'intestazione Content-Type dopo il completamento del job PutMetadata. Si tratta di un campo facoltativo che viene compilato solo se il tipo di contenuti è stato impostato o modificato.
    PutMetadata.cache_control_after Stringa Specifica il valore dell'intestazione Cache-Control dopo il completamento del job PutMetadata. Si tratta di un campo facoltativo che viene compilato solo se il controllo della cache è stato impostato o modificato.
    PutMetadata.custom_time_after Stringa Specifica il valore dell'intestazione Custom-Time dopo il completamento del job PutMetadata. Si tratta di un campo facoltativo che viene compilato solo se l'ora personalizzata è stata impostata o modificata.
    PutMetadata.custom_metadata_after Mappa (chiave: stringa, valore: stringa) Contiene una mappa di coppie chiave-valore Custom- Metadata dopo la trasformazione. Questo campo include tutti i metadati definiti dall'utente impostati o modificati nell'oggetto. Consente l'archiviazione flessibile di metadati aggiuntivi.