彙整機構和資料夾層級記錄，並將其轉送至支援的目的地

您可以在 Cloud Logging 中使用匯總接收器，將機構或資料夾中資源的記錄合併並轉送至集中位置。

事前準備

建立接收器前，請確認下列事項：

  • 您熟悉匯總接收器的行為。詳情請參閱「匯總接收器總覽」。

  • 您有 Google Cloud 資料夾或機構，且其中包含可在 Logs Explorer 中查看的記錄項目。

  • 您具備下列任一 IAM 角色，可從Google Cloud 組織或資料夾中將記錄項目傳送至其他位置。

    • 擁有者 (roles/owner)
    • 記錄管理員 (roles/logging.admin)
    • 記錄檔設定寫入者 (roles/logging.configWriter)

    這些角色包含的權限可讓您建立、刪除或修改接收器。如要瞭解如何設定 IAM 角色，請參閱 Logging 存取控管指南。

  • 匯總接收器的目的地存在，或您有權建立目的地。目的地可以位於任何 Google Cloud 專案和任何機構。如需支援的目的地清單和限制，請參閱「支援的目的地」。

    • 不支援區域端點：您無法指定區域服務端點 (REP)，例如 pubsub.LOCATION.rep.googleapis.com 做為目的地。您必須指定服務的全球端點，並提供完整合格的目的地路徑。詳情請參閱「目的地路徑格式」。

    • 不支援 Pub/Sub 傳輸中限制：請勿將記錄項目傳送至強制執行傳輸中限制的 Pub/Sub 主題。由於記錄檔接收器必須使用全域端點，因此記錄檔服務無法保證發布要求來自允許的區域，這會導致topic_region_not_allowed設定錯誤和記錄檔遭到捨棄。

  • 選取要使用的介面：

    控制台

    使用 Google Cloud 控制台存取 Google Cloud 服務和 API 時，不需要設定驗證。

    gcloud

    在 Google Cloud 控制台中啟用 Cloud Shell。

    啟用 Cloud Shell

    Google Cloud 控制台底部會開啟 Cloud Shell 工作階段，並顯示指令列提示。Cloud Shell 是已安裝 Google Cloud CLI 的殼層環境，並已設定適用於您目前專案的值。工作階段可能要幾秒鐘的時間才能初始化。

    REST

    如要在本機開發環境中使用本頁的 REST API 範例，請使用您提供給 gcloud CLI 的憑證。

      安裝 Google Cloud CLI。

      如果您使用外部識別資訊提供者 (IdP)，請先 使用聯合身分登入 gcloud CLI。

    詳情請參閱 Google Cloud 驗證說明文件中的「使用 REST 進行驗證」。

建立匯總接收器

如要設定匯總接收器，請建立接收器，然後授予接收器寫入目的地的權限。本節說明如何建立匯總接收器。如要瞭解如何授予接收器權限，請參閱本頁面「設定目的地權限」一節。

每個資料夾或機構最多可建立 200 個接收器。

控制台

