排解轉送及儲存記錄的問題

本文說明常見的路由和儲存空間問題,以及如何使用Google Cloud 控制台查看及排解設定錯誤或非預期結果。

如需查看記錄資料的一般資訊,請參閱「查看接收器目的地中的記錄檔」。

排解記錄檔路徑問題

本節說明如何排解記錄檔項目的路由常見問題。

建立接收器失敗,並顯示不明服務錯誤

您嘗試建立記錄檔接收器,但指令失敗並顯示 INVALID_ARGUMENT (HTTP 400) 錯誤。錯誤訊息包含下列內容:

Sink.destination with unknown service name: [SERVICE_DOMAIN]. Supported services are bigquery.googleapis.com,pubsub.googleapis.com,storage.googleapis.com,logging.googleapis.com

如要解決這項錯誤,請使用其中一個支援服務的全域端點。記錄檔接收器目的地無法指定區域服務端點 (REP),例如 pubsub.LOCATION.rep.googleapis.com。

接收器設定錯誤訊息指出不允許主題區域

發生下列其中一種情況:

  • 你會收到主旨為「[ACTION REQUIRED] Cloud Logging sink configuration error in [PROJECT_ID]」的電子郵件,內含錯誤代碼 topic_region_not_allowed。電子郵件會包含類似下列內容的訊息:

    主題的訊息儲存空間政策規定必須強制執行傳輸中區域,但 Pub/Sub 伺服器在不允許的區域收到發布要求。請透過允許區域對應的區域 Cloud Logging 端點發布,或更新主題的訊息儲存政策。

  • 您會發現嚴重程度為 ERROR 的記錄項目、錯誤代碼為 "topic_region_not_allowed",以及類似下列內容的文字酬載:

    Cloud Logging sink configuration error in [PROJECT_ID], sink [SINK_NAME]: topic_region_not_allowed ()
    

這些訊息表示接收器的目的地是 Pub/Sub 主題,該主題會強制執行傳輸中限制,且記錄檔路由傳送的記錄檔項目來自主題政策不允許的區域。您可以在個別主題的訊息儲存政策中設定傳輸中限制,也可以使用 constraints/pubsub.enforceInTransitRegions 組織政策限制條件,在整個機構中強制執行這項限制。

如要解決這些失敗問題,請採取下列任一做法:

  • 更新目的地 Pub/Sub 主題的訊息儲存政策,停用傳輸中強制執行功能,或擴大允許的持續性區域。
  • 如果組織政策強制執行傳輸中限制,請更新組織政策或為專案申請豁免。
  • 更新接收器,將記錄項目轉送至其他目的地。

目的地含有不必要的記錄項目

您正在查看轉送至目的地的記錄項目,並判斷目的地包含不想要的記錄項目。

如要解決這個問題,請更新將記錄項目轉送至目的地的接收器排除篩選器。排除篩選器可讓您排除特定記錄項目,避免轉送至目的地。

舉例來說,假設您建立匯總接收器,將機構中的記錄項目轉送至目的地。如要排除特定專案的記錄項目,不要轉送至目的地,請在接收器中加入下列排除篩選器:

logName:projects/PROJECT_ID

您也可以使用邏輯 OR 運算子合併 logName 子句,排除多個專案的記錄項目。

目的地缺少記錄項目

最常見的接收器相關問題,或許是記錄項目似乎從接收器的目的地遺失。

有時系統不會產生錯誤,但您可能會發現,嘗試在目的地存取記錄項目時,這些項目無法使用。如果懷疑接收器未正確傳送記錄項目,請檢查接收器的系統記錄指標:

  • exports/byte_count:已轉送的記錄項目位元組數。
  • exports/log_entry_count:已路由的記錄項目數量。
  • exports/error_count:無法轉送的記錄項目數量。

這些指標會記錄接收器名稱和目的地名稱的計數,並顯示接收器是否成功或無法順利傳送記錄項目。如要瞭解如何查看指標,請參閱「記錄指標總覽」的說明。

如果接收器指標顯示接收器未達到預期成效,可能原因和解決方法如下:

