回溯跟踪浏览器 SDK

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

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

目录

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

基本融合

安装软件包

$ npm install @backtrace/browser

整合 SDK

在所有其他脚本之前在您的应用程序中添加以下代码来向 Backtrace 报告客户端错误 .

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

// Configure client options
const options: BacktraceConfiguration = {
    // Name of the website/application
    name: 'MyWebPage',
    // Version of the website
    version: '1.2.3',
    // 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)

报告特性出错

属性

自定义属性是可以添加到您错误报告中的密钥值对. 它们被用于报告汇总, 对错误进行排序和过滤,可以提供更好的背景数据,而且可以提供更多的数据。 它们是许多 高级回溯跟踪特性,详见 报告文档。 。 。 .

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

将属性对象附加到 BacktraceClient

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

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

// BacktraceClientOptions
const options: BacktraceConfiguration = {
    name: 'MyWebPage',
    version: '1.2.3',
    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 = {
    name: 'MyWebPage',
    version: '1.2.3',
    url: 'https://submit.backtrace.io/<universe>/<token>/json',

    // Attach the attributes object
    userAttributes: () => ({
        user: getCurrentUser(),
    }),
};

// 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/browser
import { BacktraceStringAttachment, BacktraceUint8ArrayAttachment  } from "@backtrace/browser";

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

// BacktraceUint8ArrayAttachment should be used for binary files
const attachment2 = new BacktraceUint8ArrayAttachment("connection_buffer", new Uint8Array(2));

// Setup array of files to attach
const attachments = [attachment1];

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

    // Attach the files to all reports
    attachments,
}

const client = BacktraceClient.initialize(options);

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

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

面包屑

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

(面包屑特性文档)

面包屑配置

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

// 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/session-replay 模块允许您捕捉并重放导致出错的用户交互。 这为您的错误报告提供了类似视频的上下文,从而更容易复制和调试问题.

会话重放模块的设计以隐私为最高优先. 默认情况下,它会自动遮盖所有文本和输入字段来避免捕获敏感的用户数据.

关于会话重放配置、取样和高级隐私控制的全部细节,请参见 会话重放模块文档。 。 。 .

1. 安装额外软件包

何况 @backtrace/browser,您还需要安装会话重放软件包.

$ npm install @backtrace/session-replay

2. 向客户端添加模块

要启用会话重放, 您必须使用 BacktraceClient. builder () 并添加 BacktraceClientReplay Module 。 这将取代标准的 BacktraceClient. 初始化 () .

// Import the necessary modules
import { BacktraceClient, BacktraceConfiguration } from '@backtrace/react';
import { BacktraceSessionReplayModule } from '@backtrace/session-replay';

// Configure client options
const options: BacktraceConfiguration = {
    name: 'MyWebPage',
    version: '1.2.3',
    url: 'https://submit.backtrace.io/<universe>/<token>/json',
};

// Initialize the client using the builder to add the session replay module
const client = BacktraceClient.builder(options)
    .useModule(
        new BacktraceSessionReplayModule({
            // Configuration for session replay goes here.
            maxEventCount: 100,
            privacy: {
                blockClass: 'do-not-send',
            },
            sampling: {
                input: 'last',
            }
        }),
    )
    .build();

// The client is now initialized with Session Replay enabled.
// Any errors captured by the client or the ErrorBoundary will now include a session replay.

当捕获出错时,将在调试器页面上为回溯跟踪UI中的特定出错提供会话重放的链接.

应用稳定性计量

Backtrace浏览器SDK具有发送使用量表在Backtrace UI中可查看的能力.

(标准计量特征文件)

计量配置

计量使用量

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

高级 SDK 特性

回溯跟踪

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

回溯跟踪选择

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

手动发送错误

向 Backtrace 发送错误有几种方法:

// 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,
    name: '@backtrace/browser-example',
    version: '0.0.1',
    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();