如要為資料夾或機構建立匯總接收器，請按照下列步驟操作：

  1. 前往 Google Cloud 控制台的「Log Router」(記錄檔路由器) 頁面：

    前往「記錄檔路由器」

    如果您是使用搜尋列尋找這個頁面，請選取子標題為「Logging」的結果。

  2. 選取現有的資料夾或機構。

  3. 選取「建立接收器」。

  4. 在「接收器詳細資料」面板中，輸入下列詳細資料：

    • 接收器名稱：提供接收器的 ID。請注意，接收器建立後就無法重新命名，但可以刪除並建立新的接收器。

    • 接收器說明 (選填)：說明接收器的用途或用途。

  5. 在「選取接收器服務」選單中，選取目的地類型，然後完成對話方塊以指定目的地。您可以選取現有目的地或建立目的地。

    • 如果是攔截接收器，請選取「專案」Google Cloud ，然後輸入目的地專案的完整名稱 Google Cloud ：

      logging.googleapis.com/projects/DESTINATION_PROJECT_ID

    • 如果是非攔截接收器，請選取目的地，然後輸入目的地的完整名稱。系統支援下列目的地：

      • Google Cloud 專案

        logging.googleapis.com/projects/DESTINATION_PROJECT_ID

      • Cloud Logging 值區

        logging.googleapis.com/projects/DESTINATION_PROJECT_ID/locations/LOCATION/buckets/BUCKET_NAME

      • BigQuery 資料集

        輸入可寫入的資料集名稱。請勿輸入連結的 BigQuery 資料集名稱，因為這些資料集為唯讀。您可以使用分區資料表。

        bigquery.googleapis.com/projects/DESTINATION_PROJECT_ID/datasets/DATASET_ID

      • Cloud Storage bucket

        storage.googleapis.com/BUCKET_NAME

      • Pub/Sub 主題

        請勿輸入強制執行傳輸中限制的 Pub/Sub 主題名稱。

        pubsub.googleapis.com/projects/DESTINATION_PROJECT_ID/topics/TOPIC_ID

      • Splunk

        輸入 Splunk 服務的 Pub/Sub 主題。

  6. 在「選擇要納入接收器的記錄檔」面板中，選取要納入接收器的資源。

    • 如果是攔截接收器，請選取「攔截這個機構和所有子資源擷取的記錄」。

    • 如果是非攔截接收器，請選取「收錄這個資源和所有子資源擷取的記錄檔」。

  7. 在「Build inclusion filter」(建立「包含」篩選器) 欄位中，輸入篩選運算式，找出要納入的記錄項目。如未設定篩選器，所選資源的所有記錄項目都會轉送至目的地。

    舉例來說，您可能想建立篩選條件，將所有資料存取稽核記錄傳送至單一記錄值區。這個篩選器如下所示：

    LOG_ID("cloudaudit.googleapis.com/data_access") OR LOG_ID("externalaudit.googleapis.com/data_access")

    如需篩選器範例，請參閱「為匯總接收器建立篩選器」。

    請注意，篩選器的長度不得超過 20,000 個半形字元。

  8. 選用：如要確認輸入的篩選器正確無誤，請選取「預覽記錄」。系統會在新的分頁中開啟 Logs Explorer，並預先填入篩選條件。

  9. 選用：在「選擇要從接收器排除的記錄檔」面板中，執行下列操作：

    1. 在「排除篩選器名稱」欄位中輸入名稱。

    2. 在「建立排除篩選器」欄位中，輸入與要排除的記錄檔項目相符的篩選器運算式。您也可以使用 sample 函式選取要排除的部分記錄項目。

      舉例來說，如要排除特定專案的記錄項目，避免系統將這些項目傳送至目的地，請新增下列排除篩選器：

      logName:projects/PROJECT_ID

      如要排除多個專案的記錄項目，請使用邏輯 OR 運算子來聯結 logName 子句。

    每個接收器最多可建立 50 個排除篩選器。請注意，篩選器的長度不得超過 20,000 個半形字元。

  10. 選取「建立接收器」。

  11. 如要完成匯總接收器的設定，請將記錄項目寫入接收器目的地的權限授予接收器的服務帳戶。詳情請參閱「設定目的地權限」。

gcloud

