批次追溯轉送記錄項目

您可以將儲存在 Cloud Logging 記錄檔 bucket 的記錄項目，複製到 Cloud Storage bucket，以便進行安全性稽核、自訂資料分析，或封存歷來記錄項目。複製作業不會破壞資料，記錄項目會保留在來源記錄檔 bucket 中，而且您可以跨不同 Google Cloud 專案複製。

複製作業會使用 gcloud CLI，追溯轉送現有的記錄項目。相較之下，「接收器」會在相符的記錄項目送達時，自動即時轉送，但無法轉送在接收器建立前儲存的記錄項目。

限制

複製記錄項目時，請注意下列限制：

  • 您只能將記錄項目複製到未設定 Rapid Storage 的 Cloud Storage bucket，無法使用其他目的地。

  • 您無法從已設定客戶自行管理加密金鑰 (CMEK) 的記錄檔 bucket 複製記錄項目。

事前準備

開始複製記錄項目之前，請先完成下列步驟：

  • 如要取得複製記錄項目所需的權限，請要求管理員在包含複製來源記錄檔 bucket 的專案中，授予您下列 IAM 角色：

  • 如要取得將記錄項目寫入 Cloud Storage 所需的權限，請要求管理員針對包含 Cloud Storage bucket 的專案，授予您 Storage 物件建立者 (roles/storage.objectCreator) IAM 角色。

複製記錄項目

Logging 只會複製複製作業開始時，儲存在記錄檔 bucket 中的記錄項目。複製作業開始後，儲存在記錄檔 bucket 的記錄項目不會複製到 Cloud Storage。

如要將記錄項目複製到 Cloud Storage，您必須瞭解下列資訊：

如要複製記錄項目，請執行 gcloud logging copy 指令：

gcloud logging copy LOG_BUCKET_ID storage.googleapis.com/CLOUD_STORAGE_BUCKET_NAME \
--location=LOCATION --log-filter='FILTER' --project=PROJECT_ID

執行上述指令前，請先完成下列事項：

  • 將 LOG_BUCKET_ID 替換為記錄檔 bucket 的名稱。
  • 請將 CLOUD_STORAGE_BUCKET_NAME 改成您的 Cloud Storage bucket 名稱。
  • 將 LOCATION 替換為記錄檔 bucket 的位置。

  • (選用)：將 FILTER 替換為篩選器，定義要複製哪些記錄項目。

    如果省略 --log-filter 旗標，記錄檔 bucket 中的所有記錄項目都會複製到 Cloud Storage bucket。

  • 將 PROJECT_ID 替換為 Google Cloud 專案 ID。如果有效的 gcloud CLI 設定已設為正確的 Google Cloud 專案，則可省略這個旗標。

指令範例：

gcloud logging copy my-log-bucket storage.googleapis.com/my-gcs-bucket \
--location=global --log-filter='timestamp > "2024-07-18T10:00:00.0Z"' \
--project=my-project

這個指令會建立長時間執行的作業，在背景執行，並傳回複製作業的名稱和記錄檔 bucket 的位置：

name: projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID

複製作業的位置與複製來源記錄檔 bucket 的位置相同。

查看及管理複製作業

您可以使用 gcloud logging operations 指令查看及管理複製作業，包括列出、查看及取消作業。

執行下列指令時，必須指定作業位置。使用記錄檔 bucket 的位置。如要瞭解如何找出記錄檔 bucket 的位置，請參閱「查看 bucket 的詳細資料」。

列出複製作業

您可以列出最近的複製作業，包括已排定、執行中、已完成、失敗和已取消的作業。最近的複製作業會顯示在結果中，最長可保留 30 天 (從結束時間算起)。

如要列出複製作業，請執行下列指令：

gcloud logging operations list --location=LOCATION \
--operation-filter=request_type=CopyLogEntries \
--project=PROJECT_ID

執行上述指令前，請先完成下列事項：

  • 將 LOCATION 替換為要複製的記錄檔 bucket 位置。
  • 將 PROJECT_ID 替換為 Google Cloud 專案 ID。

這個指令會傳回長時間執行的作業的相關資訊，包括作業 ID：

projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID

查看複製作業的狀態

您可以擷取複製作業的狀態和其他中繼資料，包括：

  • startTime：表示作業建立時間的時間戳記。
  • endTime：表示作業完成的時間戳記。
  • state：作業狀態 (已排定、執行中、已取消、失敗或成功)。
  • cancellation：使用者是否已要求取消作業。
  • progress：作業的預估進度 (0-100%)。
  • destination： 作業要將記錄項目複製到哪個 Cloud Storage bucket。
  • filter：指定要複製哪些記錄項目的篩選器。
  • name：作業複製 記錄項目的來源記錄檔 bucket 名稱。
  • logEntriesCopiedCount：作業成功複製到 Cloud Storage bucket 的記錄項目數量。

請注意，並非所有列出的中繼資料欄位都適用於每項複製作業。舉例來說，如果複製作業仍在執行中，endTime 中繼資料就不會套用至該作業。再舉一個例子，如果在執行 gcloud logging copy 指令時未使用 --log-filter=FILTER 旗標，則 filter 中繼資料不會套用至作業。

