啟用 Storage 移轉服務的記錄功能

本頁面說明如何設定 Storage 移轉服務,產生記錄動作和狀態的記錄資料。您可以使用 Cloud Logging 查看及分析記錄資料。

Storage 移轉服務可為所有移轉作業產生記錄資料。不過,系統不會記錄代理程式型移轉作業的 FIND 作業。

檔案系統移轉作業可另外設定檔案系統移轉記錄。

事前準備

開始前,請確認您有權存取 Cloud Logging。建議您使用 記錄檢視器 (roles/logging.viewer) Identity and Access Management 角色。如要進一步瞭解 Logging 存取權,請參閱「使用 IAM 控管存取權」。

下列文件說明如何驗證目前的存取權,以及如何授予 IAM 角色:

可記錄的動作

可記錄的動作如下:

  • FIND:尋找要執行的工作,例如列出目錄中的檔案、列出 bucket 中的物件,或列出 bucket 中的代管資料夾。不支援代理程式型移轉作業。
  • COPY::將檔案或物件複製到目的地 (Cloud Storage 或檔案系統)。
  • DELETE:刪除來源或目的地的檔案或物件。在兩個檔案系統之間移轉時,也會記錄從中繼 Cloud Storage bucket 刪除檔案的作業。

可記錄的狀態

您也可以為每項動作記錄一或多個下列狀態:

  • SUCCEEDED:動作成功。
  • FAILED:動作失敗。
  • SKIPPED:僅適用於 COPY 動作,且僅支援以代理程式為基礎的移轉工作。必須使用 gcloud 或 REST API 設定。這個狀態表示已略過複製作業。如果檔案已存在於接收端,且轉移工作設為忽略現有檔案,就會發生這種情況。

最佳做法

為 FIND 動作或 SUCCEEDED 狀態啟用記錄功能,可能會產生大量記錄資料。

您可以採用下列策略,減少儲存的記錄資料量:

  • 僅記錄失敗。如果不需要完整的物件層級法規遵循稽核,請將工作設為僅在發生失敗時,才寫入複製和刪除動作的記錄。

  • 使用指標資料監控處理量、位元組數,以及略過或失敗的物件。您可以建立圖表,並使用警告政策監控指標資料。如要查看可用指標清單,請參閱「監控移轉工作」。

  • 設定 Cloud Logging,捨棄價值低的大量記錄資料。如要進行這項變更,請更新專案中的記錄檔接收器,排除低價值的 Storage 移轉服務記錄資料。由於專案中的所有記錄檔接收器都會評估所有記錄項目,因此您可能需要更新多個記錄檔接收器。

    使用下列排除篩選器,排除記錄成功動作的 Storage 移轉服務記錄項目:

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

    如要瞭解如何尋找及修改記錄檔接收器,請參閱「將記錄檔轉送至支援的目的地」。

啟用記錄功能

如要設定 Storage 移轉服務來產生記錄資料,請指定要記錄的動作和狀態。

gcloud CLI

使用 gcloud transfer jobs create 建立轉移工作時,請使用下列旗標啟用記錄功能:

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

每個旗標至少須指定一個值。您只能為無代理程式移轉作業新增 find 至 --log-actions,並為代理程式移轉作業新增 skipped 至 --log-action-states,兩者無法在同一項工作中合併。

REST

如要建立記錄設定,請搭配使用 transferJobs.create 和 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/"
    }
  }
}

如要透過代理執行移轉作業,請從 logActions 中省略 "FIND";您也可以選擇在 logActionStates 中加入 "SKIPPED"。

調整 loggingConfig,納入要記錄的特定 logActions 和 logActionStates。舉例來說,如要在複製和尋找動作失敗時記錄,請提供下列 loggingConfig:

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

更新記錄設定

gcloud CLI

如要更新現有工作的記錄設定,請使用 gcloud transfer jobs update 指令和適當的旗標:

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

如要停用這項工作的記錄功能,請指定 --clear-log-config:

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

REST

如要更新現有移轉工作的記錄設定,請使用 transferJobs.patch 和 LoggingConfig:

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

updateTransferJobFieldMask 會指定這項要求中要更新的欄位,且為必填。

如要停用這項工作的記錄功能,請傳送 loggingConfig,並將 logActions 和 logActionStates 設為空白清單:

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

查看記錄

如要查看移轉記錄,請按照下列步驟操作:

Google Cloud 控制台

  1. 前往 Google Cloud 導覽選單 ,然後依序選取 「Logging」>「Logs Explorer」 :

    前往「Logs Explorer」

  2. 選取 Google Cloud 專案。

  3. 如要篩選記錄,只顯示 Storage 移轉服務項目,請在查詢欄位中輸入 storage_transfer_job,然後按一下「Run query」(執行查詢)。

  4. 在「Query results」(查詢結果) 窗格中,按一下「Edit time」(編輯時間),變更要傳回結果的時間範圍。