如要建立匯總接收器，請使用 logging sinks create 指令：

  1. 如要建立接收器，請呼叫 gcloud logging sinks create 指令，並確保包含 --include-children 選項。

    使用下列指令前，請先替換以下項目：

    • SINK_NAME：記錄檔接收器的名稱。水槽名稱一經建立即無法變更。
    • SINK_DESTINATION：要將記錄項目傳送至的服務或專案。如要瞭解這些目的地的格式，請參閱「目的地路徑格式」。
    • INCLUSION_FILTER：接收器的「包含」篩選器。如需篩選器範例，請參閱「為匯總接收器建立篩選器」。
    • FOLDER_ID：資料夾 ID。如要在機構層級建立接收器，請將 --folder=FOLDER_ID 替換為 -- organization=ORGANIZATION_ID。

    執行 gcloud logging sinks create 指令：

    gcloud logging sinks create SINK_NAME \
  SINK_DESTINATION  --include-children \
  --folder=FOLDER_ID --log-filter="INCLUSION_FILTER"

    你也可以提供下列選項：

    • 如要建立攔截接收器，請加上 --intercept-children 選項。

    舉例來說，如果您要建立目的地為 Pub/Sub 主題的資料夾層級匯總接收器，指令可能如下所示：

    gcloud logging sinks create SINK_NAME \
  pubsub.googleapis.com/projects/PROJECT_ID/topics/TOPIC_ID --include-children \
  --folder=FOLDER_ID --log-filter="logName:activity"

  2. 授予接收器服務帳戶寫入接收器目的地的權限。詳情請參閱「設定目的地權限」。

REST

如要建立匯總接收器，請使用 organizations.sinks.create 或 folders.sinks.create Logging API 方法。準備方法引數，如下所示：

  1. 將 parent 欄位設為要建立接收器的 Google Cloud 機構或資料夾。上層必須是下列其中一項：

    • organizations/ORGANIZATION_ID
    • folders/FOLDER_ID

  2. 在方法要求主體的 LogSink 物件中，執行下列其中一項操作：

    • 將 includeChildren 設為 True。

    • 如要建立攔截接收器，請將 interceptChildren 欄位設為 True。

  3. 設定 filter 欄位，比對要納入的記錄項目。

    如需篩選器範例，請參閱「為匯總接收器建立篩選器」。

    篩選條件長度不得超過 20,000 個字元。

  4. 其餘 LogSink 欄位的設定方式與任何接收器相同。 詳情請參閱「將記錄檔轉送至支援的目的地」。

  5. 呼叫 organizations.sinks.create 或 folders.sinks.create 建立接收器。

  6. 授予接收器服務帳戶寫入接收器目的地的權限。詳情請參閱「設定目的地權限」。

對接收器所做的變更可能需要幾分鐘才會生效。

匯總接收器的篩選器

本節提供您可能在匯總接收器中使用的篩選器範例。如需更多範例，請參閱「使用記錄檔探索工具的查詢範例」。

有一些範例使用了下列標記法：

  • : 是子字串運算子。請勿替換 = 運算子。
  • ... 代表任何其他篩選條件比較。
  • 變數會以彩色文字表示。以有效的值取代。

篩選條件的長度上限為 20,000 個字元。

如要進一步瞭解篩選語法，請參閱「Logging 查詢語言」。

選取記錄來源

如要轉送所有子資源的記錄項目，請勿在接收器的「包含」和「排除」篩選器中指定專案、資料夾或機構。舉例來說，假設您為機構設定匯總接收器，並採用下列篩選條件：

resource.type="gce_instance"

使用先前的篩選器時，如果資源類型為 Compute Engine 執行個體，且寫入該機構的任何子項，則匯總接收器會將記錄項目傳送至目的地。

不過，有時您可能想使用匯總接收器，只將特定子資源的記錄項目傳送至接收器。舉例來說，基於法規遵循考量，您可能想將特定資料夾或專案的稽核記錄，儲存在專屬的 Cloud Storage bucket。在這些情況下，請設定「包含」篩選器，指定要將記錄項目傳送至每個子項資源。如要從資料夾和該資料夾內的所有專案轉送記錄項目，篩選器必須列出資料夾和該資料夾內含的每個專案，並以 OR 子句聯結陳述式。

下列篩選器會將記錄項目限制為特定 Google Cloud 專案、資料夾或機構：

logName:"projects/PROJECT_ID/logs/" AND ... 
logName:("projects/PROJECT_A_ID/logs/" OR "projects/PROJECT_B_ID/logs/") AND ... 
logName:"folders/FOLDER_ID/logs/" AND ... 
logName:"organizations/ORGANIZATION_ID/logs/" AND ...

