Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

將記錄檔轉送至支援的目的地

本文說明如何建立及管理記錄接收器，將 Google Cloud 專案中的記錄項目傳送至支援的目的地。

接收器會執行寫入動作，因此必須獲得授權才能寫入目的地。如果目的地是與接收器位於相同專案的記錄檔 bucket，系統會自動授權接收器。如為其他目的地，接收器必須附加至已獲授權的服務帳戶，該帳戶必須具備將資料寫入目的地所需的權限。

需要服務帳戶時，Cloud Logging 會自動建立及管理服務帳戶。不過，您可能需要修改授予服務帳戶的權限。您不必使用 Logging 建立的服務帳戶，您可以建立及管理服務帳戶，供多個專案中的接收器使用。詳情請參閱「使用使用者代管的服務帳戶設定記錄接收器」。

總覽

本頁說明如何建立接收器，以及如何設定使用 Google Cloud 控制台或 API 時可能看到的選項。

接收器屬於特定 Google Cloud 資源： Google Cloud 專案、帳單帳戶、資料夾或機構。當資源收到記錄項目時，資源中的每個接收器都會處理該記錄項目。如果記錄項目符合接收器的篩選條件，系統就會將該項目轉送至接收器的目的地。

一般來說，接收器只會將源自資源的記錄項目傳送至目的地。不過，您可以為資料夾和機構建立匯總接收器，從資料夾或機構，以及其中包含的資源轉送記錄項目。本文不會探討匯總接收器。詳情請參閱「匯總接收器總覽」。

如要建立及管理接收器，可以使用 Google Cloud 控制台、Cloud Logging API 和 Google Cloud CLI。建議您使用 Google Cloud 控制台，原因如下：

您可以在流程中設定接收器目的地，藉此建立接收器。
您可以預覽符合接收器篩選器的記錄項目。
簡化部分授權步驟。

變更記錄儲存空間時，建議您檢查記錄檔接收器設定。舉例來說，如果刪除記錄檔接收器的目的地，請一併刪除對應的記錄檔接收器。

如要瞭解如何查看及管理記錄接收器，請參閱本文的「管理接收器」一節。

支援的目的地

接收器的目的地可以與接收器位於不同的資源中。舉例來說，您可以使用記錄檔接收器，將一個專案的記錄檔項目傳送至儲存在另一個專案中的記錄檔 bucket。

系統支援下列目的地：

Google Cloud 專案: 如果希望目標專案中的記錄接收器重新轉送記錄項目，或是已建立攔截匯總接收器，請選取這個目標位置。接收器目的地專案中的記錄檔接收器，可將記錄檔項目重新轉送至任何支援的目的地，但專案除外。

注意： 這是唯一會重新導向記錄項目的目的地類型。舉例來說，如果您將一個專案的記錄項目轉送至另一個專案的記錄檔 bucket，則儲存記錄檔 bucket 的專案中，記錄接收器不會重新轉送這些記錄項目。

記錄檔 bucket: 如要在 Cloud Logging 管理的資源中儲存記錄檔資料，請選取這個目的地。您可以使用 Logs Explorer 等服務，查看及分析記錄檔 bucket 中儲存的記錄檔資料。

Pub/Sub 主題: 如要從匯出記錄資料，然後使用第三方整合服務，請選取這個目的地。Google Cloud 記錄項目會格式化為 JSON，然後傳送至 Pub/Sub 主題。

目的地限制

本節說明目的地專屬限制：