如要進一步瞭解如何使用 Logs Explorer,請參閱「使用 Logs Explorer」。

gcloud CLI

如要使用 gcloud CLI 搜尋 Storage 移轉服務記錄,請使用 gcloud logging read 指令。

指定篩選器,將結果限制為 Storage 移轉服務記錄。

gcloud logging read "resource.type=storage_transfer_job"

Cloud Logging API

使用 entries.list Cloud Logging API 方法。

如要篩選結果,只納入 Storage 移轉服務相關項目,請使用 filter 欄位。以下是 JSON 要求物件範例。

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

移轉記錄格式

以下各節說明 Storage 移轉服務記錄的欄位。

所有 Storage 移轉服務專屬欄位都包含在 jsonPayload 物件中。

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

COPY和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"
  }
}
}
記錄欄位 說明
@type 這個值一律為 type.googleapis.com/google.storagetransfer.logging.TransferActivityLog。
action

說明這項特定工作的動作。可以是下列其中一項:

  • FIND:尋找要執行的工作,例如列出目錄中的檔案或 bucket 中的物件。不適用於代理程式型移轉作業。
  • COPY:將檔案或物件複製到目的地 (Cloud Storage 或檔案系統)。
  • DELETE:刪除來源、目的地或中介 bucket 中的檔案或物件。
findAction

指定尋找動作的主體是物件或代管資料夾。

completeTime 作業完成的時間戳記 (符合 ISO 8601 標準)。
destinationContainer

僅適用於 FIND 作業。系統不會記錄代理程式型移轉作業的 FIND 作業。

這項轉移作業的目的地容器。包含兩個子欄位:

  • gcsBucket.bucket:目的地 Cloud Storage bucket 名稱。
  • type:一律GCS。
destinationObject

僅適用於 COPY 和 DELETE 作業。

目的地物件的相關資訊。包含兩個子欄位:

  • gcsObject、gcsManagedFolder 或 posixFile 其中之一,視目的地而定。所有選項都包含多個子欄位,用於指定名稱、位置、日期/時間資訊,以及物件或檔案的雜湊。
  • type 是 GCS 或 POSIX_FS 之一。

例如:

"destinationObject": {
  "type": "POSIX_FS",
  "posixFile": {
    "crc32c": "0",
    "path": "/tmp/data/filename.txt",
    "lastModifiedTime": "2022-09-22T04:33:45Z"
  }
}
operation 完整的 transferOperations 名稱。
sourceContainer

僅適用於 FIND 作業。系統不會記錄代理程式型移轉作業的 FIND 作業。

這項移轉作業的來源容器。包含兩個子欄位:

  • 指定來源位置的項目。欄位會根據來源類型命名。可能欄位如下。
    • awsS3Bucket.bucket:AWS S3 儲存貯體名稱。
    • azureBlobContainer:包含子欄位 account 和 container,兩者共同定義 Microsoft Azure Blob 儲存體 URI。
    • gcsBucket.bucket:Cloud Storage bucket 名稱。
    • httpManifest.url:網址清單的網址,指定要從 HTTP(S) 伺服器下載的公開檔案。
  • type 是 AWS_S3、AZURE_BLOB、GCS 或 HTTP。

例如:

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

僅適用於 COPY 和 DELETE 作業。

來源物件的相關資訊。包含兩個子欄位:

  • 來源物件主機專屬的項目。這個欄位會根據來源類型命名,並包含中繼資料的子欄位。可能欄位如下。
    • awsS3Object:AWS S3 物件。
    • awsS3CompatibleObject:與 S3 相容的儲存空間中的物件。
    • azureBlob:Azure Blob 儲存體中的檔案。
    • gcsObject:Cloud Storage 物件。
    • gcsManagedFolder:Cloud Storage 代管資料夾。
    • hdfsFile:HDFS 中的檔案。
    • httpFile:由網址清單指定的檔案。
    • posixFile:POSIX 檔案系統中的檔案。
  • type 為 AWS_S3、AWS_S3_COMPATIBLE、AZURE_BLOB、GCS、HDFS、HTTP 或 POSIX_FS。

例如:

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

動作狀態。如果 status.statusCode 為 OK,表示動作成功。否則,動作會失敗。只有在狀態並非 OK 時,系統才會填入 status.errorType 和 status.errorMessage 欄位。

此外,頂層 resource 欄位包含下列欄位。

"resource": {
  "labels": {
    "job_id": "transferJobs/7876027868280507149",
    "project_id": "my-project-id"
  },
  "type": "storage_transfer_job"
}
記錄欄位 說明
resource.labels.job_id 這項記錄所屬的 Storage 移轉服務工作名稱。
resource.labels.project_id 這項移轉作業的 Google Cloud 專案 ID。