为 Error Reporting 插桩 Ruby 应用

借助 Ruby 版 Error Reporting 库，您可以直接从 Ruby 应用向 Error Reporting 发送错误事件，以便诊断和监控运行时崩溃。使用该库对应用进行插桩处理后，即使日志存储桶使用客户管理的加密密钥 (CMEK)，您也可以报告自定义错误事件并捕获错误。

对于在集成 Google Cloud 服务（包括 Cloud Run 函数、App Engine、Compute Engine 和 Google Kubernetes Engine）上运行的应用，Error Reporting 还可以从 Cloud Logging 自动推断错误事件，而无需使用适用于 Ruby 的 Error Reporting 库。为了让 Error Reporting 从日志中推断出错误事件，您的日志条目必须遵循错误格式要求，并且必须存储在非 CMEK 日志存储桶中，该存储桶归原始项目或日志路由到的目标项目所有。

准备工作

登录您的 Google Cloud 账号。如果您是 Google Cloud新手，请 创建一个账号来评估我们的产品在实际场景中的表现。新客户还可获享 $300 赠金，用于运行、测试和部署工作负载。

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.

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

Verify that billing is enabled for your Google Cloud project.

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

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.

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

Verify that billing is enabled for your Google Cloud project.

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

1. 安装 Ruby 2.2+ 或更高版本。

安装客户端库

借助适用于 Ruby 的 Error Reporting 库，您可以监控和查看在几乎任何位置运行的 Ruby 应用报告的错误事件。

1. 将 google-cloud-error_reporting gem 添加到您的 Gemfile 中：

   gem "google-cloud-error_reporting"

2. 使用 Bundler 安装 gem：

   bundle install

启用库

如果您正在使用 Ruby on Rails，Bundler 会在启动时自动将库加载到您的应用中。

其他基于 Rack 的应用可以使用库提供的 Rack Middleware：

require "google/cloud/error_reporting"

use Google::Cloud::ErrorReporting::Middleware

如需详细了解如何安装，请参阅 Ruby 版 Error Reporting 库的文档。您还可以使用问题跟踪器来报告问题。

配置客户端库

您可以自定义 Ruby 版 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 使用的默认服务账号具有Error Reporting (与 Stackdriver 搭配使用时) 写入者角色 (roles/errorreporting.writer) 的权限。

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

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

注意： 当日志条目包含堆栈轨迹且日志条目的严重程度未设置或设置为至少 ERROR 时，Error Reporting 会自动创建错误事件。

使用 Ruby on Rails 配置界面

要在 Ruby on Rails 框架中使用 Ruby 版 Error Reporting 库，请通过 Ruby on Rails 配置界面提供如下参数：

# Add this to config/environments/*.rb
Rails.application.configure do |config|
  # Stackdriver Error Reporting specific parameters
  config.google_cloud.error_reporting.project_id = "YOUR-PROJECT-ID"
  config.google_cloud.error_reporting.keyfile    = "/path/to/service-account.json"
end

您还可以使用以下代码为所有 Stackdriver gem 设置共享配置：

# Add this to config/environments/*.rb
Rails.application.configure do |config|
  # Stackdriver Shared parameters
  config.google_cloud.project_id = "YOUR-PROJECT-ID"
  config.google_cloud.keyfile    = "/path/to/service-account.json"
end

如果 Rails 在生产模式下运行，则 Error Reporting 默认处于启用状态。要在开发模式下启用 Error Reporting，请添加以下代码：

# Add this to config/environments/development.rb
Rails.application.configure do |config|
  config.google_cloud.use_error_reporting = true
end

使用 instrumentation 配置界面

如需在其他基于 Rack 的应用中使用 Ruby 版 Error Reporting 库，请通过配置界面提供如下参数：

require "google/cloud/error_reporting"

Google::Cloud.configure do |config|
  # Stackdriver Error Reporting specific parameters
  config.error_reporting.project_id = "YOUR-PROJECT-ID"
  config.error_reporting.keyfile    = "/path/to/service-account.json"
