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 IAM (Identity and Access Management) Visualizzatore log (roles/logging.viewer). Per ulteriori informazioni 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: ricerca di lavoro da svolgere, ad esempio elencare i file in una directory, elencare gli oggetti in un bucket o elencare le cartelle gestite in un bucket. Non supportato per i 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 è riuscita.
  • 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 del logging per l'azione FIND o per lo stato SUCCEEDED può comportare 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 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, 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 che ignori i dati di log a volume elevato e di basso valore. Per apportare questa modifica, aggiorna i sink di log nel tuo progetto in modo da 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 più 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 il logging:

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 in modo da includere i 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 gcloud transfer jobs update comando:

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

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

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

Per disabilitare 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 di trasferimento:

Google Cloud Console

  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. Dal menu Esegui l'upgrade, passa da Visualizzatore log legacy a Esplora log.

  4. Per filtrare i log in modo da mostrare 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 il quale restituire i risultati.

Per ulteriori informazioni 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 gcloud logging read comando.

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 entries.list metodo dell'API Cloud Logging.

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 di richiesta JSON di esempio.

{
"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 per i log di Storage Transfer Service.

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

Azioni FIND 

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

Azioni COPY e DELETE

{
  "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: ricerca di lavoro da svolgere, ad esempio elencare i file in una directory o elencare gli oggetti in un bucket. Non viene indicato per i trasferimenti basati su agenti.
  • COPY: copia di file o oggetti in Cloud Storage.
  • DELETE: eliminazione di file o oggetti nell'origine, destinazione o nel bucket intermedio.
findAction

Specifica se l'oggetto dell'azione di ricerca era un oggetto o una cartella gestita.
completeTime Il timestamp conforme a ISO 8601 in cui l'operazione è stata completata.
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 sotto-campi:

  • 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 sotto-campi:

  • Uno tra gcsObject, gcsManagedFolder, o posixFile, a seconda della destinazione. Tutte le opzioni contengono più sotto-campi che specificano il nome, la località, le 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 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 sotto-campi:

  • 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 sotto-campi 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 è 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 sotto-campi:

  • Una voce specifica per l'host dell'oggetto di origine. Il campo viene denominato in base al tipo di origine e contiene i sotto-campi per i metadati. I campi possibili sono i seguenti.
    • awsS3Object: un oggetto AWS S3.
    • azureBlob: un file in Archiviazione BLOB di Azure.
    • 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 è AWS_S3, AZURE_BLOB, GCS, 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 è riuscita. 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.