延遲

  • 在您建立或更新接收器之後,未接收到任何相符記錄項目;系統只會傳送新的記錄項目。

    請稍候一小時,然後再次檢查目的地。

  • 相符的記錄項目延遲抵達。

    記錄項目可能需要一段時間才會顯示在目的地中。如果接收器將 Cloud Storage bucket 設為目的地,就特別容易發生記錄檔項目延遲抵達的情況。請稍候幾小時,然後再次檢查目的地。

檢視範圍/篩選條件不正確

  • 您用來查看儲存在記錄檔 bucket 中的記錄項目的範圍不正確。

    將搜尋範圍限定為一或多個記錄檢視,方法如下:

    • 如果您使用 Logs Explorer,請按一下「縮小範圍」按鈕。

    • 如果您使用 gcloud CLI,請使用 gcloud logging read 指令,並新增 --view=AllLogs 旗標。

  • 您在接收器目的地中選取及查看資料時使用的時間範圍太窄。

    在接收器目的地中選取資料時,請嘗試擴大時間範圍。

接收器篩選器發生錯誤

  • 接收器的篩選器有誤,因此未擷取您預期會在目的地中看到的記錄項目。

    在 Google Cloud 控制台使用 記錄檔路由器編輯接收器的篩選器。如要確認輸入的篩選條件是否正確,請在「Edit sink」(編輯接收器) 面板中選取「Preview logs」(預覽記錄)。這會在新的分頁中開啟 Logs Explorer,並預先填入篩選條件。如需查看及管理接收器的操作說明,請參閱「管理接收器」一節。

查看錯誤

針對每個支援的接收器目的地,記錄服務都會提供設定不當的接收器錯誤訊息。

您可以透過幾種方式查看這些與接收器相關的錯誤,詳情請參閱下列章節:

錯誤記錄檔

如要詳細檢查接收器相關錯誤,建議查看接收器產生的錯誤記錄檔項目。如要進一步瞭解如何查看記錄項目,請參閱「使用 Logs Explorer 查看記錄檔」。

您可以在 Logs Explorer 的查詢編輯器窗格中使用下列查詢,查看接收器的錯誤記錄。相同的查詢適用於 Logging API 和 gcloud CLI。

複製查詢前,請將變數 SINK_NAME 替換為要排解問題的接收器名稱。您可以在 Google Cloud 控制台的「Log Router」頁面找到接收器的名稱。

logName:"logging.googleapis.com%2Fsink_error"
resource.type="logging_sink"
resource.labels.name="SINK_NAME"

舉例來說,如果接收器的名稱是 my-sink-123,記錄項目可能如下所示:

{
   errorGroups: [
   0: {
   id: "COXu96aNws6BiQE"
   }]
   insertId: "170up6jan"
   labels: {
      activity_type_name: "LoggingSinkConfigErrorV2"
      destination: "pubsub.googleapis.com/projects/my-project/topics/my-topic"
      error_code: "topic_not_found"
      error_detail: ""
      sink_id: "my-sink-123"
   }
   logName: "projects/my-project/logs/logging.googleapis.com%2Fsink_error"
   receiveTimestamp: "2024-07-11T14:41:42.578823830Z"
   resource: {
   labels: {
      destination: "pubsub.googleapis.com/projects/my-project/topics/my-topic"
      name: "my-sink-123"
      project_id: "my-project"
   }
   type: "logging_sink"
   }
   severity: "ERROR"
   textPayload: "Cloud Logging sink configuration error in my-project, sink my-sink-123: topic_not_found ()"
   timestamp: "2024-07-11T14:41:41.296157014Z"
}

LogEntry 欄位 labels 及其巢狀鍵值資訊可協助您找出接收器錯誤的來源,其中包含受影響的資源、受影響的接收器和錯誤碼。labels.error_code 欄位包含錯誤的簡短說明,可讓您瞭解接收器中需要重新設定的元件。

如要解決這項失敗問題,請編輯接收器。舉例來說,您可以使用「記錄檔路由器」頁面編輯接收器:

前往「記錄檔路由器」

電子郵件通知

重要聯絡人會將接收器設定錯誤的電子郵件通知,傳送給指派給 Google Cloud 專案或父項資源技術通知類別的聯絡人。如果資源未設定技術通知的聯絡人,系統會將電子郵件通知傳送給列為資源 IAM 專案擁有者 roles/owner 的使用者。

