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 Cloud Logging per ogni job di trasformazione. Ogni voce di log corrisponde al tentativo di trasformazione di un oggetto.

Le operazioni batch di archiviazione supportano la registrazione sia in Cloud Logging che in Cloud Storage Cloud Audit Logs. 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 efficace 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 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 registrazione

Quando la registrazione è abilitata, le operazioni batch di archiviazione acquisiscono i seguenti dettagli:

  • Azione registrata: il valore dell'azione registrata è 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 la registrazione, 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 attivare la registrazione.

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 dare al tuo lavoro. Ad esempio, my-job.
  • MANIFEST_LOCATION è la posizione del tuo 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

Create a storage batch operations job 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 Google Cloud menu di navigazione e seleziona Logging > Esplora log :<br\></br\>

    Vai a Esplora log

  2. Seleziona un Google Cloud progetto.

  3. Nel menu Esegui l'upgrade, passa dal Visualizzatore log legacy a Esplora log.

  4. Per filtrare i log in modo da mostrare 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 della query, fai clic su Modifica data/ora per modificare il periodo di tempo per cui restituire i risultati.

Per ulteriori informazioni sull'utilizzo di Esplora log, vedi 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 oggetto richiesta JSON di esempio:

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

Dove:

my-project-name è il nome del tuo progetto.

Formato del 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 al tipo di lavoro, esiste una struttura comune condivisa in tutte le voci TransformActivityLog. Questa sezione descrive i campi di log comuni e poi quelli 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 allo standard ISO 8601 in cui è stata completata l'operazione.
    status Oggetto Fornisce informazioni sul risultato dell'attività di 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 di 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 il flusso 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 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 per l'operazione

    La differenza tra le voci di log per 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"
    }
  }
  }
}

    • Metti in attesa l'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 i 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 per l'operazione Tipo Descrizione
    PutObjectHold Oggetto Indica un'operazione di sospensione su un oggetto.
    PutObjectHold.temporaryHoldAfter Booleano Se il valore è True, indica che è stato applicato un blocco temporaneo all'oggetto dopo il completamento del job batch di operazioni 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 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 a seguito della riscrittura. È 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 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 dopo il completamento 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 dopo il completamento 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 dopo il completamento del job PutMetadata. È un campo facoltativo e viene compilato solo se il tipo di contenuto è 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. È 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 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.