如果記錄檔接收器目的地是 Google Cloud 專案，則適用下列限制：
- 躍點限制為一。
- 只有當記錄項目來自目的地專案時，符合_Required記錄檔接收器篩選條件的記錄項目才會轉送至目的地專案的 _Required 記錄檔 bucket。
- 只有記錄項目資源階層中的匯總接收器，才會處理記錄項目。
舉例來說，假設專案 A 中記錄檔接收器的目的地是專案 B。則下列情況屬實：
- 由於單一躍點限制，專案 B 中的記錄接收器無法將記錄項目重新導向至 Google Cloud 專案。
- 專案 B 的 _Required 記錄檔 bucket 只會儲存源自專案 B 的記錄項目。這個記錄檔值區不會儲存來自任何其他資源的記錄項目，包括來自專案 A 的記錄項目。
- 如果專案 A 和專案 B 的資源階層不同，則專案 A 中記錄檔接收器轉送至專案 B 的記錄項目，不會傳送至專案 B 資源階層中的匯總接收器。
- 如果專案 A 和專案 B 具有相同的資源階層，記錄檔項目就會傳送至該階層中的匯總接收器。如果記錄項目未遭匯總接收器攔截，記錄檔路由器就會將記錄項目傳送至專案 A 中的接收器。

事前準備

本文的操作說明將介紹如何在Google Cloud 專案層級建立及管理接收器。您可以使用相同程序建立接收器，將源自機構、資料夾或帳單帳戶的記錄項目傳送至目的地。

如要開始使用，請按照下列步驟操作：

啟用 Cloud Logging API。
啟用 API 時所需的角色
如要啟用 API，您必須具備 serviceusage.services.enable 權限。如果您建立了專案，可能已透過「擁有者」角色 (roles/owner) 取得這項權限。否則，您可以透過「服務使用情形管理員」角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。
啟用 API
請確認 Google Cloud 專案包含可在 Logs Explorer 中查看的記錄項目。
如要取得建立、修改或刪除接收器所需的權限，請要求管理員授予您專案的記錄設定寫入者 (roles/logging.configWriter) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

如要瞭解如何授予 IAM 角色，請參閱 Logging 存取權控管指南。
您在支援的目的地中擁有資源，或有權建立資源。

如要將記錄項目傳送至目的地，您必須先建立目的地，才能建立接收器。您可以在任何機構的任何Google Cloud 專案中建立目的地。
建立接收器前，請先查看接收器目的地適用的限制。詳情請參閱本文的「目的地限制」一節。
選取要使用的介面：
控制台

使用 Google Cloud 控制台存取 Google Cloud 服務和 API 時，無須設定驗證。
gcloud

安裝 Google Cloud CLI，然後使用聯合身分登入 gcloud CLI。登入後，執行下列指令來初始化 Google Cloud CLI：
gcloud init
注意：如果您已經安裝 gcloud CLI，請務必執行 gcloud components update，確認您安裝的是最新版本。
REST

如要在本機開發環境中使用本頁的 REST API 範例，請使用您提供給 gcloud CLI 的憑證。
詳情請參閱 Google Cloud 驗證說明文件中的「使用 REST 進行驗證」。

建立接收器

本節說明如何在 Google Cloud 專案中建立接收器。每個專案最多可建立 200 個接收器。 Google Cloud 如要查看已路由傳送的記錄項目數量和容量，請查看logging.googleapis.com/exports/指標。

您可以使用 Logging 查詢語言建立篩選器運算式，找出要納入的記錄項目。請勿在接收器篩選器中加入機密資訊。接收器篩選器會視為服務資料。

如果查詢包含多個陳述式，您可以指定這些陳述式的聯結方式，也可以讓 Cloud Logging 在陳述式之間隱含地加入連詞限制 AND。舉例來說，假設查詢或篩選器對話方塊包含兩個陳述式：resource.type = "gce_instance" 和 severity >= "ERROR"。實際查詢為 resource.type = "gce_instance" AND severity >= "ERROR"。 Cloud Logging 支援不相交限制 (OR) 和合取限制 (AND)。使用 OR 陳述式時，建議您使用括號將子句分組。

如要建立接收器，請按照下列步驟操作：

控制台

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

如果您是使用搜尋列尋找這個頁面，請選取子標題為「Logging」的結果。
選取要轉送的記錄項目所屬的專案 Google Cloud 。