針對每個記錄檔接收器名稱和錯誤的組合,系統每天會傳送一則通知。

電子郵件訊息包含下列資訊:

  • 資源 ID:設定接收器的 Google Cloud 專案Google Cloud 或其他資源名稱。
  • 接收器名稱:含有設定錯誤的接收器名稱。
  • 接收器目的地:接收器路由目的地的完整路徑;例如: pubsub.googleapis.com/projects/PROJECT_ID/topics/TOPIC_ID
  • 錯誤代碼:錯誤類別的簡短說明,例如 topic_not_found。
  • 錯誤詳細資料:錯誤的詳細資訊,包括排解根本錯誤的建議。

這封電子郵件的寄件者是 logging-noreply@google.com。

主旨類似於:Subject: [ACTION REQUIRED] Cloud Logging sink configuration error in my-project

如要查看及管理接收器,請使用「記錄檔路由器」頁面:

前往「記錄檔路由器」

清單中會以 Cloud Logging sink configuration error 符號標示適用於資源的任何接收器設定錯誤。每個錯誤都包含一個連結,連至有問題的接收器所產生的其中一個記錄項目。如要詳細檢查基礎錯誤,請參閱「錯誤記錄」一節。

接收器目的地不正確

如果您設定接收器,但隨後看到設定錯誤,指出 Logging 嘗試將記錄項目傳送至目的地時找不到目的地,可能的原因如下:

  • 您指定的接收器目的地設定含有錯字或其他格式錯誤。

    您需要更新接收器的設定,才能正確指定現有目的地。

  • 指定的目的地可能已刪除。

    您可以變更接收器的設定,改用其他現有目的地,也可以使用相同名稱重新建立目的地。

如要解決這類失敗問題,請編輯接收器。舉例來說,您可以使用「記錄檔路由器」頁面編輯接收器:

前往「記錄檔路由器」

系統找到目的地,且 Logging 收到符合篩選條件的新記錄項目時,接收器就會開始轉送記錄項目。

已停用接收器問題

如果您停用接收器,停止在記錄檔 bucket 中儲存記錄項目,但仍看到系統傳送記錄項目,請稍待幾分鐘,讓接收器套用變更。

接收器權限問題

如果接收器嘗試轉送記錄項目,但缺少接收器目的地適用的 IAM 權限,接收器就會回報錯誤 (您可以查看),並略過記錄項目。

建立接收器時,必須授予接收器服務帳戶適當的目的地權限。如果您在 Google Cloud 控制台中建立接收器,且與Google Cloud 專案位於同一位置,則 Google Cloud 控制台通常會自動指派這些權限。不過,如果您在其他Google Cloud 專案中建立接收器,或是使用 gcloud CLI 或 Logging API 建立接收器,則必須手動設定權限。

如果接收器發生權限相關錯誤,請新增必要權限,或更新接收器以使用其他目的地。如需更新這些權限的操作說明,請參閱「目的地權限」。

建立接收器後,需要稍待片刻,才能使用接收器的新服務帳戶授權寫入目的地。修正任何權限後,Logging 收到符合篩選條件的新記錄項目時,接收器就會開始傳送記錄項目。

接收器發生機構政策問題

如果您嘗試將記錄項目傳送至接收器目的地,但遇到機構政策限制 Logging 寫入接收器目的地,接收器就無法將記錄項目傳送至所選目的地,並會回報錯誤。

如果看到與機構政策相關的錯誤訊息,請採取下列行動:

  • 更新目的地的機構政策,移除禁止接收器轉送記錄檔項目的限制。前提是您必須具備更新機構政策的適當權限。

    您可能會檢查是否有資源位置限制 (constraints/gcp.resourceLocations)。這項限制會決定資料的儲存位置。 此外,部分服務支援可能會影響記錄檔接收器的限制。舉例來說,選取 Pub/Sub 目的地時,可能會受到多項限制。如要查看可能的限制清單,請參閱「組織政策限制」。

    如需操作說明,請參閱「建立及編輯政策」。

  • 如果無法更新機構政策,請在「記錄檔路由器」頁面中更新接收器,改用符合規定的目的地。

    前往「記錄檔路由器」