舉例來說，如要只將 Compute Engine 執行個體產生的記錄項目，以及源自 my-folder 資料夾的記錄項目，傳送至接收器，請使用下列篩選器：

logName:"folders/my-folder/logs/" AND resource.type="gce_instance"

使用先前的篩選器時，系統不會將來自 my-folder 以外任何資源的記錄項目 (包括來自 Google Cloud 子項my-folder專案的記錄項目) 轉送至目的地。

選取受監控的資源

如要只從Google Cloud 專案中的特定受監控資源傳送記錄項目，請使用多項比較來精確指定資源：

logName:"projects/PROJECT_ID/logs" AND
resource.type=RESOURCE_TYPE AND
resource.labels.instance_id=INSTANCE_ID

如需資源類型清單，請參閱「受監控資源類型」。

選取記錄項目樣本

如要將記錄項目隨機取樣並傳送至目的地，請新增 sample 內建函式。舉例來說，如要只將符合目前篩選條件的記錄項目 10% 傳送至目的地，請新增下列內容：

sample(insertId, 0.10) AND ...

詳情請參閱 sample 函式。

如要進一步瞭解 Cloud Logging 篩選器，請參閱「Logging 查詢語言」。

設定目的地權限

本節說明如何授予 Logging 身分與存取權管理權限，將記錄項目寫入接收器的目的地。如需完整的 Cloud Logging 角色和權限清單，請參閱「存取控管」。

建立或更新接收器時，如果接收器會將記錄項目轉送至目前專案中的記錄檔 bucket 以外的任何目的地，則必須使用該接收器的服務帳戶。Logging 會自動建立及管理服務帳戶：

  • 自 2023 年 5 月 22 日起，如果您建立接收器，但基礎資源沒有服務帳戶，Logging 會建立服務帳戶。Logging 會為基礎資源中的所有接收器使用相同的服務帳戶。資源可以是 Google Cloud 專案、機構、資料夾或帳單帳戶。
  • 2023 年 5 月 22 日前，Logging 會為每個接收器建立服務帳戶。自 2023 年 5 月 22 日起，Logging 會為基礎資源中的所有接收器使用共用服務帳戶。

接收器的寫入者身分是與該接收器相關聯的服務帳戶 ID。除非接收器寫入目前 Google Cloud 專案中的記錄檔儲存空間，否則所有接收器都會有寫入者身分。寫入者身分中的電子郵件地址會識別主體，該主體必須有權將資料寫入目的地。

如要將記錄檔項目傳送至受服務範圍保護的資源，您必須將該接收器的服務帳戶新增至存取層級，然後指派給目的地服務範圍。非匯總接收器不需要執行這項操作。詳情請參閱「VPC Service Controls：Cloud Logging」。

如要設定接收器的權限，以便將資料傳送至目的地，請按照下列步驟操作：

