Logging für Storage Transfer Service aktivieren

Auf dieser Seite wird beschrieben, wie Sie den Storage Transfer Service so konfigurieren, dass Logdaten generiert werden, in denen Aktionen und Status aufgezeichnet werden. Sie können die Logdaten mit Cloud Logging aufrufen und analysieren.

Storage Transfer Service kann Logdaten für alle Übertragungen generieren. FIND-Vorgänge werden jedoch nicht für agentenbasierte Übertragungen protokolliert.

Für Dateisystemübertragungen können zusätzlich Übertragungslogs des Dateisystems konfiguriert werden.

Hinweis

Prüfen Sie zuerst, ob Sie Zugriff auf Cloud Logging haben. Wir empfehlen Identity and Access Management-Rolle Logbetrachter (roles/logging.viewer). Weitere Informationen zum Logging-Zugriff finden Sie unter Zugriffssteuerung mit IAM.

In den folgenden Dokumenten wird beschrieben, wie Sie Ihren aktuellen Zugriff überprüfen und IAM-Rollen gewähren:

Protokollierbare Aktionen

Folgende Aktionen können protokolliert werden:

  • FIND: Zu suchende Aufgaben finden, z. B. zum Auflisten von Dateien in einem Verzeichnis, zum Auflisten von Objekten in einem Bucket oder zum Auflisten von verwalteten Ordnern in einem Bucket. Wird bei agentenbasierten Übertragungen nicht unterstützt.
  • COPY: Dateien oder Objekte in Cloud Storage kopieren.
  • DELETE: Dateien oder Objekte an der Quelle oder am Ziel löschen. Bei Übertragungen zwischen zwei Dateisystemen wird auch das Löschen von Dateien aus dem Cloud Storage-Zwischen-Bucket protokolliert.

Protokollierbare Status

Für jede Aktion können Sie auch einen oder mehrere der folgenden Statuswerte aufzeichnen:

  • SUCCEEDED: Die Aktion wurde erfolgreich ausgeführt.
  • FAILED: Die Aktion ist fehlgeschlagen.
  • SKIPPED: Gilt nur für die COPY-Aktion und wird nur für agentenbasierte Übertragungsjobs unterstützt. Muss mit gcloud oder der REST API festgelegt werden. Dieser Status bedeutet, dass das Kopieren übersprungen wurde. Dieser Fehler tritt auf, wenn die Datei bereits im Senken-Dataset vorhanden ist und Ihr Übertragungsjob so konfiguriert ist, dass vorhandene Dateien ignoriert werden.

Best Practices

Wenn Sie die Protokollierung für die Aktion FIND oder den Status SUCCEEDED aktivieren, kann dies zu einem hohen Volumen an Logdaten führen, was sich auf Ihre Cloud Logging-Kosten auswirken kann.

Mit den folgenden Strategien können Sie das Volumen der gespeicherten Logdaten reduzieren:

  • Nur Fehler protokollieren. Wenn Sie keine vollständige Compliance-Prüfung auf Objektebene benötigen, konfigurieren Sie den Job so, dass Protokolle nur für Kopier- und Löschvorgänge und nur bei einem Fehler geschrieben werden.

  • Mit Messwertdaten können Sie den Durchsatz, die Anzahl der Byte und die übersprungenen oder fehlgeschlagenen Objekte überwachen. Sie können Diagramme erstellen und Messwertdaten mit einer Benachrichtigungsrichtlinie überwachen. Eine Liste der verfügbaren Messwerte finden Sie unter Storage Transfer Service.

  • Konfigurieren Sie Cloud Logging so, dass Logdaten mit hohem Volumen und geringem Wert verworfen werden. Um diese Änderung vorzunehmen, aktualisieren Sie die Logsinks in Ihrem Projekt, um Storage Transfer Service-Logdaten mit geringem Wert auszuschließen. Da alle Logsenken in einem Projekt alle Logeinträge auswerten, müssen Sie möglicherweise mehrere Logsenken aktualisieren.

    Verwenden Sie den folgenden Ausschlussfilter, um Storage Transfer Service-Logeinträge auszuschließen, in denen erfolgreiche Aktionen aufgezeichnet werden:

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

    Informationen zum Suchen und Ändern Ihrer Logsenken finden Sie unter Logs an unterstützte Ziele weiterleiten.

Logging aktivieren

