Sentry(v20.12.1) K8S 云原生架构探索，SENTRY FOR JAVASCRIPT SDK 配置详解（二）

Default Integrations

所有 Sentry 的 SDK 都提供了集成（integrations），扩展了 SDK 的功能。

默认情况下，系统集成（System integrations）是启用的，以集成到标准库或解释器本身中。它们已记录在案，因此您既可以知道它们在做什么，也可以在它们引起问题时禁用它们。

Enabled by Default

InboundFilters

Import name: Sentry.Integrations.InboundFilters

通过这种集成，您可以根据给定异常中的类型，消息或 URL 忽略特定错误。

默认情况下，它忽略以 Script error 或 Javascript error: Script error 开头的错误。

要配置这个集成，直接使用 ignoreErrors，denyUrls，和 allowUrls SDK 选项。请记住，denyURL 和 allowURL 只对捕获的异常有效，而不是原始消息事件。

FunctionToString

Import name: Sentry.Integrations.FunctionToString

这种集成使 SDK 可以提供原始的函数和方法名称，即使我们的错误或面包屑处理程序包装了它们也是如此。

TryCatch

Import name: Sentry.Integrations.TryCatch

这个集成封装了原生 time 和 events APIs (setTimeout, setInterval, requestAnimationFrame, addEventListener/removeEventListener) 在 try/catch 块处理 async 异常。

Breadcrumbs

Import name: Sentry.Integrations.Breadcrumbs

这种集成封装了原生 API 以捕获面包屑。默认情况下，Sentry SDK 封装了所有 API。

Available options:

{ beacon: boolean; // Log HTTP requests done with the Beacon API
  console: boolean; // Log calls to `console.log`, `console.debug`, etc
  dom: boolean; // Log all click and keypress events
  fetch: boolean; // Log HTTP requests done with the Fetch API
  history: boolean; // Log calls to `history.pushState` and friends
  sentry: boolean; // Log whenever we send an event to the server
  xhr: boolean; // Log HTTP requests done with the XHR API
}

GlobalHandlers

Import name: Sentry.Integrations.GlobalHandlers

这个集成附加了全局处理程序来捕获未捕获的 exceptions 和未处理的 rejections。

可用的选项：

{
  onerror: boolean;
  onunhandledrejection: boolean;
}

LinkedErrors

Import name: Sentry.Integrations.LinkedErrors

此集成允许您配置链接错误。它们将被递归地读取到指定的限制，并由特定的 key 执行查找。默认情况下，Sentry SDK 将限制设置为 5，使用的键 key 是 cause。

可用的选项：

{
  key: string;
  limit: number;
}

UserAgent

Import name: Sentry.Integrations.UserAgent

这种集成将 user-agent 信息附加到事件中，这使我们能够正确地分类并使用特定的操作系统(OS)，浏览器(browser)和版本(version)信息对其进行标记。

Modifying System Integrations

要禁用系统集成，在调用 init() 时设置 defaultIntegrations: false。

要覆盖它们的设置，请提供一个带有配置到 integrations 选项的新实例。例如，关闭浏览器捕获的控制台调用：integrations: [new Sentry.Integrations.Breadcrumbs({ console: false })]。

Removing an Integration

这个例子移除了为事件添加面包屑的默认启用的集成：

Sentry.init({
  // ...
  integrations: function(integrations) {
    // integrations will be all default integrations
    return integrations.filter(function(integration) {
      return integration.name !== "Breadcrumbs";
    });
  },
});

Pluggable Integrations

这些可插拔的集成是为特定的应用程序和/或框架增加功能的代码片段。我们对它们进行了记录，这样您就可以看到它们的功能，并且可以启用它们。

How to Enable

安装 @sentry/integrations 包，并提供一个带有你配置到 integrations 选项的新实例。加载 SDK 之后，包括插件。

示例：

import * as Sentry from "@sentry/browser";
import { ReportingObserver as ReportingObserverIntegration } from "@sentry/integrations";
Sentry.init({
  dsn: "___PUBLIC_DSN___",
  integrations: [new ReportingObserverIntegration()],
});

ExtraErrorData

Import name: Sentry.Integrations.ExtraErrorData

这个集成从错误对象中提取所有非原生(non-native)属性，并将它们作为 extra 数据附加到事件中。

可用的选项：

{
  // limit of how deep the object serializer should go. Anything deeper than limit will
  // be replaced with standard Node.js REPL notation of [Object], [Array], [Function] or
  // a primitive value. Defaults to 3.
  depth: number;
}

CaptureConsole

Import name: Sentry.Integrations.CaptureConsole

这种集成捕获所有的 Console API 调用，并使用 captureMessage 调用将它们重定向到 Sentry。然后，它会重新触发以保留默认的原生行为。

{
  // array of methods that should be captured
  // defaults to ['log', 'info', 'warn', 'error', 'debug', 'assert']
  levels: string[];
}

Dedupe

Import name: Sentry.Integrations.Dedupe

这种集成可以对某些事件进行重复数据删除。如果您收到许多重复的错误，可能会有所帮助。请注意，Sentry 将仅比较堆栈跟踪和指纹。

Debug

Import name: Sentry.Integrations.Debug

