Abilita la registrazione per Storage Transfer Service

Questa pagina descrive come configurare Storage Transfer Service per generare dati di log che registrano azioni e stati. Puoi visualizzare e analizzare i dati di log utilizzando Cloud Logging.

Storage Transfer Service può generare dati di log per tutti i trasferimenti. Tuttavia, le operazioni FIND non vengono registrate per i trasferimenti basati su agenti.

I trasferimenti del file system possono anche configurare i log di trasferimento del file system.

Prima di iniziare

Prima di iniziare, verifica di avere accesso a Cloud Logging. Ti consigliamo il ruolo Identity and Access Management Visualizzatore log (roles/logging.viewer). Per saperne di più sull'accesso a Logging, consulta Controllo dell'accesso con IAM.

I seguenti documenti descrivono come verificare l'accesso corrente e come concedere i ruoli IAM:

Azioni registrabili

È possibile registrare le seguenti azioni:

  • FIND: ricerca del lavoro da svolgere, ad esempio l'elenco dei file in una directory, l'elenco degli oggetti in un bucket o l'elenco delle cartelle gestite in un bucket. Non supportato per i trasferimenti basati su agenti.
  • COPY: copia dei file o degli oggetti nella destinazione (Cloud Storage o un file system).
  • DELETE: eliminazione di file o oggetti nell'origine o nella destinazione. Per i trasferimenti tra due file system, registra anche l'eliminazione dei file dal bucket Cloud Storage intermedio.

Stati registrabili

Per ogni azione, puoi anche registrare uno o più dei seguenti stati:

  • SUCCEEDED: l'azione è stata eseguita correttamente.
  • FAILED: l'azione non è riuscita.
  • SKIPPED: si applica solo all'azione COPY ed è supportato solo per i job di trasferimento basati su agenti. Deve essere impostato utilizzando gcloud o l'API REST. Questo stato indica che la copia è stata ignorata. Questo accade quando il file esiste già nel sink e il job di trasferimento è configurato per ignorare i file esistenti.

Best practice

L'abilitazione del logging per l'azione FIND o per lo stato SUCCEEDED può comportare un volume elevato di dati di log.

Puoi utilizzare le seguenti strategie per ridurre il volume dei dati di log archiviati:

  • Registra solo gli errori. Se non hai bisogno di un audit di conformità completo a livello di oggetto, configura il job in modo che scriva i log solo per le azioni di copia ed eliminazione e solo quando si verifica un errore.

  • Utilizza i dati delle metriche per monitorare la velocità effettiva, il conteggio dei byte e gli oggetti ignorati o non riusciti. Puoi creare grafici e monitorare i dati delle metriche utilizzando una policy di avviso. Per un elenco delle metriche disponibili, consulta Monitora i job di trasferimento.

  • Configura Cloud Logging per eliminare i dati di log ad alto volume e di basso valore. Per apportare questa modifica, aggiorna i sink di log nel tuo progetto in modo da escludere i dati dei log del servizio Storage Transfer Service di scarso valore. Poiché tutti i sink di log di un progetto valutano tutte le voci di log, potrebbe essere necessario aggiornare diversi sink di log.

    Utilizza il seguente filtro di esclusione per escludere le voci di log di Storage Transfer Service che registrano azioni riuscite:

    resource.type="storage_transfer_job" AND
    jsonPayload.status.statusCode="OK"
    

    Per informazioni su come trovare e modificare i sink di log, consulta Instrada i log verso destinazioni supportate.

Abilita il logging

Per configurare Storage Transfer Service in modo che generi dati di log, specifica le azioni e gli stati da registrare.

gcloud CLI

Quando crei un job di trasferimento con gcloud transfer jobs create, utilizza i seguenti flag per attivare il logging:

gcloud transfer jobs create SOURCE DESTINATION \
  --log-actions=copy,delete \
  --log-action-states=succeeded,failed

Devi specificare almeno un valore per ogni flag. Puoi aggiungere find a --log-actions solo per i trasferimenti senza agenti e skipped a --log-action-states solo per i trasferimenti basati su agenti. I due non possono essere combinati nello stesso job.

REST

Per creare una configurazione di logging, utilizza transferJobs.create con un LoggingConfig:

{
  "name": "transferJobs/myFirstTransfer",
  "status": "ENABLED",
  "projectId": "test-id-001",
  "loggingConfig": {
    "logActions": ["FIND", "DELETE", "COPY"],
    "logActionStates": ["SUCCEEDED", "FAILED"]
  },
  "transferSpec": {
    "gcsDataSource": {
      "bucketName": "source_bucket"
    },
    "gcsDataSink": {
      "bucketName": "destination_bucket",
      "path": "foo/bar/"
    }
  }
}