舉例來說，如要將名為 Project-A 的專案中的資料存取記錄項目，轉送至名為 Project-B 的專案中的記錄檔 bucket，請選取 Project-A。
選取「建立接收器」。
在「接收器詳細資料」面板中，輸入下列詳細資料：
- 「Sink name」(接收器名稱)：提供接收器的 ID。請注意，建立接收器後就無法重新命名，但可以刪除並建立新的接收器。
- 接收器說明 (選填)：說明接收器的用途或用途。
在「接收器目的地」面板中，使用「選取接收器服務」選單選取接收器服務和目的地。執行下列任一操作：
- 如要將記錄項目傳送至同一Google Cloud 專案中的服務，請選取下列其中一個選項：
  - Cloud Logging bucket：選取或建立記錄檔 bucket。
  - Pub/Sub 主題：選取或建立用於接收已路由傳送記錄檔項目的特定主題。
- 如要將記錄項目轉送至其他 Google Cloud 專案，請選取「專案」Google Cloud ，然後輸入目標的完整名稱：
```
logging.googleapis.com/projects/DESTINATION_PROJECT_ID
```
- 如要將記錄檔項目傳送至其他Google Cloud 專案中的服務，請按照下列步驟操作：
  1. 選取「其他資源」。
  2. 輸入目的地的完整名稱。如要瞭解語法，請參閱「目的地路徑格式」。
指定要納入的記錄項目：
1. 前往「選擇要納入接收器的記錄檔」面板。
2. 在「Build inclusion filter」(建立「包含」篩選器) 欄位中，輸入與您想納入的記錄項目相符的篩選運算式。如要進一步瞭解如何撰寫篩選器的語法，請參閱 Logging 查詢語言。
  
  如未設定篩選器，系統會將所選資源的所有記錄項目轉送至目的地。
  
  舉例來說，如要將所有資料存取記錄項目傳送至 Logging 儲存空間，可以使用下列篩選器：
```
log_id("cloudaudit.googleapis.com/data_access") OR log_id("externalaudit.googleapis.com/data_access")
```
  篩選條件長度不得超過 20,000 個字元。
3. 如要確認輸入的篩選條件正確無誤，請選取「預覽記錄」。系統會在新的分頁中開啟 Logs Explorer，並預先填入篩選條件。
(選用) 設定排除篩選器，排除部分納入的記錄項目：
1. 前往「選擇要從接收器排除的記錄檔」面板。
2. 在「排除篩選器名稱」欄位中輸入名稱。
3. 在「建立排除篩選器」欄位中，輸入與您想排除的記錄項目相符的篩選運算式。您也可以使用 sample 函式選取要排除的記錄項目部分。
  
  重要事項： 如要在建立接收器時停用排除篩選器，請輸入篩選運算式，然後選取「停用」。您稍後可以更新接收器，啟用排除篩選器。
每個接收器最多可建立 50 個排除篩選器。請注意，篩選條件的長度不得超過 20,000 個字元。
選取「建立接收器」。
將記錄項目寫入接收器目的地所需的權限，授予接收器的服務帳戶。詳情請參閱「設定目的地權限」。

gcloud

如要建立接收器，請按照下列步驟操作：

執行下列 gcloud logging sinks create 指令：
```
gcloud logging sinks create SINK_NAME SINK_DESTINATION
```
執行指令前，請先進行下列替換：
- SINK_NAME：記錄檔接收器的名稱。接收器名稱一經建立即無法變更。
- SINK_DESTINATION：要將記錄項目傳送至的服務或專案。如「目的地路徑格式」一文所述，設定 SINK_DESTINATION 的適當路徑。
  
  舉例來說，如果接收器目的地是 Pub/Sub 主題，則 SINK_DESTINATION 看起來會如下所示：