通过这种集成，您可以检查已处理事件的内容，该事件将被传递到 beforeSend 并有效地发送到 Sentry SDK。无论何时注册，它都将始终作为最后的集成运行。

可用的选项：

{
  // trigger DevTools debugger instead of using console.log
  debugger: boolean;
  // stringify event before passing it to console.log
  stringify: boolean;
}

RewriteFrames

Import name: Sentry.Integrations.RewriteFrames

这种集成允许您对堆栈跟踪的每一帧应用转换。在 streamlined 场景中，可以使用它来更改文件框架的名称，或者向它提供一个迭代函数来应用任何任意的转换。

在 Windows 机器上，你必须使用 Unix 路径并跳过 root 选项中的卷(volume)号来启用。例如，C:\\Program Files\\Apache\\www 不能工作，但是，/Program Files/Apache/www 可以。

可用的选项：

{
  // root path that will be appended to the basename of the current frame's url
  root: string;
  // function that takes the frame, applies a transformation, and returns it
  iteratee: (frame) => frame;
}

ReportingObserver

Import name: Sentry.Integrations.ReportingObserver

此集成与 ReportingObserver API 挂钩，并将捕获的事件发送到 Sentry。可以将其配置为仅处理特定的问题类型。

可用的选项：

{
  types: <'crash'|'deprecation'|'intervention'>[];
}

Custom Integrations

使用以下格式在 JavaScript 中添加一个自定义集成：

// All integration that come with an SDK can be found on Sentry.Integrations object
// Custom integration must conform Integration interface: https://github.com/getsentry/sentry-javascript/blob/master/packages/types/src/integration.ts
Sentry.init({
  // ...
  integrations: [new MyAwesomeIntegration()],
});

rrweb: Session Replays

Sentry 提供了与 rrweb 的 proof-of-concept（概念验证） 集成，该工具包用于记录和重放用户会话。在功能丰富的单页应用程序中诊断复杂的用户行为时，这可能非常有用。

有关可用 hints 的信息，请参阅 hints in JavaScript

回放使用 Attachments.

Configuration

首先，您需要添加 @sentry/rrweb 和 rrweb 软件包：

npm install --save @sentry/rrweb rrweb

接下来，使用 Sentry SDK 注册集成。这将根据您使用的框架而有所不同：

import * as Sentry from "@sentry/browser";
import SentryRRWeb from "@sentry/rrweb";
Sentry.init({
  dsn: "___PUBLIC_DSN___",
  integrations: [
    new SentryRRWeb({
      // ...options
    }),
  ],
  // ...
});

有关配置的更多信息，请参阅 @sentry/rrweb project on GitHub。

捕获到事件的重播后，您会发现该事件在事件的 “Replay” 部分下的“问题详细信息”中可见。

Sampling

为了满足组织的需求，您可能希望对 replay 进行采样。最简单的方法是在初始化 Sentry SDK 时做出抽样决定。例如，以下是 Sentry 本身如何使用采样来仅捕获员工的样本的方法：

const hasReplays = getCurrentUser().isStaff;
let integrations = [];
if (hasReplays) {
  console.log("[sentry] Instrumenting session with rrweb");
  integrations.push(new SentryRRWeb());
}
Sentry.init({
  dsn: "___PUBLIC_DSN___",
  integrations,
});
Sentry.setTag("rrweb.active", hasReplays ? "yes" : "no");

您会注意到我们还设置了 rrweb.active 标记，该标记可帮助我们识别附加了 replay 的事件，因为否则我们将无法找到它们。配置完成后，您将可以在搜索查询中简单地使用 rrweb.active:yes。

Sentry Testkit

在为应用程序构建测试时，您希望断言正确的 flow-tracking 或错误正在发送到 Sentry，而不是真正地将其发送到 Sentry 服务器。这样，您就不会在测试运行或其他 CI 操作期间用错误报告淹没 Sentry。

Note: Wix, 一个 Sentry 合作伙伴, 负责维护Sentry Testkit。

Sentry Testkit 是一个 Sentry 插件，允许拦截 Sentry 的报告，并进一步检查正在发送的数据。它允许 Sentry 在您的应用程序中原生工作，并且通过覆盖缺省 Sentry 的传输机制，报告并不真正发送，而是在本地记录到内存中。通过这种方式，可以在以后获取记录的报告，用于您自己的使用、验证，或者您在本地开发/测试环境中的任何其他用途。

Installation

npm install sentry-testkit --save-dev

Using in tests

const sentryTestkit = require("sentry-testkit");
const { testkit, sentryTransport } = sentryTestkit();
// initialize your Sentry instance with sentryTransport
Sentry.init({
  dsn: "___PUBLIC_DSN___",
  transport: sentryTransport,
  //... other configurations
});
// then run any scenario that should call Sentry.catchException(...)
expect(testkit.reports()).toHaveLength(1);
const report = testkit.reports()[0];
expect(report).toHaveProperty(/*...*/);

您也可以在 sentry-testkit 仓库中的 testing section 中看到更多用法示例。

Testkit API

Sentry Testkit 由一个非常简单和直接的 API 组成。在 Sentry Testkit Docs 中可以看到完整的 API 描述和文档。