遷移至 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 屬性。應用程式記錄會根據記錄方法進行路徑設定： stdout 和 stderr：將記錄檔路徑 (例如 print()) 轉送至 logs/stdout 或 logs/stderr。 設定 Cloud Logging 用戶端後，Python 記錄模組 會將 Python 根記錄模組 (例如 logging.info() 和 logging.error()) 寫入的所有記錄，路由至 logs/python。 如果 Python 適用的 Cloud Logging 用戶端程式庫未設定關聯性，Python 根記錄模組預設會將記錄路徑設為 logs/stderr。
在記錄檔探索工具中查看記錄	第一代執行階段只包含一種記錄類型，即 appengine.googleapis.com/request_log。展開要求記錄後，您會看到巢狀結構的應用程式記錄。	第二代執行階段包含多種記錄類型，例如 appengine.googleapis.com/request_log、stdout、stderr、logs/python 中的要求記錄，以及更多記錄，具體取決於應用程式發出記錄的方式。Google 內部記錄也會顯示在 /var/log/google_init.log 中。 由於應用程式記錄不會自動與要求記錄建立關聯，因此必須採取額外步驟，才能在記錄檔探索工具中顯示要求和應用程式記錄的巢狀檢視畫面。詳情請參閱「將要求記錄與應用程式記錄相互關聯」和「在記錄檔探索工具中查看相關聯的記錄」。
整合 Cloud Trace	自動與 Cloud Trace 整合，收集延遲時間資料。	您必須手動將應用程式與 Cloud Trace 整合，才能收集 App Engine 的延遲資料。詳情請參閱「檢測 Cloud Trace」。
錯誤等級關聯	在 App Engine 要求記錄中，以 ERROR 嚴重性層級記錄擲回的錯誤。Error Reporting 資訊主頁會自動將這些詳細資料相互關聯。	依預設，App Engine 不會在第二代執行階段整合 Error Reporting。如要設定與 Error Reporting 的記錄整合，請參閱「使用用戶端程式庫檢測應用程式 」。
嚴重程度	Logs Explorer 會為要求記錄指派嚴重程度，而嚴重程度會反映與要求記錄項目相關聯的任何應用程式記錄項目中，嚴重程度最高的項目。舉例來說，如果要求導致應用程式發出警告記錄項目，記錄檔探索工具會在要求記錄項目旁顯示警告圖示。展開請求項目後，您會看到巢狀結構的請求項目內含警告記錄項目。	根據預設，所有要求記錄的嚴重性等級為 DEFAULT 或 INFO。 即使要求記錄與應用程式記錄相關聯，且 Logs Explorer 已設定為查看相關聯的記錄，要求記錄也不會反映相關聯應用程式記錄的嚴重程度。
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 層級以上的記錄檔，依預設都會傳送至 Logging：

# 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 欄位新增至相關聯的要求記錄，因此您可以在 Log Explorer 中查看相關的記錄項目。

使用 stdout 和 stderr

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

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

查看記錄

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

• 在 Google Cloud 控制台中，使用 Cloud Logging 的記錄檔探索工具。
• 使用 Google Cloud CLI，透過 gcloud 查看記錄。
• 以程式輔助方式讀取記錄，方法不一而足。

使用記錄檔探索工具

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

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

   前往 Logs Explorer

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

3. 在「資源類型」中，選取「GAE 應用程式」。

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

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

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

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

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

1. 在 Google Cloud 控制台的導覽面板中，依序選取「Logging」(記錄) 和「Logs Explorer」(記錄檔探索工具)：

   前往 Logs Explorer

2. 在「資源類型」中，選取「GAE 應用程式」。

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

   

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

為記錄檔建立篩選器後，每個要求記錄檔都會顯示對應的應用程式記錄檔 (子項記錄檔)。Logs Explorer 會關聯應用程式記錄檔和指定要求記錄檔中的 trace 欄位，前提是應用程式使用 google-cloud-logging 程式庫。

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

使用 Google Cloud CLI

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

gcloud app logs tail

詳情請參閱 gcloud app logs tail。

以程式輔助方式讀取記錄

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

• 使用記錄接收器將記錄檔傳送至 Pub/Sub，並使用指令碼從 Pub/Sub 提取記錄檔。
• 透過程式設計語言的用戶端程式庫呼叫 Cloud Logging API。
• 直接呼叫 Cloud Logging API REST 端點。

測試應用程式

如果可以部署應用程式且沒有錯誤，即代表遷移作業成功。如要確認 Cloud Logging 是否正常運作，請按照下列步驟操作：

1. 前往記錄檔探索工具，然後展開要求記錄項目。

   前往 Logs Explorer

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

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