```
pubsub.googleapis.com/projects/PROJECT_ID/topics/TOPIC_ID
```
你也可以提供下列選項：
- --log-filter：使用這個選項設定篩選器，找出要納入接收器的記錄項目。如果未提供納入篩選器的值，這個篩選器就會比對所有記錄項目。
- --exclusion：使用這個選項為記錄項目設定排除篩選器，讓接收器不會轉送這些項目。您也可以使用 sample 函式選取要排除的記錄項目部分。這項選項可以重複使用，每個接收器最多可建立 50 個排除篩選器。
- --description：使用這個選項說明接收器的用途或使用案例。
舉例來說，如要建立接收器並將記錄檔傳送至 Logging 儲存空間，您的指令可能如下所示：
```
gcloud logging sinks create my-sink logging.googleapis.com/projects/myproject123/locations/global/buckets/my-bucket \
 --log-filter='logName="projects/myproject123/logs/matched"' --description="My first sink"
```
如要進一步瞭解如何使用 Google Cloud CLI 建立接收器，請參閱 gcloud logging sinks 參考資料。
如果指令回應包含標示為 "writerIdentity" 的 JSON 金鑰，請授予接收器服務帳戶寫入接收器目的地的權限。詳情請參閱「設定目的地權限」一文。

如果回應不含標示為 "writerIdentity" 的 JSON 金鑰，就不需要設定目的地權限。

REST

如要在 Google Cloud 專案中建立記錄接收器，請使用 Logging API 中的 projects.sinks.create。在 LogSink 物件中，於方法要求主體中提供適當的必要值：
- name：接收器的 ID。請注意，建立接收器後就無法重新命名，但可以刪除並建立新的接收器。
- destination：要將記錄項目轉送至的服務和目的地。如要將記錄檔項目轉送至其他專案，或轉送至其他專案中的目的地，請使用適當路徑設定 destination 欄位，如「目的地路徑格式」一文所述。
  
  舉例來說，如果接收器目的地是 Pub/Sub 主題，則 destination 看起來會如下所示：
```
pubsub.googleapis.com/projects/PROJECT_ID/topics/TOPIC_ID
```
在 LogSink 物件中，提供適當的選用資訊：
- filter：設定 filter 欄位，比對要納入接收器的記錄項目。如未設定篩選器，Google Cloud 專案中的所有記錄項目都會轉送至目的地。請注意，篩選條件的長度不得超過 20,000 個字元。
- exclusions：將這個欄位設為與要從接收器排除的記錄項目相符。您也可以使用 sample 函式選取要排除的記錄項目部分。每個接收器最多可建立 50 個排除篩選器。
- description：設定這個欄位，說明接收器的用途或使用案例。
呼叫 projects.sinks.create 建立接收器。
如果 API 回應包含標示為 "writerIdentity" 的 JSON 金鑰，請授予接收器的服務帳戶寫入接收器目的地的權限。詳情請參閱「設定目的地權限」一文。

如果 API 回應不包含標示為 "writerIdentity" 的 JSON 金鑰，則不需要設定目的地權限。

如要進一步瞭解如何使用 Logging API 建立接收器，請參閱 LogSink 參考資料。

如果收到錯誤通知，請參閱「排解路由和接收器問題」。

目的地路徑格式

如果將記錄檔項目傳送至其他專案中的服務，則必須為接收器提供該服務的完整名稱。同樣地，如果將記錄檔項目轉送至其他 Google Cloud 專案，則必須為接收器提供目的地專案的完整名稱：

Cloud Logging 記錄值區：

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

其他 Google Cloud 專案：

logging.googleapis.com/projects/DESTINATION_PROJECT_ID

Pub/Sub 主題：

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

設定目的地權限

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

建立接收器時，Cloud Logging 會為資源建立共用服務帳戶，除非必要的服務帳戶已存在。如果基礎資源中的所有接收器都使用同一個服務帳戶，就可能會發生這種情況。資源可以是 Google Cloud 專案、機構、資料夾或帳單帳戶。