控制台

  1. 如要取得接收器的服務帳戶資訊，請按照下列步驟操作：

    1. 前往 Google Cloud 控制台的「Log Router」(記錄檔路由器) 頁面：

      前往「記錄檔路由器」

      如果您是使用搜尋列尋找這個頁面，請選取子標題為「Logging」的結果。

    2. 選取「選單」圖示 ，然後選取「查看接收器詳細資料」。寫入者身分會顯示在「接收器詳細資料」面板中。

    3. 如果 writerIdentity 欄位的值包含電子郵件地址，請繼續下一個步驟。如果值為 None，則不需要設定目的地權限。

    4. 將接收器的寫入者身分複製到剪貼簿。視接收器所屬的資源而定，寫入者身分可能有所不同，但一律會以 serviceAccount: 為前置字元。以下是寫入者身分的範例：

      serviceAccount:service-123456789012@gcp-sa-logging.iam.gserviceaccount.com

  2. 將記錄資料寫入目的地的權限授予接收器寫入者身分指定的主體：

    1. 前往 Google Cloud 控制台的「IAM」頁面：

      前往 IAM

      如果您是使用搜尋列尋找這個頁面，請選取子標題為「IAM & Admin」(IAM 與管理) 的結果。

    2. 在 Google Cloud 控制台的工具列中，選取儲存匯總接收器目的地的專案。如果目的地是專案，請選取該專案。

    3. 按一下 「授予存取權」。

    4. 輸入接收器寫入者身分指定的主體，然後授予 IAM 角色：

      • 針對所有目的地，授予記錄檔寫入者角色 (roles/logging.logWriter)。具體來說，主體需要 logging.logEntries.route 權限。
      • 根據目的地授予下列其中一個角色：
        • 記錄檔 bucket：授予記錄檔 bucket 寫入者角色 (roles/logging.bucketWriter)。
        • Cloud Storage bucket：授予「Storage 物件建立者」角色 (roles/storage.objectCreator)。
        • BigQuery 資料集：授予「BigQuery 資料編輯者」角色 (roles/bigquery.dataEditor)。
        • Pub/Sub 主題，包括 Splunk：授予 Pub/Sub 發布者角色 (roles/pubsub.publisher)。

gcloud

  1. 確認您對包含目的地的Google Cloud 專案具有「擁有者」存取權。如果沒有接收器目的地的「擁有者」存取權，請要求專案擁有者將寫入者身分新增為主體。

  2. 如要取得接收器的服務帳戶資訊，請呼叫 gcloud logging sinks describe 方法。

    使用下列指令前，請先替換以下項目：

    • SINK_NAME：記錄檔接收器的名稱。水槽名稱一經建立即無法變更。

    執行 gcloud logging sinks describe 指令：

    gcloud logging sinks describe SINK_NAME

  3. 如果接收器詳細資料包含標示為 writerIdentity 的欄位，請繼續下一個步驟。如果詳細資料不含writerIdentity欄位，您就不需要為接收器設定目的地權限。

  4. 將接收器的寫入者身分複製到剪貼簿。以下說明寫入者身分：

    serviceAccount:service-123456789012@gcp-sa-logging.iam.gserviceaccount.com

  5. 呼叫 gcloud projects add-iam-policy-binding 指令，將記錄資料寫入目的地的權限授予接收器的寫入者身分。

    使用下列指令前，請先替換以下項目：

    • PROJECT_ID：專案的 ID。選取儲存匯總接收器目的地的專案。如果目的地是專案，請選取該專案。
    • PRINCIPAL：要授予角色的主體 ID。主體 ID 通常採用以下格式： PRINCIPAL-TYPE:ID。 例如：user:my-user@example.com。如要查看 PRINCIPAL 的完整格式清單，請參閱「主體 ID」。

    • ROLE：IAM 角色。根據記錄檔接收器的目的地，授予接收器寫入者身分 IAM 角色：

      • 針對所有目的地，授予記錄檔寫入者角色 (roles/logging.logWriter)。具體來說，主體需要 logging.logEntries.route 權限。
      • 根據目的地授予下列其中一個角色：
        • 記錄檔 bucket：授予記錄檔 bucket 寫入者角色 (roles/logging.bucketWriter)。
        • Cloud Storage bucket：授予「Storage 物件建立者」角色 (roles/storage.objectCreator)。
        • BigQuery 資料集：授予「BigQuery 資料編輯者」角色 (roles/bigquery.dataEditor)。
        • Pub/Sub 主題，包括 Splunk：授予 Pub/Sub 發布者角色 (roles/pubsub.publisher)。

      執行 gcloud projects add-iam-policy-binding 指令：

      gcloud projects add-iam-policy-binding PROJECT_ID --member=PRINCIPAL --role=ROLE

REST

建議您使用 Google Cloud 控制台或 Google Cloud CLI，將角色授予服務帳戶。

後續步驟