如要擷取複製作業的相關資訊，請執行下列指令：

gcloud logging operations describe OPERATION_ID \
--location=LOCATION --project=PROJECT_ID

執行上述指令前，請先完成下列事項：

  • 將 OPERATION_ID 替換為作業 ID。
  • 將 LOCATION 替換為要複製的記錄檔 bucket 位置。
  • 將 PROJECT_ID 替換為 Google Cloud 專案 ID。

指令會傳回複製作業的中繼資料。例如，以下是執行中作業的輸出內容：

done: false
metadata:
  `@type`: type.googleapis.com/google.logging.v2.CopyLogEntriesMetadata
  progress: 75
  destination: storage.googleapis.com/CLOUD_STORAGE_BUCKET_NAME
  source: projects/PROJECT_ID/locations/LOCATION/buckets/LOG_BUCKET_ID
  verb: copy
  startTime: `2024-05-23T10:52:40.039751Z`
  state: OPERATION_STATE_RUNNING
name: projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID

取消複製作業

您可以取消進行中的複製作業。如果取消複製作業，在取消作業前複製的所有記錄項目，都會保留在 Cloud Storage bucket 中。

取消複製作業後，Logging 會先完成所有進行中的程序，再完成取消作業。因此，在您取消作業後，可能仍有部分記錄項目會複製到 Cloud Storage。

如要取消複製作業，請執行下列指令：

gcloud logging operations cancel OPERATION_ID \
--location=LOCATION --project=PROJECT_ID

執行上述指令前，請先完成下列事項：

  • 將 OPERATION_ID 替換為作業 ID。
  • 將 LOCATION 替換為要複製的記錄檔 bucket 位置。
  • 將 PROJECT_ID 替換為 Google Cloud 專案 ID。

在 Cloud Storage 查看記錄項目

如要瞭解如何查看及解讀複製到 Cloud Storage 的記錄項目，請參閱「查看轉送至 Cloud Storage 的記錄項目」。

配額與限制

無論複製的資料量多寡，所有複製作業都至少需要一小時才能完成。

如要複製大量資料 (例如 PB 級)，請使用 --log-filter 旗標中的 timestamp 欄位，將複製作業拆分為多項作業。

複製指令無法複製保留期限已過的記錄項目。

疑難排解

本節說明如何排解複製記錄項目時發生的錯誤。

無法寫入匯出資料

使用 gcloud logging operations describe 查看複製作業的狀態時，作業可能會顯示下列錯誤：

done: true
error:
  code: 7
  message: Failed to write export data to the destination Cloud Storage bucket.

如果 Logging 無法在目的地 Cloud Storage bucket 中寫入或完成記錄檔，就會發生這項錯誤。作業期間寫入匯出檔案可能會失敗，原因如下：

  • VPC Service Controls service perimeter 會封鎖傳送至目的地 Cloud Storage bucket 的要求。
  • 在作業執行期間，啟動複製作業的帳戶 IAM 權限遭到修改或撤銷。
  • 複製作業執行時間過長，導致授權憑證過期。
  • 目的地 Cloud Storage bucket 使用 CMEK，且 Cloud Key Management Service 金鑰已停用，或 Cloud Storage 服務代理缺少加密權限。
  • 寫入重試作業嘗試覆寫無法取代的現有檔案。舉例來說，如果匯出批次在暫時延遲後重試，或複製作業重新啟動，重試作業可能會嘗試覆寫已建立的檔案。如果該檔案受到有效物件保留或鎖定資料保留政策保護，Cloud Storage 就會拒絕覆寫。
  • 目的地 bucket 已刪除、進入鎖定狀態，或專案超過資源配額。

請按照下列步驟解決這個問題：

  1. 查看 VPC Service Controls：如果貴組織使用 VPC Service Controls，請查看 Cloud 稽核記錄，瞭解 perimeter 拒絕情形 (cloudaudit.googleapis.com/data_access)。目的地 Cloud Storage bucket 的 perimeter 必須允許從執行複製作業的專案存取，或設定輸入和輸出規則。

  2. 驗證目的地 bucket 的 IAM 角色：啟動複製作業的帳戶必須具備目的地 bucket 的 Storage 物件建立者 (roles/storage.objectCreator) 角色。

  3. 驗證客戶自行管理的加密金鑰 (CMEK)：如果目的地 bucket 使用 CMEK 做為預設加密，請確認 Cloud KMS 金鑰已啟用，且 Cloud Storage 服務代理具備金鑰的 Cloud KMS CryptoKey 加密者/解密者 (roles/cloudkms.cryptoKeyEncrypterDecrypter) 角色。

  4. 將大型複製作業拆分為較短的時間間隔：複製大量記錄項目時，為避免逾時或憑證過期，請將作業拆分為較小的批次。如要將記錄項目拆分為批次，請使用 --log-filter 旗標中的 timestamp 欄位。

  5. 確認沒有物件保留或保留衝突：確認目的地 bucket 的目標路徑中，沒有受有效物件保留或鎖定保留政策保護的物件。