接收器的寫入者身分是與該接收器相關聯的服務帳戶 ID。除了寫入記錄檔 bucket 的接收器 (該 bucket 與記錄項目來源專案相同) 之外，所有接收器都有寫入者身分。 Google Cloud 如果是後者，則不需要服務帳戶，因此接收器的「寫入者身分」欄位在控制台中會列為 None。API 和 Google Cloud CLI 指令不會回報寫入者身分。

下列操作說明適用於專案、資料夾、機構和帳單帳戶：

控制台

請確認您對Google Cloud 包含目的地的專案具有擁有者存取權。如果您不具有接收器目的地的擁有者存取權，請要求專案擁有者將寫入者身分新增為主體。
如要從新接收器取得該接收器的寫入者身分 (電子郵件地址)，請按照下列步驟操作：
1. 前往 Google Cloud 控制台的「Log Router」(記錄檔路由器) 頁面：
  前往「記錄檔路由器」
  
  如果您是使用搜尋列尋找這個頁面，請選取子標題為「Logging」的結果。
2. 在工具列中，選取含有接收器的專案。
3. 選取「選單」圖示，然後選取「查看接收器詳細資料」。寫入者身分會顯示在「接收器詳細資料」面板中。
如果 writerIdentity 欄位的值包含電子郵件地址，請繼續下一個步驟。如果值為 None，則不需要為接收器設定目的地權限。
將接收器的寫入者身分複製到剪貼簿。

電子郵件地址可識別主體。前置字串 serviceAccount: 用於指定帳戶類型。
將記錄資料寫入目的地的權限授予接收器寫入者身分中指定的主體：
1. 前往 Google Cloud 控制台的「IAM」頁面：
  前往 IAM
  
  如果您是使用搜尋列尋找這個頁面，請選取子標題為「IAM & Admin」(IAM 與管理) 的結果。
2. 在工具列中，確認所選專案是儲存目的地的專案，或是接收器目的地。舉例來說，如果目的地是記錄檔 bucket，請確認工具列顯示儲存記錄檔 bucket 的專案。
3. 按一下「授予存取權」。
4. 根據記錄接收器的目的地，將 IAM 角色授予接收器寫入者身分中指定的主體：
  - 針對所有目的地，請授予記錄檔寫入者角色 (roles/logging.logWriter)。具體來說，主體需要 logging.logEntries.route 權限。
  - 根據目的地授予下列其中一個角色：
    - 記錄檔值區：授予記錄檔值區寫入者角色 (roles/logging.bucketWriter)。
    - Pub/Sub 主題：授予 Pub/Sub 發布者角色 (roles/pubsub.publisher)。

gcloud

請確認您對Google Cloud 包含目的地的專案具有擁有者存取權。如果您不具有接收器目的地的擁有者存取權，請要求專案擁有者將寫入者身分新增為主體。
從接收器的「writerIdentity」欄位取得服務帳戶：
```
gcloud logging sinks describe SINK_NAME
```
找到要修改權限的接收器，如果接收器詳細資料包含 writerIdentity 的行，請繼續下一個步驟。如果詳細資料不包含欄位，則不需要為接收器設定目的地權限。writerIdentity

服務帳戶的寫入者身分類似如下所示：
```
serviceAccount:service-123456789012@gcp-sa-logging.
```
呼叫 gcloud projects add-iam-policy-binding 指令，授予接收器的寫入者身分將記錄資料寫入目的地的權限。

使用下列指令前，請先替換以下項目：
- PROJECT_ID：專案的 ID。指定儲存記錄檔接收器目的地的專案。如果目的地是專案，請指定該專案。
- PRINCIPAL：要授予角色的主體 ID。主體 ID 通常採用以下格式： PRINCIPAL-TYPE:ID。例如：。如需 PRINCIPAL 可採用的完整格式清單，請參閱「主體 ID」。
- ROLE：IAM 角色。根據記錄接收器的目的地，授予該接收器的寫入者身分 IAM 角色：
  - 針對所有目的地，請授予記錄檔寫入者角色 (roles/logging.logWriter)。具體來說，主體需要 logging.logEntries.route 權限。
  - 根據目的地授予下列其中一個角色：
    - 記錄檔值區：授予記錄檔值區寫入者角色 (roles/logging.bucketWriter)。
    - Pub/Sub 主題：授予 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，將角色授予服務帳戶。