Wenn Sie den Storage Transfer Service so konfigurieren möchten, dass Logdaten generiert werden, geben Sie die Aktionen und Statuswerte an, die protokolliert werden sollen.

gcloud-CLI

Wenn Sie einen Übertragungsjob mit gcloud transfer jobs create erstellen, verwenden Sie die folgenden Flags, um das Logging zu aktivieren:

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

Sie müssen für jedes Flag mindestens einen Wert angeben.

REST

Verwenden Sie zum Erstellen einer Logging-Konfiguration transferJobs.create mit einer 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/"
      },
   }
}

Passen Sie loggingConfig an, um die spezifischen logActions und logActionStates einzuschließen, die protokolliert werden sollen. Wenn Sie beispielsweise protokollieren möchten, welche Kopier- und Suchaktionen fehlschlagen, können Sie die folgende loggingConfig angeben:

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

Logging-Konfiguration aktualisieren

gcloud-CLI

Verwenden Sie die entsprechenden Flags mit dem Befehl gcloud transfer jobs update, um die Logging-Konfiguration eines vorhandenen Jobs zu aktualisieren:

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

Wenn Sie das Logging für diesen Job deaktivieren möchten, geben Sie --clear-log-config an:

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

REST

Verwenden Sie transferJobs.patch mit LoggingConfig, um die Logging-Konfiguration eines vorhandenen Übertragungsjobs zu aktualisieren:

{
  "projectId": "test-id-001",
  "transferJob": {
    "loggingConfig": {
       "logActions": ["FIND", "DELETE", "COPY"],
       "logActionStates": ["SUCCEEDED", "FAILED", "SKIPPED"], #SKIPPED is only supported for agent-based transfers
    },
  },
  "updateTransferJobFieldMask": "loggingConfig"
}

Der Wert updateTransferJobFieldMask gibt das Feld an, das in dieser Anfrage aktualisiert wird, und ist erforderlich.

Wenn Sie die Protokollierung für diesen Job deaktivieren möchten, senden Sie eine loggingConfig mit leeren Listen für logActions und logActionStates:

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

Logs ansehen

So rufen Sie Übertragungslogs auf:

Google Cloud Console

  1. Rufen Sie das Google Cloud-Navigationsmenü  auf und wählen Sie Logging > Log-Explorer aus:

    Zu „Log-Explorer“

  2. Wählen Sie ein Projekt in Google Cloud aus.

  3. Wechseln Sie im Menü Upgrade von Legacy-Loganzeige zu Log-Explorer.

  4. Wenn Sie Ihre Logs so filtern möchten, dass nur Storage Transfer Service-Einträge angezeigt werden, geben Sie in das Abfragefeld storage_transfer_job ein und klicken Sie auf Abfrage ausführen.

  5. Klicken Sie im Bereich Abfrageergebnisse auf Zeit bearbeiten, um den Zeitraum zu ändern, für den Ergebnisse zurückgegeben werden sollen.

Informationen zur Verwendung des Log-Explorers finden Sie unter Log-Explorer verwenden.

gcloud-CLI

Wenn Sie mit der gcloud CLI nach Storage Transfer Service-Logs suchen möchten, verwenden Sie den Befehl gcloud logging read.

Geben Sie einen Filter an, um Ihre Ergebnisse auf Storage Transfer Service-Logs zu beschränken.

gcloud logging read "resource.type=storage_transfer_job"

Cloud Logging API

Verwenden Sie die Cloud Logging API-Methode entries.list.

Verwenden Sie das Feld filter, um Ihre Ergebnisse so zu filtern, dass nur Einträge in Storage Transfer Service enthalten sind. Unten finden Sie ein Beispiel für ein JSON-Anfrageobjekt.

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

Format von Übertragungslogs

Im folgenden Abschnitt werden die Felder für Storage Transfer Service-Logs beschrieben.

Alle spezifischen Felder für Storage Transfer Service sind in einem jsonPayload-Objekt enthalten.

FIND Aktionen 

{
  "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- und DELETE-Aktionen

{
  "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"
    }
  }
}
Logfeld Beschreibung
@type Der Wert ist immer type.googleapis.com/google.storagetransfer.logging.TransferActivityLog
action

