对 Node.js 应用进行插桩处理以生成 Error Reporting

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

  • 您的日志存储桶具有客户管理的加密密钥 (CMEK)。
  • 您的日志存储分区不在 global 区域。
  • 您想要报告自定义错误事件。

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

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

准备工作

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

  2. 在 Google Cloud Console 中的项目选择器页面上，选择或创建一个 Google Cloud 项目。

    转到“项目选择器”

  3. 确保您的 Google Cloud 项目已启用结算功能。

  4. 启用 Error Reporting API 。

    启用 API

    5.

  5. 在 Google Cloud Console 中的项目选择器页面上，选择或创建一个 Google Cloud 项目。

    转到“项目选择器”

  6. 确保您的 Google Cloud 项目已启用结算功能。

  7. 启用 Error Reporting API 。

    启用 API

    8.
  8. 为 Node.js 开发准备好环境。

    转到 Node.js 设置指南

安装客户端库

借助 Node.js 版 Error Reporting 库，您可以监控和查看几乎在任何位置运行的 Node.js 应用所报告的错误。

  1. 使用 npm 安装该软件包：

    npm install --save @google-cloud/error-reporting

  2. 导入库并实例化客户端，以开始报告错误：

    // Imports the Google Cloud client library
const {ErrorReporting} = require('@google-cloud/error-reporting');

// Instantiates a client
const errors = new ErrorReporting();

// Reports a simple error
errors.report('Something broke!');

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

配置客户端库

您可以自定义 Node.js 版 Error Reporting 库的行为。如需查看可能的配置选项的列表，请参阅库的配置。这些选项可以在传递到库构造函数的 options 对象中传递。

其他集成

如需详细了解 Node.js 版 Error Reporting 库与其他 Node.js Web 框架之间的集成，请参阅 GitHub 上该库的代码库。

在 Google Cloud 上运行应用

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

某些 Google Cloud 服务会自动将 Error Reporting Writer 角色 (roles/errorreporting.writer) 授予相应的服务帐号。但是，您必须将此角色授予某些服务的相应服务帐号。

App Engine 柔性环境

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

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

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

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. 点击启动/恢复。

Cloud Functions

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

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

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

示例：

// Imports the Google Cloud client library
const {ErrorReporting} = require('@google-cloud/error-reporting');

// Instantiates a client
const errors = new ErrorReporting({
  projectId: 'your-project-id',
  keyFilename: '/path/to/key.json',
});

// Reports a simple error
errors.report('Something broke!');

示例

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

// Imports the Google Cloud client library
const {ErrorReporting} = require('@google-cloud/error-reporting');

// Instantiates a client
const errors = new ErrorReporting();

// Use the error message builder to customize all fields ...
const errorEvent = errors.event();

// Add error information
errorEvent.setMessage('My error message');
errorEvent.setUser('root@nexus');

// Report the error event
errors.report(errorEvent, () => {
  console.log('Done reporting error event!');
});

// Report an Error object
errors.report(new Error('My error message'), () => {
  console.log('Done reporting Error object!');
});

// Report an error by provided just a string
errors.report('My error message', () => {
  console.log('Done reporting error string!');
});

使用 Express.js 报告错误

通过 Node.js 版 Error Reporting 库，您可以将 Error Reporting 轻松集成到常用的 Node.js Web 框架中，例如 Express.js：

const express = require('express');

// Imports the Google Cloud client library
const {ErrorReporting} = require('@google-cloud/error-reporting');

// Instantiates a client
const errors = new ErrorReporting();

const app = express();

app.get('/error', (req, res, next) => {
  res.send('Something broke!');
  next(new Error('Custom error message'));
});

app.get('/exception', () => {
  JSON.parse('{"malformedJson": true');
});

// Note that express error handling middleware should be attached after all
// the other routes and use() calls. See the Express.js docs.
app.use(errors.express);

const PORT = process.env.PORT || 8080;
app.listen(PORT, () => {
  console.log(`App listening on port ${PORT}`);
  console.log('Press Ctrl+C to quit.');
});

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

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

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

  1. 安装 Google Cloud CLI。

  2. 如需初始化 gcloud CLI，请运行以下命令： 

    gcloud init

  3. 为您的 Google 账号创建本地身份验证凭据：

    gcloud auth application-default login

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

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

示例：

// Imports the Google Cloud client library
const {ErrorReporting} = require('@google-cloud/error-reporting');

// Instantiates a client
const errors = new ErrorReporting({
  projectId: 'your-project-id',
  keyFilename: '/path/to/key.json',
});

// Reports a simple error
errors.report('Something broke!');

查看错误报告

在 Google Cloud 控制台的导航面板中，选择 Error Reporting，然后选择您的 Google Cloud 项目：

前往 Error Reporting

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