遷移至 Cloud Logging

在第二代執行階段中記錄資料的方式與第一代執行階段不同。升級至較新的執行階段時，最重大的變更之一是，第二代執行階段不支援與 App Engine 預先整合的記錄功能，且記錄不會自動關聯。如果您要遷移至第二代執行階段，就必須使用 Cloud Logging 用戶端程式庫。

本指南說明如何更新應用程式，以便使用 Cloud Logging，並實現與 App Engine 記錄整合時幾乎相同的篩選和記錄相關功能。

Cloud Logging 是即時記錄管理系統，提供儲存、搜尋、分析和監控功能。Cloud Logging 會自動收集 Google Cloud 資源的記錄。您也可以從應用程式、地端部署資源，以及其他雲端服務供應商的資源收集記錄。

主要差異

下表說明第一代與第二代執行階段之間的記錄差異：

第一代執行階段 第二代執行階段
要求和應用程式記錄 (也稱為應用程式記錄) App Engine 會將所有應用程式記錄嵌入要求記錄中。在第一代執行階段中記錄資料時，會使用要求記錄的 protoPayload.line.logMessage 欄位嵌入應用程式記錄。 App Engine 不會將應用程式記錄嵌入相關聯的要求記錄中。App Engine 會在要求記錄中省略 protoPayload.line 屬性。應用程式記錄會根據記錄方法進行路由：
在 Logs Explorer 中查看記錄 第一代執行階段只包含一個記錄類型：appengine.googleapis.com/request_log。展開要求記錄後，您可以看到其中巢狀的應用程式記錄。 第二代執行階段會納入多種記錄類型的記錄，例如 appengine.googleapis.com/request_log、stdout、stderr、logs/python 中的要求記錄，以及其他許多記錄，具體取決於應用程式產生記錄的方式。/var/log/google_init.log 也提供 Google 內部記錄。

由於應用程式記錄不會自動與要求記錄建立關聯，因此您必須採取額外步驟，才能在記錄檔探索工具中顯示要求和應用程式記錄的巢狀檢視畫面。詳情請參閱「將要求記錄與應用程式記錄做關聯」和「在記錄檔探索工具中查看關聯記錄」。
Cloud Trace 整合 自動整合 Cloud Trace，收集延遲時間資料。 您必須手動將應用程式與 Cloud Trace 整合，才能收集 App Engine 的延遲資料。詳情請參閱「Cloud Trace 的檢測器」。
錯誤等級關聯 以 ERROR 嚴重性層級記錄 App Engine 要求記錄檔中擲回的錯誤。Error Reporting 會自動在 Error Reporting 資訊主頁中連結這些詳細資料。 根據預設，App Engine 不會在第二代執行階段中整合 Error Reporting。如要設定記錄整合功能與 Error Reporting，請參閱「使用用戶端程式庫檢測應用程式 」一文。
嚴重性等級 Logs Explorer 會為要求記錄指派嚴重性等級，而嚴重性等級會反映與要求記錄項目相關聯的任何應用程式記錄項目的最高嚴重性。舉例來說，如果要求導致應用程式發出警告記錄項目，記錄檔探索工具就會在要求記錄項目旁顯示警告圖示。展開要求項目後，您會看到警告記錄項目內嵌在要求項目中。 根據預設，所有要求記錄的嚴重性等級為 DEFAULT 或 INFO。即使要求記錄與應用程式記錄相關聯，且記錄檢視器已設定為查看相關聯的記錄，要求記錄仍不會反映相關應用程式記錄的嚴重性。
Logservice API Logservice API 是捆綁服務 SDK 的一部分。 Logservice API 已從 Bundled Services SDK 中移除。詳情請參閱可用 API 清單。