end

您还可以使用以下代码，为所有 Google Cloud Observability gem 设置共享配置：

require "stackdriver"

Google::Cloud.configure do |config|
  # Stackdriver Shared parameters
  config.project_id = "YOUR-PROJECT-ID"
  config.keyfile    = "/path/to/service-account.json"
end

App Engine 柔性环境

App Engine 会自动向您的默认服务账号授予Error Reporting (与 Stackdriver 搭配使用时) 写入者角色 (roles/errorreporting.writer)。

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

系统会自动为 App Engine 柔性环境应用启用 Error Reporting。 无需进行额外设置。

注意： 写入 stderr 的错误日志条目会自动由 Error Reporting 处理，而无需直接使用 Ruby 版 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. 确保虚拟机实例要使用的服务账号已被授予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. 点击启动/恢复。

示例

报告基于 Rack 的框架中的错误

通过 Ruby 版 Error Reporting 库，您可以将 Error Reporting 轻松集成到常用的基于 Rack 的 Ruby Web 框架中，例如 Ruby on Rails 和 Sinatra。该库启用后，它会自动报告从应用的 Rack 堆栈捕获的异常。

手动报告错误

您可以调用 report 方法来手动报告错误，如以下示例所示：

require "google/cloud/error_reporting"

begin
  raise "Something went wrong"
rescue StandardError => e
  Google::Cloud::ErrorReporting.report e
end

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

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

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

1. 安装 Google Cloud CLI。

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

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

   gcloud auth application-default login

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

   注意：如果 gcloud CLI 输出警告，提示您的账号没有 serviceusage.services.use 权限，则某些 gcloud CLI 命令和客户端库可能无法正常运行。请让管理员授予您 Service Usage Consumer IAM 角色 (roles/serviceusage.serviceUsageConsumer)，然后运行以下命令：

   gcloud auth application-default set-quota-project PROJECT_ID

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

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

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

使用 Ruby on Rails 配置界面

要在 Ruby on Rails 框架中使用 Ruby 版 Error Reporting 库，请通过 Ruby on Rails 配置界面提供如下参数：

# Add this to config/environments/*.rb
Rails.application.configure do |config|
  # Stackdriver Error Reporting specific parameters
  config.google_cloud.error_reporting.project_id = "YOUR-PROJECT-ID"
  config.google_cloud.error_reporting.keyfile    = "/path/to/service-account.json"
end

您还可以使用以下代码为所有 Stackdriver gem 设置共享配置：

# Add this to config/environments/*.rb
Rails.application.configure do |config|
  # Stackdriver Shared parameters
  config.google_cloud.project_id = "YOUR-PROJECT-ID"
  config.google_cloud.keyfile    = "/path/to/service-account.json"
end

如果 Rails 在生产模式下运行，则 Error Reporting 默认处于启用状态。要在开发模式下启用 Error Reporting，请添加以下代码：

# Add this to config/environments/development.rb
Rails.application.configure do |config|
  config.google_cloud.use_error_reporting = true
end

使用 instrumentation 配置界面

如需在其他基于 Rack 的应用中使用 Ruby 版 Error Reporting 库，请通过配置界面提供如下参数：

require "google/cloud/error_reporting"

Google::Cloud.configure do |config|
  # Stackdriver Error Reporting specific parameters
  config.error_reporting.project_id = "YOUR-PROJECT-ID"
  config.error_reporting.keyfile    = "/path/to/service-account.json"
end

您还可以使用以下代码，为所有 Google Cloud Observability gem 设置共享配置：

require "stackdriver"

Google::Cloud.configure do |config|
  # Stackdriver Shared parameters
  config.project_id = "YOUR-PROJECT-ID"
  config.keyfile    = "/path/to/service-account.json"
end

查看错误组

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

前往 Error Reporting

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

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