篩選器範例

以下是一些篩選器範例，在建立接收器時特別實用。如需更多範例，協助您建立納入和排除篩選器，請參閱範例查詢。

還原 `_Default` 水槽篩選器

如果您編輯了 _Default 接收器的篩選器，可能需要將這個接收器還原為原始設定。建立 _Default 接收器時，系統會設定下列「包含」篩選器和空白的「排除」篩選器：

  NOT log_id("cloudaudit.googleapis.com/activity") AND NOT \
  log_id("externalaudit.googleapis.com/activity") AND NOT \
  log_id("cloudaudit.googleapis.com/system_event") AND NOT \
  log_id("externalaudit.googleapis.com/system_event") AND NOT \
  log_id("cloudaudit.googleapis.com/access_transparency") AND NOT \
  log_id("externalaudit.googleapis.com/access_transparency")

排除 Google Kubernetes Engine 容器和 Pod 記錄

如要排除 Google Kubernetes Engine 容器和 Pod 的記錄項目 (適用於 GKE 系統 namespaces)，請使用下列篩選器：

resource.type = ("k8s_container" OR "k8s_pod")
resource.labels.namespace_name = (
"cnrm-system" OR
"config-management-system" OR
"gatekeeper-system" OR
"gke-connect" OR
"gke-system" OR
"istio-system" OR
"knative-serving" OR
"monitoring-system" OR
"kube-system")

如要排除 GKE 系統 logNames 的 Google Kubernetes Engine 節點記錄項目，請使用下列篩選器：

resource.type = "k8s_node"
logName:( "logs/container-runtime" OR
"logs/docker" OR
"logs/kube-container-runtime-monitor" OR
"logs/kube-logrotate" OR
"logs/kube-node-configuration" OR
"logs/kube-node-installation" OR
"logs/kubelet" OR
"logs/kubelet-monitor" OR
"logs/node-journal" OR
"logs/node-problem-detector")

支援性

雖然 Cloud Logging 可讓您排除記錄項目，並防止這些項目儲存在記錄檔 bucket 中，但建議您保留有助於支援的記錄項目。您可以利用這些記錄檔項目排解及找出應用程式問題。

舉例來說，GKE 系統記錄項目是在叢集發生事件時產生，因此有助於排解 GKE 應用程式和叢集的疑難。這些記錄項目可協助您判斷應用程式錯誤是由應用程式程式碼或基礎 GKE 叢集所造成。GKE 系統記錄檔也包含 Kubernetes API 伺服器元件產生的 Kubernetes 稽核記錄，包括使用 kubectl 指令所做的變更和 Kubernetes 事件。

後續步驟

如果使用接收器將記錄檔項目傳送至其他目的地時發生問題，請參閱「排解記錄檔傳送問題」。
如要瞭解如何在目的地中查看記錄項目，以及記錄的格式和組織方式，請參閱「在接收器目的地中查看記錄」一文。
如要進一步瞭解如何使用 Logging 查詢語言查詢及篩選記錄，請參閱「Logging 查詢語言」。

將記錄檔轉送至支援的目的地 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

總覽

支援的目的地

目的地限制

事前準備

控制台

gcloud

REST

建立接收器

控制台

gcloud

REST

目的地路徑格式

設定目的地權限

控制台

gcloud

REST

篩選器範例

還原 _Default 水槽篩選器

排除 Google Kubernetes Engine 容器和 Pod 記錄

支援性

後續步驟

將記錄檔轉送至支援的目的地

還原 `_Default` 水槽篩選器