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 dei 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 attuale e come concedere i ruoli IAM:

Azioni registrabili

È possibile registrare le seguenti azioni:

  • FIND: trovare il lavoro da svolgere, ad esempio elencare i file in una directory, gli oggetti in un bucket o le cartelle gestite in un bucket. Non supportato per trasferimenti basati su agenti.
  • COPY: Copia di file o oggetti in Cloud Storage.
  • 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. Ciò si verifica quando il file esiste già nel sink e il job di trasferimento è configurato per ignorare i file esistenti.

Best practice

L'abilitazione della registrazione per l'azione FIND o per lo stato SUCCEEDED può generare un volume elevato di dati di log, il che potrebbe influire sui costi di Cloud Logging.

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

  • Registra solo gli errori. Se non è necessario l'audit completo della conformità a livello di oggetto, configura il job in modo che scriva i log solo per le azioni di copia ed eliminazione e solo in caso di errore.

  • Utilizza i dati delle metriche per monitorare il throughput, i conteggi 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 Storage Transfer Service.

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

    Utilizza il seguente filtro di esclusione per escludere le voci di log di Storage Transfer Service che registrano le 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 abilitare la registrazione:

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

Devi specificare almeno un valore per ogni flag.

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", "SKIPPED"], #SKIPPED is only supported for agent-based transfers
  },
  "transferSpec": {
      "awsS3DataSource": {
          "bucketName": "AWS_SOURCE_NAME",
          "awsAccessKey": {
              "accessKeyId": "AWS_ACCESS_KEY_ID",
              "secretAccessKey": "AWS_SECRET_ACCESS_KEY"
          }
      },
      "gcsDataSink": {
           "bucketName": "destination_bucket",
           "path": "foo/bar/"
      },
   }
}

Modifica loggingConfig per includere logActions e logActionStates specifici da registrare. Ad esempio, per registrare quando 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,find \
  --log-action-states=succeeded,failed,skipped

Per disattivare la registrazione 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", "SKIPPED"], #SKIPPED is only supported for agent-based transfers
    },
  },
  "updateTransferJobFieldMask": "loggingConfig"
}

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

Per disattivare la registrazione 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 di trasferimento:

Console Google Cloud

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

    Vai a Esplora log

  2. Seleziona un Google Cloud progetto.

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

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

  5. Nel riquadro Risultati della 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, vedi 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 oggetto richiesta JSON di esempio.

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

Formato del log di trasferimento

La sezione seguente descrive i campi per i log di 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 attività specifica. Il valore sarà uno dei seguenti:

  • FIND: trovare il lavoro da svolgere, ad esempio elencare i file in una directory o gli oggetti in un bucket. Non segnalato per trasferimenti basati su agenti.
  • COPY: Copia di file o oggetti in Cloud Storage.
  • 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 contenitore 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 hash dell'oggetto o del file.
  • type è uno dei seguenti valori: 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 completo di transferOperations.
sourceContainer

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

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

  • Una voce che specifica la posizione 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 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 seguenti 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 viene denominato in base al tipo di origine e contiene i sottocampi per i metadati. I campi possibili sono i seguenti.
    • awsS3Object: un oggetto AWS S3.
    • azureBlob: un file in Azure Blob Storage.
    • gcsObject: un oggetto Cloud Storage.
    • gcsManagedFolder: una cartella gestita di Cloud Storage.
    • httpFile: Un file specificato da un elenco di URL.
    • posixFile: Un file su un file system POSIX.
  • type è uno dei seguenti valori: AZURE_BLOB, GCS, HTTP o POSIX_FS.AWS_S3

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 di primo livello resource 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 Storage Transfer Service a cui appartiene questo log.
resource.labels.project_id L'ID progetto Google Cloud per questo trasferimento.