后追踪节点 SDK

回溯跟踪 在您的生产软件中抓取和处理的报告和未处理的例外 您可以通过完整的产品生命周期管理应用质量.

这个 @ 回溯跟踪/节点 SDK将您的JavaScript应用程序连接到 Backtrace. 基本的整合是快速和容易的, 之后可以探索丰富的回溯追踪特征集.

目录

1. 基本整合 - 报告您的第一个错误
   • 安装软件包
   • 整合 SDK
   • 上传源代码图
2. 报告特性出错
   • 属性
   • 文件附件
   • 面包屑
   • 应用稳定性计量
     • 计量配置
     • 计量使用量
   • 离线数据库支持
     • 数据库配置
     • 本地崩溃支持
     • 手工数据库操作
3. 高级 SDK 特性
   • 回溯跟踪快捷选项
   • 手动发送错误
   • 修改/skip 错误报告
   • SDK 方法覆盖

基本融合

安装软件包

$ npm install @backtrace/node

整合 SDK

在所有其他脚本之前将以下代码添加到您的应用程序中,向 Backtrace 报告节点错误 .

// Import the BacktraceClient from @backtrace/node with your favorite package manager.
import { BacktraceClient, BacktraceConfiguration } from '@backtrace/node';

// Configure client options
const options: BacktraceConfiguration = {
    // Submission url
    // <universe> is the subdomain of your Backtrace instance (<universe>.backtrace.io)
    // <token> can be found in Project Settings/Submission tokens
    url: 'https://submit.backtrace.io/<universe>/<token>/json',
};

// Initialize the client with the options
const client = BacktraceClient.initialize(options);

// By default, Backtrace will send an error for Uncaught Exceptions and Unhandled Promise Rejections

// Manually send an error
client.send(new Error('Something broke!'));

上传源代码图

客户端错误报告基于已修改的代码. 上传源代码和源代码以解析已修改的代码 您的原始源标识符.

(原始内容存档于2018-10-21) (原始内容存档于2017-09-21)

报告特性出错

属性

自定义属性是可以添加到您错误报告中的密钥值对. 它们被用于报告汇总, 对错误进行排序和过滤,可以提供更好的背景数据,而且可以提供更多的数据。 它们是许多 高级回溯跟踪特性,详见 报告文档。默认属性 作为应用程序名称和版本,自动基于您的软件包.json信息。 如果回溯跟踪不能 找到它们,您需要通过用户属性手动提供它们 .

有几个地方可以添加,修改或删除属性.

将属性对象附加到 BacktraceClient

可以在 回溯跟踪 初始化。 本列表 属性将包含在每个错误报告,称为全局属性.

// Create an attributes object that can be modified throughout runtime
const attributes: Record<string, unknown> = {
    release: 'PROD',
};

// BacktraceClientOptions
const options: BacktraceConfiguration = {
    url: 'https://submit.backtrace.io/<universe>/<token>/json',

    // Attach the attributes object
    userAttributes: attributes,
};

// Initialize the client
const client = BacktraceClient.initialize(options);

您还可以包括创建报告时要解决的属性 :

// BacktraceClientOptions
const options: BacktraceConfiguration = {
    url: 'https://submit.backtrace.io/<universe>/<token>/json',

    // Attach the attributes object
    userAttributes: () => ({
        attribute: getAttributeValue(),
    }),
};

// Initialize the client
const client = BacktraceClient.initialize(options);

应用程序运行时添加属性

一旦装入了特定数据(例如用户已经登录),就可以在运行期间设置全局属性.

const client = BacktraceClient.initialize(options);
...

client.addAttribute({
    "clientID": "de6faf4d-d5b5-486c-9789-318f58a14476"
})

您也可以添加创建报表时要解决的属性 :

const client = BacktraceClient.initialize(options);
...

client.addAttribute(() => ({
    "clientID": resolveCurrentClientId()
}))

添加属性到错误报告

BacktraceReport 对象的属性列表可以被直接修改.

const report: BacktraceReport = new BacktraceReport('My error message', { myReportKey: 'myValue' });
report.attributes['myReportKey'] = 'New value';

文件附件

文件可以附在错误报告上. 当将回溯跟踪连接起来, 更新 回溯跟踪 或 动态的特定报告 。 当在 BacktraceClient 中包含附件时, 所有文件都将是 与每份报告一起上传.

// Import attachment types from @backtrace/node
import { BacktraceStringAttachment, BacktraceUint8ArrayAttachment, BacktraceFileAttachment } from "@backtrace/node";

// BacktraceStringAttachment should be used for text object like a log file, for example
const stringAttachment = new BacktraceStringAttachment("logfile.txt", "This is the start of my log")

// Buffer attachment is an attachment type dedicated to store buffer data
const bufferAttachment = new BacktraceBufferAttachment('buffer-attachment.txt', Buffer.from('sample'));

// File attachment is an attachment type dedicated for streaming files
const fileAttachment = new BacktraceFileAttachment('/path/to/sample/file');

// BacktraceClientOptions
const options = {
    url: "https://submit.backtrace.io/<universe>/<token>/json",

    // Attach the files to all reports
    attachments: [path.join('/path/to/attachment'), stringAttachment],
}

const client = BacktraceClient.initialize(options);

// Later decide to add an attachment to all reports
client.addAttachment(bufferAttachment)

