为 C# 应用插桩以实现 Error Reporting

您可以使用 Google.Cloud.Diagnostics 库集 ，从 C# 应用向 Error Reporting 发送错误事件。 在以下情况下，请使用 Google.Cloud.Diagnostics 库集 创建错误组：

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

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

您还可以使用 Logging将错误事件发送到 Error Reporting。如需了解数据格式设置 要求，请参阅 设置日志条目格式以报告错误事件。

准备工作

  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 .

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. 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 .

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

    8.

安装客户端库

借助 Google.Cloud.Diagnostics 库集 ，您可以监控和查看在几乎任何位置运行的 C# 应用所报告的错误事件。

  1. 对于以 ASP.NET Core 3 或更高版本为目标的应用，请使用 Google.Cloud.Diagnostics.AspNetCore3 库。您可以从 NuGet安装此库。
  2. 对于以早期版本的 ASP.NET Core 为目标的应用，请使用 Google.Cloud.Diagnostics.AspNetCore 库。您可以从 NuGet安装此库。
  3. 对于以非 ASP.NET Core 框架为目标的应用，请使用 Google.Cloud.Diagnostics.Common 库。您可以从 NuGet安装此库。

如需详细了解如何安装，请参阅 Google.Cloud.Diagnostics 库集 的 文档。您还可以使用 问题跟踪器来报告问题。

配置客户端库

如需了解详情和示例，请参阅以下资源：

  • Google.Cloud.Diagnostics.AspNetCore3 文档
  • Google.Cloud.Diagnostics.AspNetCore 文档
  • Google.Cloud.Diagnostics.Common 文档

    • 在 上运行应用 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 使用的默认服务帐号具有 Error Reporting Writer 角色 (roles/errorreporting.writer) 的 权限。

    无需明确提供 凭据即可使用 Google.Cloud.Diagnostics 库集。

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

    App Engine 柔性环境

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

    无需明确提供 凭据即可使用 Google.Cloud.Diagnostics 库集。

    系统会自动为 App Engine 柔性环境应用启用 Error Reporting。无需进行额外设置。 Error Reporting 将对从 App Engine 写入到 stderr 的消息进行分析；如果发现包含堆栈轨迹，则显示这些消息。

    请参阅查看错误，了解如何在 控制台中查看应用的错误和异常数据。Google Cloud

    Google Kubernetes Engine

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

    1. 确保您的容器要使用的服务帐号已被 授予 Error Reporting Writer 角色 (roles/errorreporting.writer)。

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

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

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

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

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

    Compute Engine

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

    1. 确保您的虚拟机实例要使用的服务帐号已被 授予 Error Reporting Writer 角色 (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. 点击启动/恢复 。

    示例

    如需了解详情和示例，请参阅以下资源：

  • Google.Cloud.Diagnostics.AspNetCore3 文档
  • Google.Cloud.Diagnostics.AspNetCore 文档
  • Google.Cloud.Diagnostics.Common 文档

    • 在本地开发环境中运行应用

    如需在本地开发环境中使用 Google.Cloud.Diagnostics 库集 （例如在您自己的工作站上运行该库），您必须向 Google.Cloud.Diagnostics 库集 提供本地应用默认凭据。 如需了解详情，请参阅向 Error Reporting 进行身份验证。

    如需在本地开发环境中使用本页面上的 .NET 示例，请安装并 初始化 gcloud CLI，然后使用您的用户凭证设置应用默认凭据。

    1. 安装 Google Cloud CLI。

    2. 如果您使用的是外部身份提供方 (IdP)，则必须先 使用联合身份登录 gcloud CLI。

    3. 如果您使用的是本地 shell，请为您的用户 账号创建本地身份验证凭证： 

      gcloud auth application-default login

      如果您使用的是 Cloud Shell，则无需执行此操作。

      如果返回身份验证错误，并且您使用的是外部身份提供方 (IdP)，请确认您已使用联合身份登录 gcloud CLI 。

    如需了解详情，请参阅 为本地开发环境设置身份验证。

    The projects.events.report method also supports API keys. 如果您要使用 API 密钥进行身份验证，则无需 设置本地应用默认凭据文件。 如需了解详情，请参阅 身份验证文档 中的 Google Cloud 创建 API 密钥。

    查看错误组

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

    前往 Error Reporting

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

    如需了解详情，请参阅 查看和过滤错误组。