Beschreibt die Aktion dieser bestimmten Aufgabe. Beispiele:

  • FIND: Zu suchende Aufgaben finden, z. B. zum Auflisten von Dateien in einem Verzeichnis oder zum Auflisten von Objekten in einem Bucket. Wird nicht für agentenbasierte Übertragungen erfasst.
  • COPY: Dateien oder Objekte in Cloud Storage kopieren.
  • DELETE: Dateien oder Objekte an der Quelle, am Ziel oder im Zwischen-Bucket löschen.
findAction

Gibt an, ob das Ziel der Suchaktion ein Objekt oder ein verwalteter Ordner war.
completeTime Der ISO 8601-konforme Zeitstempel, zu dem der Vorgang abgeschlossen wurde.
destinationContainer

Nur für FIND-Vorgänge vorhanden. FIND-Vorgänge werden für agentenbasierte Transfers nicht protokolliert.

Der Zielcontainer für diese Übertragung. Enthält zwei untergeordnete Felder:

  • gcsBucket.bucket: Der Name des Cloud Storage-Ziel-Buckets.
  • type: Immer GCS.
destinationObject

Nur für COPY- und DELETE-Vorgänge vorhanden.

Informationen zum Objekt am Zielort. Enthält zwei untergeordnete Felder:

  • Je nach Zielort entweder gcsObject, gcsManagedFolder oder posixFile. Alle Optionen enthalten mehrere Unterfelder, in denen Name, Speicherort, Datums-/Uhrzeitinformationen und der Hash des Objekts oder der Datei angegeben sind.
  • type ist entweder GCS oder POSIX_FS.

Beispiel:

"destinationObject": {
  "type": "POSIX_FS",
  "posixFile": {
    "crc32c": "0",
    "path": "/tmp/data/filename.txt",
    "lastModifiedTime": "2022-09-22T04:33:45Z"
  }
}
operation Der vollständig qualifizierte transferOperations-Name.
sourceContainer

Nur für FIND-Vorgänge vorhanden. FIND-Vorgänge werden für agentenbasierte Transfers nicht protokolliert.

Der Quellcontainer für diese Übertragung. Enthält zwei untergeordnete Felder:

  • Ein Eintrag, der den Quellspeicherort angibt. Das Feld wird entsprechend dem Quelltyp benannt. Mögliche Felder:
    • awsS3Bucket.bucket: Der Name des AWS S3-Buckets.
    • azureBlobContainer: Enthält untergeordnete Felder account und container, die zusammen den Microsoft Azure Blob-Speicher-URI definieren.
    • gcsBucket.bucket: der Name des Cloud Storage-Buckets.
    • httpManifest.url: Die URL einer URL-Liste mit öffentlich verfügbaren Dateien, die von einem HTTP(S)-Server heruntergeladen werden können.
  • type ist wahlweise AWS_S3, AZURE_BLOB, GCS oder HTTP.

Beispiel:

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

Nur für COPY- und DELETE-Vorgänge vorhanden.

Informationen zum Quellobjekt. Enthält zwei untergeordnete Felder:

  • Ein Eintrag, der für den Host des Quellobjekts spezifisch ist. Das Feld wird entsprechend dem Quelltyp benannt und enthält Unterfelder für Metadaten. Mögliche Felder:
    • awsS3Object: Ein AWS-S3-Objekt.
    • azureBlob: Eine Datei in Azure Blob Storage.
    • gcsObject: Ein Cloud Storage-Objekt.
    • gcsManagedFolder: Ein verwalteter Cloud Storage-Ordner.
    • httpFile: Eine Datei, die durch eine URL-Liste angegeben wurde.
    • posixFile: Eine Datei in einem POSIX-Dateisystem.
  • type ist wahlweise AWS_S3, AZURE_BLOB, GCS, HTTP oder POSIX_FS.

Beispiel:

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

Der Status der Aktion. Wenn status.statusCode den Wert OK hat, war die Aktion erfolgreich. Andernfalls ist die Aktion fehlgeschlagen. Die Felder status.errorType und status.errorMessage werden nur ausgefüllt, wenn der Status nicht OK lautet.

Außerdem enthält das übergeordnete Feld resource die folgenden Felder.

"resource": {
  "labels": {
    "job_id": "transferJobs/7876027868280507149"
    "project_id": "my-project-id"
  },
  "type": "storage_transfer_job"
}
Logfeld Beschreibung
resource.labels.job_id Der Name des Storage Transfer Service-Jobs, zu dem dieses Log gehört.
resource.labels.project_id Die Google Cloud-Projekt-ID für diese Übertragung.