// After catching an exception and generating a report
try {
    throw new Error("Caught exception!")
} catch (error) {
    const report = const report = new BacktraceReport(error, {}, [fileAttachment])
    client.send(report);
}

面包屑

Breadcrumbs是时间顺序数据追踪运行时间事件的片段. 这个SDK默认记录了一些事件, 也可以加入手动面包屑.

(面包屑特性文档)

面包屑配置

import { BacktraceClient, BacktraceConfiguration } from '@backtrace/node';

// BacktraceClientOptions
const options: BacktraceConfiguration = {
    // ignoring all but breadcrumbs config for simplicity
    breadcrumbs: {
        // breadcrumbs configuration
    },
};

// Initialize the client
const client = BacktraceClient.initialize(options);

默认面包屑

拦截面包屑

如果PII或其他信息需要从面包屑中过滤,您可以使用截取功能来跳过或过滤 清除敏感信息。 任何RawBreadcrumb返回的会用于面包crumb. 如果返回未定义,则无 将添加面包屑.

手动面包屑

除了所有自动收集的默认面包屑外,您还可以手动添加面包屑: 属于你自己的.

client.breadcrumbs?.info('This is a manual breadcrumb.', {
    customAttr: 'wow!',
});

应用稳定性计量

Backtrace节点SDK具有发送使用量表的能力,可以在Backtrace UI中查看.

(标准计量特征文件)

计量配置

计量使用量

// metrics will be undefined if not enabled
client.metrics?.send();

离线数据库支持

Backtrace节点SDK可以在发送到Backtrace之前缓存生成的报告并崩溃到本地磁盘. 这是 建议;在某些配置中,节点应用程序可在SDK完成提交数据之前崩溃,并在 网络条件缓慢 您的应用程序可能会在关闭窗口中等待 HTTP 提交完成 。 在这样的情况下 下一次应用程序启动时会发送事件缓存报告.

通过离线数据库支持,您可以:

• 在用户没有互联网连接或服务无法提供时缓存您的报告,
• 捕捉坠机,
• 手动决定是否发送报告,以及何时发送.

离线数据库支持默认已禁用 。 要启用它, 请添加“ enable: true ” 和目录的路径 回溯跟踪可以存储崩溃数据.

const client = BacktraceClient.initialize({
    // ignoring all but database config for simplicity
    database: {
        enable: true,
        path: '/path/to/the/database/directory',
        captureNativeCrashes: true,
    },
});

// manually send and keep the data on connection issue
client.database.send();
// manually send and remove all data no matter if received success or not.
client.database.flush();

数据库配置

本地崩溃支持

Backtrace节点SDK可以捕捉由Assert/OOM相撞等节点应用程序所生成的本土相撞. 顺序 为了收集它们,SDK使用节点 process.report API (英语). 设置本地崩溃支持后, 您 process.report 设置可能被覆盖, 您的崩溃数据可能在数据库目录中创建 .

下次会议发送的数据库记录可能没有关于崩溃会话的一些信息,例如属性或 面包屑. 为了缩小数据库记录的大小,附件支持仅限于文件附件.

手工数据库操作

BacktraceDatabase对象的客户端选项中可提供数据库支持. 你可以用手动的 操作数据库记录.

高级 SDK 特性

回溯跟踪

后追Client是SDK的主要类. 当这个单通对象被即时化时, 开始监测错误, 它会 撰写和发送报告,说明未处理的错误和未处理的承诺拒绝。 也可以用来手动发送 例外和拒绝处理者的报告。 不创建此对象的一个以上实例 .

回溯跟踪选择

BacktraceClient 初始化后通过的选项如下 .

手动发送错误

将错误发送到 Backtrace 有几种方法 。 关于定义的更详细情况 client.send() 见 方法 见下文.

// send as a string
await client.send('This is a string!');

// send as an Error
await client.send(new Error('This is an Error!'));

// as a BacktraceReport (string)
await client.send(new BacktraceReport('This is a report with a string!'));

// as a BacktraceReport (Error)
await client.send(new BacktraceReport(new Error('This is a report with a string!')));

修改/skip 错误报告

当管理环境中出现例外,您可以附加一个处理器时,会触发发送前的事件. 您可以使用“ 发送前” 事件来擦除 PII, 或者根据您的应用程序的数据扩展属性或 JSON 对象数据 在例外时有。 报告可以通过返回一个无效值被完全跳过 .

const client = BacktraceClient.initialize({
    url: SUBMISSION_URL,
    beforeSend: (data: BacktraceData) => {
        // skip the report by returning a null from the callback
        if (!shouldSendReportToBacktrace(data)) {
            return undefined;
        }
        // apply custom attribute
        data.attributes['new-attribute"] = 'apply-data-in-callback';
        return data;
    },
});

SDK 方法覆盖

BacktraceClient. buildinger 用于推翻默认的 BacktraceClient 方法. 文件与 http 操作覆盖 例如,可用于在休息或运动中执行数据自定义加密.

不使用这些操作来修改数据对象。 见 修改/skip 错误报告 页:1 用于修改报告然后将其发送到 Backtrace 的正确方法.

const client = BacktraceClient.builder(options)
    .useRequestHandler(requestHandler)
    .useBreadcrumbSubscriber(breadcrumbSubscriber)
    .addAttributeProvider(attributeProvider)
    .build();