Cloud Logging per le operazioni batch di archiviazione

Questa pagina descrive come configurare e visualizzare i log delle operazioni batch di archiviazione utilizzando Cloud Logging. Un job di operazioni batch di archiviazione può essere configurato per generare voci di log di Cloud Logging per ogni job di trasformazione. Ogni voce di log corrisponde alla trasformazione tentata di un oggetto.

Le operazioni batch di archiviazione supportano il logging sia in Cloud Logging sia in Cloud Audit Logs di Cloud Storage. Sebbene entrambe le opzioni acquisiscano le azioni delle operazioni batch di archiviazione, ti consigliamo di utilizzare Cloud Logging. Cloud Logging fornisce una piattaforma centralizzata per l'analisi dei log, il monitoraggio in tempo reale e il filtraggio avanzato, offrendo una soluzione solida per la gestione e la comprensione dell'attività delle operazioni batch.

Prima di iniziare

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

Per verificare e concedere le autorizzazioni IAM:

• Visualizza l'accesso attuale per verificare l'accesso di ogni entità.
• Concedi un ruolo a entità pertinenti nel tuo progetto.

Informazioni sui dettagli di logging

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

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

• Stati registrati: 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 abilitare il logging, specifica le azioni e gli stati da registrare.

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

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

Visualizza i log

Per visualizzare i log delle operazioni batch di archiviazione:

gcloud logging read "resource.type=storage_batch_operations_job"

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

Formato dei log delle operazioni batch di archiviazione

Tutti i campi specifici delle operazioni batch di archiviazione sono contenuti in un oggetto jsonPayload. Sebbene il contenuto esatto di jsonPayload vari in base a il tipo di prestazione, esiste una struttura comune condivisa in tutte le TransformActivityLog voci. Questa sezione illustra i campi di log comuni e poi i campi specifici dell'operazione.

• 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 a ISO 8601 in cui l'operazione è stata completata.
  status	Oggetto	Fornisce informazioni sul risultato dell'attività dell'operazione batch.
  status.errorMessage	Stringa	Un messaggio di errore se l'operazione non riesce. Il messaggio di errore viene visualizzato solo se il valore di status.statusCode non è OK.
  status.errorType	Stringa	Il tipo di errore. Il tipo di errore viene visualizzato solo se il valore di 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 in cui la voce di log è stata ricevuta dal sistema di logging.
  resource	Oggetto	Informazioni sulla risorsa che ha generato la voce di log.
  resource.labels	Oggetto	Coppie chiave-valore che forniscono ulteriori informazioni identificative 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 all'operazione batch specifica eseguita:

  • Elimina oggetto (DeleteObject)

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

  • Inserisci 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 dell'operazione:

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