當機構政策不再禁止接收器寫入目的地,且 Logging 收到符合篩選條件的新記錄項目時,接收器就會開始傳送記錄項目。

接收器加密金鑰問題

如果您使用加密金鑰 (無論是透過 Cloud Key Management Service 管理,還是由您管理),對接收器目的地中的資料進行加密,則可能會看到相關錯誤。以下列出一些可能的問題和解決方法:

  • Google Cloud 含有 Cloud KMS 金鑰的專案未啟用計費功能。

    • 即使已使用正確目的地成功建立接收器,如果與含有金鑰的 Google Cloud 專案相關聯的帳單帳戶無效,系統仍會顯示這則錯誤訊息。

    • 請確認專案 Google Cloud 已連結有效的帳單帳戶,且該專案包含金鑰。如果帳單帳戶未連結至Google Cloud 專案,請為該 Google Cloud 專案啟用帳單功能,或使用 Google Cloud 專案所含的 Cloud KMS 金鑰,該專案必須連結至有效的帳單帳戶。

  • 找不到 Cloud KMS 金鑰。

    • 找不到包含已設定用於加密資料的 Cloud KMS 金鑰的 Google Cloud 專案。

    • 使用現有 Google Cloud 專案中的有效 Cloud KMS 金鑰。

  • Cloud KMS 金鑰的位置與目的地位置不符。

    • 如果包含 Cloud KMS 金鑰的 Google Cloud 專案與目的地 所在的區域不同, 加密就會失敗,且接收器無法將資料傳送至該目的地。

    • 使用 Google Cloud 專案中的 Cloud KMS 金鑰,該專案的區域必須與接收器的目的地相符。

  • 接收器的服務帳戶遭拒存取加密金鑰。

    • 即使已使用正確的服務帳戶權限成功建立接收器,如果接收器目的地使用的加密金鑰未授予服務帳戶足夠的資料加密或解密權限,系統仍會顯示這則錯誤訊息。

    • 在接收器的 writerIdentity 欄位中,為目的地使用的金鑰指定服務帳戶,並授予 Cloud KMS CryptoKey Encrypter/Decrypter 角色。此外,請確認已啟用 Cloud KMS API。

接收器的配額問題

接收器寫入記錄項目時,會套用匯出和目的地配額。視目的地而定,系統會在建立接收器的資源 (例如 Pub/Sub) 或目的地本身 (例如 BigQuery) 強制執行配額。如果配額用盡,接收器就會停止將記錄項目轉送至目的地。

  • 將記錄項目轉送至 Pub/Sub 主題的接收器,每分鐘最多只能轉送 60 GB 的資料。如果記錄項目量超過匯出速率配額,系統會寫入含有 topic_over_quota 錯誤代碼的記錄項目。
  • 將資料轉送至 BigQuery 的接收器會受到每個資料表串流資料即時插入配額的限制。如果超出配額,系統會寫入含有 table_resource_exhausted 錯誤代碼的記錄項目。

配額也適用於匯總接收器。這些接收器會轉送所屬資料夾或機構,以及子項資源的記錄項目。

如果是專案層級的接收器,下列指標類型可協助您監控配額用量,並找出錯誤發生時間:

  • logging.googleapis.com/exports/byte_count: 匯出至目的地的記錄項目大小 (以位元組為單位)。
  • logging.googleapis.com/exports/log_entry_count:匯出至目的地的記錄項目數量。
  • logging.googleapis.com/exports/error_count: 無法匯出的記錄項目數量。

如要繪製指標類型圖表,請使用 Metrics Explorer,並篩選特定目的地的資料。這些指標類型不適用於資料夾或機構層級的接收器。

如要修正配額用盡問題,請嘗試下列做法:

  • 更新接收器的篩選條件,減少相符的記錄項目,即可減少要傳送的記錄資料量。您可以在篩選器中使用 sample 函式,選取記錄項目總數的一小部分。

  • 提出支援要求,申請提高配額。

如要瞭解路由記錄項目時可能適用的限制,請參閱適當目的地的配額資訊:

將錯誤記錄至 Cloud Storage