Per i trasferimenti basati su agenti, ometti "FIND" da logActions; facoltativamente, puoi includere "SKIPPED" in logActionStates.

Modifica loggingConfig per includere i valori logActions e logActionStates specifici da registrare. Ad esempio, per registrare i casi in cui le azioni di copia e ricerca non vanno a buon fine, fornisci il seguente loggingConfig:

"loggingConfig": {
  "logActions": ["COPY", "FIND"],
  "logActionStates": ["FAILED"]
}

Aggiorna una configurazione di logging

gcloud CLI

Per aggiornare la configurazione di logging di un job esistente, utilizza i flag appropriati con il comando gcloud transfer jobs update:

gcloud transfer jobs update NAME \
  --log-actions=copy,delete \
  --log-action-states=succeeded,failed

Per disattivare il logging per questo job, specifica --clear-log-config:

gcloud transfer jobs update NAME --clear-log-config

REST

Per aggiornare la configurazione di logging di un job di trasferimento esistente, utilizza transferJobs.patch con LoggingConfig:

{
  "projectId": "test-id-001",
  "transferJob": {
    "loggingConfig": {
      "logActions": ["FIND", "DELETE", "COPY"],
      "logActionStates": ["SUCCEEDED", "FAILED"]
    }
  },
  "updateTransferJobFieldMask": "loggingConfig"
}

updateTransferJobFieldMask specifica il campo che viene aggiornato in questa richiesta ed è obbligatorio.

Per disattivare il logging per questo job, invia un loggingConfig con elenchi vuoti per logActions e logActionStates:

{
  "projectId": "test-id-001",
  "transferJob": {
    "loggingConfig": {
      "logActions": [],
      "logActionStates": []
    }
  },
  "updateTransferJobFieldMask": "loggingConfig"
}

Visualizza i log

Per visualizzare i log dei trasferimenti:

Console Google Cloud

  1. Vai al menu di navigazione Google Cloud e selezionaLogging > Esplora log:

    Vai a Esplora log

  2. Seleziona un Google Cloud progetto.

  3. Per filtrare i log in modo da visualizzare solo le voci di Storage Transfer Service, digita storage_transfer_job nel campo della query e fai clic su Esegui query.

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

gcloud CLI

Per utilizzare gcloud CLI per cercare i log di Storage Transfer Service, utilizza il comando gcloud logging read.

Specifica un filtro per limitare i risultati ai log di Storage Transfer Service.

gcloud logging read "resource.type=storage_transfer_job"

API Cloud Logging

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

Per filtrare i risultati in modo da includere solo le voci relative a Storage Transfer Service, 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_transfer_job\""
}

Formato dei log di trasferimento

La sezione seguente descrive i campi dei log del servizio Storage Transfer Service.

Tutti i campi specifici di Storage Transfer Service sono contenuti in un oggetto jsonPayload.

FIND azioni

{
"jsonPayload": {
  "@type": "type.googleapis.com/google.storagetransfer.logging.TransferActivityLog",
  "action": "FIND",
  "completeTime": "2021-12-16T18:58:49.344509695Z",
  "destinationContainer": {
    "gcsBucket": {
      "bucket": "my-bucket-2"
    },
    "type": "GCS"
  },
  "operation": "transferOperations/transferJobs-7876027868280507149--3019866490856027148",
  "sourceContainer": {
    "gcsBucket": {
      "bucket": "my-bucket-1"
    },
    "type": "GCS"
  },
  "status": {
    "statusCode": "OK"
  }
}
}

COPY e DELETE azioni

{
"jsonPayload": {
  "@type": "type.googleapis.com/google.storagetransfer.logging.TransferActivityLog",
  "action": "COPY",
  "completeTime": "2021-12-16T18:59:00.510509049Z",
  "destinationObject": {
    "gcsObject": {
      "bucket": "my-bucket-2",
      "objectKey": "README.md"
    },
    "type": "GCS"
  },
  "operation": "transferOperations/transferJobs-7876027868280507149--3019866490856027148",
  "sourceObject": {
    "gcsObject": {
      "bucket": "my-bucket-1",
      "lastModifiedTime": "2021-12-07T16:41:09.456Z",
      "md5": "WgnCOIdfCXNTUDpQJSKb2w==",
      "objectKey": "README.md"
    },
    "type": "GCS"
  },
  "status": {
    "statusCode": "OK"
  }
}
}
Campo log Descrizione
@type Il valore è sempre type.googleapis.com/google.storagetransfer.logging.TransferActivityLog.
action