開始遷移前

  1. 在包含應用程式的專案中啟用 Cloud Logging API。

    啟用 API

  2. 確認應用程式具有寫入記錄的權限。

    根據預設，應用程式的預設服務帳戶具有寫入記錄的權限。

    如果應用程式使用不同的服務帳戶，或是您變更了預設服務帳戶的權限，請確認您使用的帳戶具有寫入記錄檔的 logging.logEntries.create 權限。

  3. 熟悉 App Engine 中的不同類型的記錄。

轉換程序總覽

如要將應用程式遷移至使用 Cloud Logging，請按照下列步驟操作：

  1. 安裝 Cloud Logging 適用的 Cloud 用戶端程式庫
  2. 透過 Cloud Logging 寫入記錄檔
  3. 將要求記錄與應用程式記錄建立關聯
  4. 查看記錄檔
  5. 測試應用程式

安裝 Cloud Logging 適用的 Cloud 用戶端程式庫

如要安裝及更新設定檔，請將 Cloud Logging 的 Cloud 用戶端程式庫新增至 requirements.txt 檔案中的依附元件清單，如下所示：

google-cloud-logging

使用標準 Python 記錄模組寫入記錄

在每個寫入記錄項目的檔案中：

  1. 匯入 Cloud Logging 用戶端程式庫。
  2. 建立 Cloud Logging 用戶端例項。
  3. 執行 Cloud Logging 用戶端的 setup_logging() 方法，該方法會將預設的事件監聽器附加為 Python 根記錄器的記錄處理常式。

例如：

# Imports the Cloud Logging client library
import google.cloud.logging

# Instantiates a client
client = google.cloud.logging.Client()

# Retrieves a Cloud Logging handler based on the environment
# you're running in and integrates the handler with the
# Python logging module. By default this captures all logs
# at INFO level and higher
client.setup_logging()

附加處理常式後，根據預設，應用程式中發出的任何 INFO 以上層級記錄都會傳送至記錄：

# Imports Python standard library logging
import logging

# The data to log
text = "Hello, world!"

# Emits the data using the standard logging module
logging.warning(text)

將要求記錄與應用程式記錄相關聯

第一代執行階段支援的部分功能 (例如自動將要求記錄與應用程式記錄建立關聯)，第二代執行階段則不支援。

使用第二代執行階段的應用程式可以透過以下任一方式，實現與第一代執行階段相似的巢狀記錄行為：

  • 在應用程式中設定 Cloud Logging 用戶端，並相關聯記錄。
  • 使用 trace ID 搭配 stdout 和 stderr。

第一代與第二代執行階段的記錄行為有以下差異：

  • 在第一代執行階段中，App Engine 會將處理要求時產生的所有應用程式記錄嵌入要求記錄的 protoPayload.line.logMessage 欄位。這些記錄會透過 appengine.googleapis.com/request_log 顯示在 Logs Explorer 中。

    下圖顯示第一代執行階段中關聯的請求和應用程式記錄：

    在第一代執行階段中記錄

  • 在第二代執行階段中，App Engine 會省略要求記錄中的 protoPayload.line 屬性。應用程式記錄的內容不會顯示在記錄檔探索工具中的 JSON 要求記錄中。每個應用程式記錄都會在 Logs Explorer 中以其記錄名稱個別顯示。

    下圖顯示第二代執行階段中的個別要求和應用程式記錄：

    在第二代執行階段中記錄

以下各節將說明如何使用 Cloud Logging 用戶端，或搭配 stdout 和 stderr 使用結構化記錄，以便比對記錄。

使用 Python 記錄模組

如要在由 Python 記錄模組記錄的應用程式記錄中新增要求關聯，請設定 Cloud Logging 用戶端程式庫。

在應用程式啟動時執行 client.setup_logging() 方法，此方法會將 trace 欄位和 HTTP 要求詳細資料新增至由 Python logging 模組 (例如 logging.info() 和 logging.error()) 編寫的應用程式記錄。這些記錄會路由至 logs/python。

App Engine 也會將這個 trace 欄位新增至相關聯的要求記錄，讓您在 Logs Explorer 中查看相關聯的記錄項目。

使用 stdout 和 stderr

