為 Python 應用程式進行檢測，以便回報錯誤

您可以使用 Python 適用的 Error Reporting 程式庫，直接從 Python 應用程式將錯誤事件傳送至 Error Reporting，以便診斷及監控執行階段當機情形。使用程式庫檢測應用程式，即可回報自訂錯誤事件，並擷取錯誤，即使記錄檔儲存空間使用客戶管理的加密金鑰 (CMEK) 也是如此。

對於在整合式 Google Cloud 服務 (包括 Cloud Run 函式、App Engine、Compute Engine 和 Google Kubernetes Engine) 上執行的應用程式，Error Reporting 也可以從 Cloud Logging 自動推斷錯誤事件，不必使用 Python 適用的 Error Reporting 程式庫。如要讓 Error Reporting 從記錄檔推斷錯誤事件，記錄檔項目必須符合錯誤格式規定，並儲存在非 CMEK 記錄檔 bucket 中，且該 bucket 必須由原始專案或記錄檔轉送目的地專案擁有。

事前準備

  1. 登入 Google Cloud 帳戶。如果您是 Google Cloud新手，歡迎 建立帳戶，親自評估產品在實際工作環境中的成效。新客戶還能獲得價值 $300 美元的免費抵免額，可用於執行、測試及部署工作負載。

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Error Reporting API , if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Error Reporting API , if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

    8.
  8. 準備 Python 開發環境。

    前往 Python 設定指南

安裝用戶端程式庫

您可以使用 Python 適用的 Error Reporting 程式庫，監控及查看幾乎在任何位置執行的 Python 應用程式回報的錯誤事件。

  1. 建立虛擬環境，並使用 pip 安裝套件：

    pip install google-cloud-error-reporting --upgrade

  2. 匯入程式庫並例項化用戶端，即可開始回報錯誤：

    Python

    如要向 Error Reporting 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

    #!/usr/bin/env python
#
# Copyright 2022 Google, Inc.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#    http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.


def report_exception():
    from google.cloud import error_reporting

    client = error_reporting.Client()
    try:
        raise Exception("Something went wrong")
    except Exception:
        client.report_exception()




def report_manual_error():
    from google.cloud import error_reporting

    client = error_reporting.Client()
    client.report("An error has occurred.")




if __name__ == "__main__":
    report_exception()
    report_manual_error()

如要進一步瞭解如何安裝，請參閱 Python 錯誤回報程式庫的說明文件。您也可以使用問題追蹤工具報告問題。

設定用戶端程式庫

您可以自訂 Python 適用的 Error Reporting 程式庫行為。如需設定範例，請參閱 用戶端程式庫說明文件 。

在 Google Cloud上執行應用程式

如要使用 projects.events.report 建立錯誤群組，服務帳戶必須具備錯誤報告寫入者角色 (roles/errorreporting.writer)。

部分 Google Cloud 服務會自動將錯誤報告寫入者角色 (roles/errorreporting.writer) 授予適當的服務帳戶。不過，您必須為某些服務的適當服務帳戶授予這個角色。

Cloud Run 和 Cloud Run functions

Cloud Run 使用的預設服務帳戶具有Error Reporting Writer 角色 (roles/errorreporting.writer) 的權限。

使用 Python 適用的 Error Reporting 程式庫時，不必明確提供憑證。

Cloud Run 會自動設定使用 Error Reporting。未處理的 JavaScript 例外狀況會顯示在記錄中，並由錯誤報告處理，無須使用 Python 的錯誤報告程式庫。

App Engine 彈性環境

App Engine 會自動將Error Reporting Writer 角色 (roles/errorreporting.writer) 授予預設服務帳戶。

使用 Python 適用的 Error Reporting 程式庫時，不必明確提供憑證。

系統會自動為 App Engine 彈性環境應用程式啟用 Error Reporting。您不需要另外進行設定。

Google Kubernetes Engine

如要在 Google Kubernetes Engine 中使用 Error Reporting，請按照下列步驟操作：

  1. 確認容器使用的服務帳戶已獲派錯誤報告寫入者角色 (roles/errorreporting.writer)。

    您可以使用 Compute Engine 預設服務帳戶或自訂服務帳戶。

    如要瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」。

  2. 建立叢集，並授予叢集 cloud-platform access scope。

    舉例來說，下列建立指令會指定cloud-platform存取權範圍和服務帳戶：

    gcloud container clusters create CLUSTER_NAME --service-account  SERVICE_ACCT_NAME --scopes=cloud-platform

Compute Engine

如要搭配使用 Error Reporting 和 Compute Engine VM 執行個體，請按照下列步驟操作：

  1. 確認 VM 執行個體使用的服務帳戶已獲派「Error Reporting Writer」角色 (roles/errorreporting.writer)。

    您可以使用 Compute Engine 預設服務帳戶或自訂服務帳戶。

    如要瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」。

  2. 前往 Google Cloud 控制台的「VM instances」(VM 執行個體) 頁面：

    前往「VM instances」(VM 執行個體) 頁面

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

  3. 選取要接收cloud-platform 存取權範圍的 VM 執行個體。

  4. 依序點選「停止」和「編輯」。

  5. 在「身分及 API 存取權」部分，選取具有 Error Reporting 寫入者角色 (roles/errorreporting.writer) 的服務帳戶。

  6. 在「存取權範圍」部分，選取「允許所有 Cloud API 的完整存取權」，然後儲存變更。

  7. 點選「啟動/重新啟用」。

範例

您可以呼叫 report 方法手動回報錯誤，如下列範例所示：

Python

如要向 Error Reporting 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定驗證」。

#!/usr/bin/env python
#
# Copyright 2022 Google, Inc.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#    http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.


def report_exception():
    from google.cloud import error_reporting

    client = error_reporting.Client()
    try:
        raise Exception("Something went wrong")
    except Exception:
        client.report_exception()




def report_manual_error():
    from google.cloud import error_reporting

    client = error_reporting.Client()
    client.report("An error has occurred.")




if __name__ == "__main__":
    report_exception()
    report_manual_error()

在本機開發環境中執行應用程式

如要在本機開發環境中使用 Python 適用的 Error Reporting 程式庫 (例如在自己的工作站上執行程式庫)，您必須為 Python 適用的 Error Reporting 程式庫提供本機應用程式預設憑證。詳情請參閱「向 Error Reporting 進行驗證」。

如要在本機開發環境中使用本頁的 Python 範例，請安裝並初始化 gcloud CLI，然後使用您的使用者憑證設定應用程式預設憑證。

  1. 安裝 Google Cloud CLI。

  2. 若您採用的是外部識別資訊提供者 (IdP)，請先 使用聯合身分登入 gcloud CLI。

  3. 如果您使用本機殼層，請為使用者帳戶建立本機驗證憑證： 

    gcloud auth application-default login

    如果您使用 Cloud Shell，則不需要執行這項操作。

    如果系統傳回驗證錯誤，且您使用外部識別資訊提供者 (IdP)，請確認您已 使用聯合身分登入 gcloud CLI。

詳情請參閱 這篇文章，瞭解如何設定本機開發環境的驗證機制。

projects.events.report 方法也支援 API 金鑰。 如要使用 API 金鑰進行驗證，則無須設定本機應用程式預設憑證檔案。詳情請參閱 Google Cloud 驗證說明文件中的「建立 API 金鑰」。

查看錯誤群組

前往 Google Cloud 控制台的「Error Reporting」頁面：

前往Error Reporting

您也可以透過搜尋列找到這個頁面。

詳情請參閱「查看及篩選錯誤群組」。