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

您可以从 Node.js 向 Error Reporting 发送错误报告 如何使用 Google Cloud 中的 Node.js 版 Error Reporting 库。 使用 Node.js 版 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. 登录您的 Google Cloud 账号。如果您是 Google Cloud 新手，请创建一个账号来评估我们的产品在实际场景中的表现。新客户还可获享 $300 赠金，用于运行、测试和部署工作负载。

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

    Go to project selector

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

  4. Enable the Error Reporting API .

    Enable the API

    5.

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

    Go to project selector

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

  7. Enable the Error Reporting API .

    Enable the 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 写入者角色 (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 写入者角色 (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 写入者角色 (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 Run 函数可 Error Reporting Writer 角色 (roles/errorreporting.writer) 您的默认服务账号

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

Cloud Run 函数已配置为使用 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. Install the Google Cloud CLI.

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

    gcloud init

  3. 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.

如需了解详情，请参阅 Set up authentication for a local development environment。

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 页面：

前往 Error Reporting

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

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