將記錄檔項目傳送至 Cloud Storage 時,最常見的錯誤如下:

  • 遲到記錄項目:

    • 系統會以每小時批次作業的方式,將轉送的記錄檔項目儲存至 Cloud Storage bucket。第一批項目可能需要 2 到 3 個小時才會開始出現。

    • 後置字串為 An (「附加」) 的已路由記錄檔資料分割會保留遲到的記錄項目。如果 Cloud Storage 目的地發生服務中斷,Cloud Logging 會緩衝處理資料,直到服務恢復正常為止。

  • 無法將正確的權限授予目的地:

    如要解決這項失敗問題,請確認記錄檔接收器的服務帳戶具有正確的權限。詳情請參閱本文的「權限問題」一節。

  • 您收到電子郵件通知,或看到記錄項目指出記錄檔接收器設定有誤。錯誤代碼為 bucket_changed_parent_project。

    這個錯誤代碼表示通知中列出的記錄檔接收器已設定為將記錄項目轉送至 Cloud Storage bucket,且 Cloud Storage bucket 的父項專案已變更。在此情境中,Cloud Logging 會將記錄檔接收器標示為設定錯誤,導致接收器無法將記錄項目轉送至 Cloud Storage bucket。

    如要解決這項設定錯誤,請執行下列任一操作:

    • 刪除現有的記錄檔接收器,並建立新的記錄檔接收器,將記錄項目轉送至 Cloud Storage bucket。

    • 將 Cloud Storage bucket 移回 Google Cloud 原始專案。

轉送至 BigQuery 時發生錯誤

將記錄項目傳送至 BigQuery 時,最常見的錯誤如下:

  • 資料表結構定義無效:

    • 串流至 BigQuery 資料集資料表的記錄項目與目前的資料表結構定義不符。常見問題包括嘗試使用不同資料類型的記錄檔項目進行路徑設定,導致結構定義不符。舉例來說,記錄項目中的其中一個欄位是整數,但結構定義中對應的資料欄是字串類型。

    • 請確認記錄檔項目與資料表的結構定義相符。修正錯誤來源後,您可以重新命名目前的資料表,然後讓 Logging 再次建立資料表。

    • BigQuery 支援將巢狀資料載入資料表。不過,從 Logging 載入資料時,資料欄的巢狀深度上限為 13 層。

    如果 BigQuery 發現架構不符,就會在對應的資料集中建立資料表,以儲存錯誤資訊。資料表類型會決定資料表名稱。如果是日期資料分割資料表,命名格式為 export_errors_YYYYMMDD。如果是分區資料表,命名格式為 export_errors。如要瞭解錯誤資料表的結構定義,以及如何避免日後發生欄位類型不符的情況,請參閱「結構定義不符」一文。

  • 記錄檔項目不在允許的時間範圍內:

    • 串流至 BigQuery 分區資料表的記錄檔項目不在允許的時間範圍內。BigQuery 不接受時間戳記在過去或未來較遠時間點的記錄項目。

    • 您可以更新接收器,將這些記錄項目傳送至 Cloud Storage,並使用 BigQuery 載入工作。如需進一步的指示,請參閱 BigQuery 說明文件。

  • 與記錄檔接收器相關聯的服務帳戶權限不足,因此無法寫入資料集:

    • 即使已使用正確的服務帳戶權限成功建立接收器,如果與包含接收器目的地的 Google Cloud 專案沒有相關聯的有效帳單帳戶,系統仍會顯示這則錯誤訊息。

    • 請確認 Google Cloud 專案已連結帳單帳戶。如果帳單帳戶未連結至接收器目的地Google Cloud 專案,請為該 Google Cloud 專案啟用帳單功能,或更新接收器目的地,使其位於已連結有效帳單帳戶的Google Cloud 專案中。

  • 資料集含有重複的記錄項目:

    • 如果串流記錄檔項目至 BigQuery 時發生失敗 (包括重試或設定錯誤),可能會出現重複的記錄檔項目。Cloud Logging 會在查詢時,將具有相同 timestamp 和 insertId 的記錄項目重複資料刪除。BigQuery 不會刪除重複的記錄項目。

    • 如要在 BigQuery 中忽略重複的記錄項目,請在查詢中加入 SELECT DISTINCT 子句。例如:

    SELECT DISTINCT insertId, timestamp FROM TABLE_NAME
    
  • Cloud Logging 警報觸發後,系統會回填記錄項目:

    如果 Cloud Logging 快訊阻止記錄資料路由至 BigQuery,記錄檔就會在回填作業期間自動產生含有 backfill_ 前置字元的資料表。

    前置字元為 backfill_ 的資料表包含所有記錄項目,這些項目會在警報的時間範圍內,路由至 BigQuery。這些資料表可能包含已成功轉送至接收器指定資料表的記錄項目。

    為避免資料重複,建議您將回填資料表中的資料合併至原始資料表,然後刪除回填資料表。

