为 Error Reporting 插桩 Python 应用

您可以使用 Python 版 Error Reporting 库，从 Python 应用向 Error Reporting 发送错误报告。 使用 Python 版 Error Reporting 库可为以下情况创建错误组：

• 包含日志条目的日志存储桶具有客户管理的加密密钥 (CMEK)。
• 日志存储桶满足以下条件之一：
  • 日志存储桶存储在日志条目源自的项目中。
  • 日志条目被路由到某个项目，然后该项目将这些日志条目存储在自己拥有的日志存储桶中。
• 您想报告自定义错误事件。

Error Reporting 已与某些 Google Cloud 服务集成，例如 Cloud Functions、App Engine、Compute Engine 和 Google Kubernetes Engine。Error Reporting 可显示在这些服务上运行的应用记录到 Cloud Logging 中的错误。如需了解详情，请参阅本页面上的在 Google Cloud上运行。

您还可以使用 Logging 将错误数据发送到 Error Reporting。如需了解数据格式设置要求，请参阅设置 Logging 中的错误消息格式。

准备工作

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

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

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. Make sure that billing is enabled for your Google Cloud project.

4. Enable the Error Reporting API .

   Enable the API

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

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

6. Make sure that billing is enabled for your Google Cloud project.

7. Enable the Error Reporting API .

   Enable the API

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 版 Error Reporting 库的文档。您还可以使用问题跟踪器来报告问题。

配置客户端库

您可以自定义 Python 版 Error Reporting 库的行为。有关配置示例，请参阅客户端库文档。

在 Google Cloud上运行应用

如需使用 projects.events.report 创建错误组，您的服务账号需要具有Error Reporting Writer 角色 (roles/errorreporting.writer)。

某些 Google Cloud 服务会自动向相应的服务账号授予 Error Reporting Writer 角色 (roles/errorreporting.writer)。不过，对于某些服务，您必须将此角色授予相应的服务账号。

Cloud Run 和 Cloud Run functions

Cloud Run 使用的默认服务账号具有错误报告写入者角色 (roles/errorreporting.writer) 的权限。

您无需明确提供凭据即可使用 Python 版 Error Reporting 库。

Cloud Run 已配置为自动使用 Error Reporting。未处理的 JavaScript 异常将在 Logging 中显示，并且会由 Error Reporting 进行处理，而无需使用 Python 版 Error Reporting 库。

注意： 如果日志条目包含堆栈轨迹，并且未指定日志严重级别或至少指定了 ERROR 日志严重级别，则系统会自动处理这些条目，而无需使用 Python 版 Error Reporting 库。

App Engine 柔性环境

App Engine 会自动向您的默认服务账号授予 Error Reporting Writer 角色 (roles/errorreporting.writer)。

您无需明确提供凭据即可使用 Python 版 Error Reporting 库。

系统会自动为 App Engine 柔性环境应用启用 Error Reporting。 无需进行额外设置。
注意： 写入 stderr 的错误日志条目由 Error Reporting 自动处理，而无需直接使用 Python 版 Error Reporting 库。

Google Kubernetes Engine

如需将 Error Reporting 与 Google Kubernetes Engine 搭配使用，请执行以下操作：

1. 确保已向容器将使用的服务账号授予 Error Reporting Writer 角色 (roles/errorreporting.writer)。

   您可以使用 Compute Engine 默认服务账号或自定义服务账号。

   如需了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

2. 创建集群，并向该集群授予 cloud-platform 访问权限范围。

   例如，以下创建命令指定了 cloud-platform 访问权限范围和服务账号：

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

注意： 创建集群后，无法更改其服务账号。

Compute Engine

如需将 Error Reporting 与 Compute Engine 虚拟机实例搭配使用，请执行以下操作：

1. 确保虚拟机实例要使用的服务账号已被授予错误报告写入者角色 (roles/errorreporting.writer)。

   您可以使用 Compute Engine 默认服务账号或自定义服务账号。

   如需了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

2. 在 Google Cloud 控制台中，前往虚拟机实例页面：

   前往虚拟机实例

   如果您使用搜索栏查找此页面，请选择子标题为 Compute Engine 的结果。

3. 选择要接收 cloud-platform 访问权限范围的虚拟机实例。

4. 点击停止，然后点击修改。

5. 在身份和 API 访问权限部分，选择具有 Error Reporting Writer 角色 (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，然后使用您的用户凭证设置应用默认凭证。

9. Install the Google Cloud CLI.

10. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

11. To initialize the gcloud CLI, run the following command:

    gcloud init

12. If you're using a local shell, then create local authentication credentials for your user account:

    gcloud auth application-default login

    You don't need to do this if you're using Cloud Shell.

    Note: If the gcloud CLI prints a warning that your account doesn't have the serviceusage.services.use permission, then some gcloud CLI commands and client libraries might not work. Ask an administrator to grant you the Service Usage Consumer IAM role (roles/serviceusage.serviceUsageConsumer), then run the following command:

    gcloud auth application-default set-quota-project PROJECT_ID

    If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

如需了解详情，请参阅 Set up authentication for a local development environment。 如需了解详情，请参阅身份验证文档中的为本地开发环境设置 ADC。

查看错误报告

在 Google Cloud 控制台中，前往 Error Reporting 页面：

前往 Error Reporting

您也可以使用搜索栏查找此页面。

如需了解详情，请参阅查看错误。