回溯电源SDK

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

这个 @ 回溯跟踪/ 电子 SDK将您的JavaScript应用程序连接到 Backtrace. 基本一体化是快速的 简单,在此之后可以探索丰富的回溯追踪特征集.

目录

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

基本融合

安装软件包

$ npm install @backtrace/electron

将SDK纳入主要进程

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

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

// 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!'));

将 SDK 纳入渲染器进程

您可以在渲染器过程中使用基于 Backtrace SDK 的任何浏览器, 例如 @backtrace/browser 或者说 @backtrace/react. 确保将其安装到一边 @backtrace/electron数字 :

$ npm install @backtrace/browser

要在 Electron IPC 支持下将回溯跟踪添加到渲染器进程,您需要使用一个 预装入脚本 在你身边 BrowserWindow。 一旦你 含有一个,请在其中添加此导入:

import '@backtrace/electron/main/preload';

这将确保Backtrace使用的IPC API被正确装入.

之后,可以在渲染器过程中初始化回溯跟踪. 有两样东西和普通的SDK不同 初始化 :

1. 未使用 URL - 您可以把它留作空字符串,
2. 需要用吗 addBacktraceElectron 和建筑师.

例如,如果您正在使用 initialize 函数 :

const client = BacktraceClient.initialize(
    {
        url: '',
        name: 'My Renderer App',
        version: '0.0.1',
    },
    (builder) => addBacktraceElectron(builder),
);

或者,如果你在使用 build 函数 :

const builder = BacktraceClient.builder({
    url: '',
    name: 'My Renderer App',
    version: '0.0.1',
});

addBacktraceElectron(builder);

const client = builder.build();

提交过程

渲染器客户端不提交任何错误. 所有发送到回溯追踪的都通过 IPC 传递到主 进程,处理提交.

这包括:

• 错误报告,
• 错误报告附件,
• 面包屑,
• 度量衡.

主要过程的会话ID用于渲染器报告.

当在渲染器过程中发生出错时,来自主和渲染器过程的附件会包含在报表中. 如果可能,附件将流出(Blob, (中文(简体) ), ReadableStream),否则通过序列化复制到JSON. 然而,渲染器附件不包含在主过程崩溃中. 这是因为有可能 多个渲染器过程,但未来可能会有变化.

同步初始化

在向渲染器SDK上添加Electron时,数据会与主要过程进行交换,以确保使用相同的会话ID. 默认情况下,将尽快同步完成这项工作。 不过,如果发生起动撞车事件,这可能是不够的 就在SDK初始化之后,因为数据可能尚未交换.

在这种情况下,你可以使用 synchronize 选项在 addBacktraceBuilder。请注意,如果你不能确保 SDK 在主过程中,您拨打时初始化 addBacktraceBuilder, (中文(简体) ), 您的申请可以与白色挂起 屏幕。这是因为IPC的同步性质,即阻断了渲染器过程直至它收到一个 反应.

要启用同步初始化 :

const client = BacktraceClient.initialize(
    {
        url: '',
        name: 'My Renderer App',
        version: '0.0.1',
    },
    (builder) => addBacktraceElectron(builder, { synchronous: true }),
);

上传源代码图

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

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

报告特性出错

这里的所有特征都以主要过程来描述. 如果您想了解浏览器中的错误报告, 请查看 您的后跟踪浏览器 SDK 读取我.

属性

自定义属性是可以添加到您错误报告中的密钥值对. 它们被用于报告汇总, 对错误进行排序和过滤,可以提供更好的背景数据,而且可以提供更多的数据。 它们是许多 高级回溯跟踪特性,详见 报告文档。默认属性 由于应用程序名称和版本自动从Electron app信息中填入.

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

将属性对象附加到 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/electron
import { BacktraceStringAttachment, BacktraceFileAttachment, BacktraceBufferAttachment } from "@backtrace/electron";

// 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/electron';

// 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 Electron SDK具有发送使用量表的能力,可以在Backtrace UI中取景.

(标准计量特征文件)

计量配置

计量使用量

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

离线数据库支持

Backtrace Electron SDK可以在发送到Backtrace之前将生成的报告缓存到本地磁盘. 这是 建议; 在某些配置中, Electron 应用程序可以在 SDK 完成提交数据之前崩溃,以及 在缓慢的互联网条件下, 您的应用程序可能会在关闭窗口中等待 HTTP 提交完成 。 单位 这个案子,缓存报告将在下一次应用启动时发送.

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

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

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

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();

数据库配置

本地崩溃支持

后追踪Electron SDK可以捕捉由Electron应用程序所生成的本土相撞. 为了收集它们,SDK 使用电源 crashReporter。 。 。 .

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

手工数据库操作

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();