如果您使用 stdout 和 stderr 寫入記錄項目，這些項目會顯示在 Logs Explorer 中。不過，如要啟用篩選功能並與要求記錄建立關聯，您必須將項目格式化為 JSON 物件，並提供特定中繼資料。如要進一步瞭解這種做法，請參閱「將結構化記錄寫入 stdout 和 stderr」。這個方法會透過以下方式，在應用程式記錄檔中新增要求的追蹤記錄 ID：

  1. 從 X-Cloud-Trace-Context 要求標頭中擷取追蹤記錄 ID。
  2. 將 ID 寫入結構化記錄項目中的 logging.googleapis.com/trace 欄位。如要進一步瞭解 X-Cloud-Trace-Context 標頭，請參閱「強制追蹤要求」。

查看記錄

您可以透過多種方式查看應用程式記錄和要求記錄：

使用記錄檔探索工具

您可以使用記錄檔探索工具查看應用程式和要求記錄：

  1. 前往 Google Cloud 控制台的「Logs Explorer」：

    前往「Logs Explorer」

  2. 在頁面頂端選取現有 Google Cloud 專案。

  3. 在「Resource Type」(資源類型) 中，選取「GAE Application」(GAE 應用程式)。

您可以依 App Engine 服務、版本和其他條件篩選記錄總管。您也可以在記錄中搜尋特定項目。詳情請參閱「使用記錄檔探索工具」。

如果您將簡單的文字項目傳送至標準輸出內容，就無法使用記錄檢視器依嚴重程度篩選應用程式項目，也無法查看哪些應用程式記錄對應至特定要求。您仍可在記錄探索器中使用其他類型的篩選功能，例如文字和時間戳記。

在 Logs Explorer 中查看相關聯的記錄項目

如要在 Logs Explorer 中查看與父項記錄項目相關聯的子項記錄項目，請展開記錄項目。

舉例來說，如要顯示 App Engine 要求記錄項目和應用程式記錄項目，請執行下列操作：

  1. 在 Google Cloud 控制台的導覽面板中，依序選取「Logging」和「Logs Explorer」：

    前往「Logs Explorer」

  2. 在「Resource Type」(資源類型) 中，選取「GAE Application」(GAE 應用程式)。

  3. 如要查看並關聯要求記錄，請在「記錄名稱」中選取「request_log」。或者，如要依據要求記錄建立關聯，請按一下「依據」，然後選取「request_log」。

    關聯記錄檔

  4. 如要展開記錄項目，請在「查詢結果」窗格中按一下「展開」。展開後，每個要求記錄都會顯示相關聯的應用程式記錄。

為記錄檔建立篩選器後，每個要求記錄都會顯示對應的應用程式記錄檔做為子項記錄檔。假設應用程式使用 google-cloud-logging 程式庫，Logs Explorer 會透過關聯應用程式記錄檔和指定要求記錄檔中的 trace 欄位來達成這項目標。

下圖顯示按 trace 欄位分組的應用程式記錄：

應用程式記錄項目會巢狀在要求記錄項目中。

使用 Google Cloud CLI

如要透過指令列查看 App Engine 記錄，請使用下列指令：

gcloud app logs tail

詳情請參閱「gcloud app logs tail」。

以程式輔助方式讀取記錄檔

如要以程式輔助方式讀取記錄，您可以使用下列任一方法：

測試應用程式

如果您能夠部署應用程式而不會發生錯誤，表示遷移作業已成功。如要確認 Cloud Logging 是否正常運作，請按照下列步驟操作：

  1. 前往「Logs Explorer」，然後展開要求記錄項目。

    前往「Logs Explorer」

  2. 請確認應用程式在處理要求時產生的應用程式記錄會在要求記錄中巢狀。

  3. 如果所有應用程式端點都能正常運作，請使用流量拆分功能，為更新後的應用程式緩慢增加流量。在將更多流量導向更新後的應用程式前，請密切監控應用程式是否有任何問題。