轉送至 Cloud Logging 值區的錯誤

您可能會遇到一種情況:在記錄檔探索工具中,您會看到透過接收器排除的記錄項目。如果符合下列任一條件,您仍可查看這些記錄項目:

  • 您在 Google Cloud 產生記錄檔項目的專案中執行查詢。

    如要修正這個問題,請確認您是在正確的Google Cloud 專案中執行查詢。

  • 排除的記錄項目已傳送至多個記錄儲存空間;您看到的是您要排除的記錄副本。

    如要修正這個問題,請在「記錄檔路由器」頁面中檢查接收器,確認您未在其他接收器的篩選器中納入記錄項目。

  • 您有權存取記錄項目傳送至的記錄檔 bucket 中的檢視畫面。在這種情況下,您預設會看到這些記錄項目。

    如要避免在 Logs Explorer 中看到這些記錄項目,可以縮小搜尋範圍,只搜尋來源 Google Cloud 專案或 bucket。

排解記錄檔儲存問題

為什麼無法刪除這個值區?

如要刪除值區,請按照下列步驟操作:

  • 確認您具備刪除值區的適當權限。如需必要權限清單,請參閱「使用 IAM 控管存取權」。

  • 列出 bucket 的屬性,判斷 bucket 是否已鎖定。如果 bucket 已鎖定,請檢查 bucket 的保留期限。鎖定的 bucket 必須等到所有記錄檔都達到保留期限,才能刪除。

  • 確認記錄檔 bucket 沒有任何連結。您無法刪除含有連結的記錄檔儲存空間。

    在已連結 BigQuery 資料集的記錄檔 bucket 上執行 delete 指令時,系統會顯示下列錯誤:

    FAILED_PRECONDITION: This bucket is used for advanced analytics and has an active link. The link must be deleted first before deleting the bucket
    

    如要列出與記錄檔 bucket 相關聯的連結,請執行 gcloud logging links list 指令或 projects.locations.buckets.links.list API 方法。

    如要刪除連結,請使用 gcloud logging links delete 指令。

哪些服務帳戶正在將記錄檔轉送至我的值區?

如要判斷是否有任何服務帳戶具備將記錄檔傳送至儲存空間的 IAM 權限,請按照下列步驟操作:

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

    前往 IAM

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

  2. 在「權限」分頁標籤中,依「角色」查看。畫面上會顯示表格,列出與Google Cloud 專案相關聯的所有 IAM 角色和主體。

  3. 在表格的「Filter」(篩選器)文字方塊 中,輸入「Logs Bucket Writer」(記錄檔 Bucket 寫入者)。

    畫面上會顯示具備「記錄儲存空間寫入者」角色的所有主體。如果主體是服務帳戶,其 ID 會包含 gserviceaccount.com 字串。

  4. 選用:如要禁止服務帳戶將記錄檔傳送至 Google Cloud 專案,請選取服務帳戶的核取方塊,然後按一下「移除」。

即使我已從 _Default 接收器排除專案,為什麼還是會看到該 Google Cloud 專案的記錄?

您可能正在集中式 Google Cloud 專案的記錄檔 bucket 中查看記錄,該專案會匯總整個機構的記錄。

如果您使用 Logs Explorer 存取這些記錄,並看到從 _Default 接收器排除的記錄,則檢視畫面可能設為Google Cloud 專案層級。

如要修正這個問題,請在「縮小範圍」選單中選取「記錄檢視」,然後選取與Google Cloud 專案中 _Default bucket 相關聯的記錄檢視。您應該不會再看到排除的記錄。