Descrive l'azione di questa particolare attività. Il valore sarà uno dei seguenti:

  • FIND: ricerca del lavoro da svolgere, ad esempio l'elenco dei file in una directory o l'elenco degli oggetti in un bucket. Non segnalato per i trasferimenti basati su agenti.
  • COPY: copia dei file o degli oggetti nella destinazione (Cloud Storage o un file system).
  • DELETE: eliminazione di file o oggetti nel bucket di origine, di destinazione o intermedio.
findAction

Specifica se l'oggetto dell'azione di ricerca era un oggetto o una cartella gestita.

completeTime Il timestamp conforme allo standard ISO 8601 in cui è stata completata l'operazione.
destinationContainer

Presente solo per le operazioni FIND. Le operazioni FIND non vengono registrate per i trasferimenti basati su agenti.

Il container di destinazione per questo trasferimento. Contiene due campi secondari:

  • gcsBucket.bucket: il nome del bucket Cloud Storage di destinazione.
  • type: sempre GCS.
destinationObject

Presente solo per le operazioni COPY e DELETE.

Informazioni sull'oggetto nella destinazione. Contiene due campi secondari:

  • Uno dei valori gcsObject, gcsManagedFolder o posixFile, a seconda della destinazione. Tutte le opzioni contengono più campi secondari che specificano nome, posizione, informazioni su data/ora e l'hash dell'oggetto o del file.
  • type è GCS o POSIX_FS.

Ad esempio:

"destinationObject": {
  "type": "POSIX_FS",
  "posixFile": {
    "crc32c": "0",
    "path": "/tmp/data/filename.txt",
    "lastModifiedTime": "2022-09-22T04:33:45Z"
  }
}
operation Il nome transferOperations completo.
sourceContainer

Presente solo per le operazioni FIND. Le operazioni FIND non vengono registrate per i trasferimenti basati su agenti.

Il container di origine per questo trasferimento. Contiene due campi secondari:

  • Una voce che specifica la località di origine. Il campo viene denominato in base al tipo di origine. I campi possibili sono i seguenti.
    • awsS3Bucket.bucket: il nome del bucket AWS S3.
    • azureBlobContainer: contiene i campi secondari account e container, che insieme definiscono l'URI di archiviazione BLOB di Microsoft Azure.
    • gcsBucket.bucket: il nome del bucket Cloud Storage.
    • httpManifest.url: l'URL di un elenco di URL che specifica i file disponibili pubblicamente da scaricare da un server HTTP(S).
  • type è uno dei valori AWS_S3, AZURE_BLOB, GCS o HTTP.

Ad esempio:

"sourceContainer": {
  "gcsBucket": {
    "bucket": "my-bucket-1"
  },
  "type": "GCS"
}
sourceObject

Presente solo per le operazioni COPY e DELETE.

Informazioni sull'oggetto di origine. Contiene due campi secondari:

  • Una voce specifica per l'host dell'oggetto di origine. Il campo è denominato in base al tipo di origine e contiene sottocampi per i metadati. I campi possibili sono i seguenti.
    • awsS3Object: un oggetto AWS S3.
    • awsS3CompatibleObject: un oggetto nello spazio di archiviazione compatibile con S3.
    • azureBlob: un file in Azure Blob Storage.
    • gcsObject: un oggetto Cloud Storage.
    • gcsManagedFolder: una cartella gestita di Cloud Storage.
    • hdfsFile: un file in HDFS.
    • httpFile: un file specificato da un elenco di URL.
    • posixFile: un file su un file system POSIX.
  • type è uno dei seguenti valori: AWS_S3, AWS_S3_COMPATIBLE, AZURE_BLOB, GCS, HDFS, HTTP o POSIX_FS.

Ad esempio:

"sourceObject": {
  "gcsObject": {
    "bucket": "my-bucket-1",
    "lastModifiedTime": "2021-12-07T16:41:09.456Z",
    "md5": "WgnCOIdfCXNTUDpQJSKb2w==",
    "objectKey": "README.md"
  },
  "type": "GCS"
}
status

Lo stato dell'azione. Se status.statusCode è OK, l'azione è riuscita. In caso contrario, l'azione non è andata a buon fine. I campi status.errorType e status.errorMessage vengono compilati solo se lo stato non è OK.

Inoltre, il campo resource di primo livello contiene i seguenti campi.

"resource": {
  "labels": {
    "job_id": "transferJobs/7876027868280507149",
    "project_id": "my-project-id"
  },
  "type": "storage_transfer_job"
}
Campo log Descrizione
resource.labels.job_id Il nome del job di Storage Transfer Service a cui appartiene questo log.
resource.labels.project_id L'ID progetto Google Cloud per questo trasferimento.