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

系列

1. Sentry-Go SDK 中文实践指南
2. 一起来刷 Sentry For Go 官方文档之 Enriching Events
3. Snuba：Sentry 新的搜索基础设施(基于 ClickHouse 之上)
4. Sentry 10 K8S 云原生架构探索，Vue App 1 分钟快速接入
5. Sentry(v20.12.1) K8S云原生架构探索,玩转前/后端监控与事件日志大数据分析,高性能高可用+可扩展可伸缩集群部署
6. Sentry(v20.12.1) K8S 云原生架构探索，Sentry JavaScript SDK 三种安装加载方式

Basic Options

SDK 可以使用多种选项进行配置。这些选项在 SDK 中基本上是标准化的，但在更好地适应平台特性方面存在一些差异。选项是在 SDK 首次初始化时设置的。

选项作为对象传递给 init() 函数：

Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  maxBreadcrumbs: 50,
  debug: true,
});

Common Options

跨 SDK 的常见选项列表。这些功能在所有 SDK 中或多或少都是一样的，但是为了更好地支持平台，会存在一些细微的差异。可以从环境变量或你的 ~/.sentryclirc 文件中自动的读取的选项(SENTRY_DSN, SENTRY_ENVIRONMENT, SENTRY_RELEASE)。有关更多信息，请参见Working with Projects。

dsn

DSN 告诉 SDK 将事件发送到哪里。如果没有提供这个值，SDK 将尝试从 SENTRY_DSN 环境变量中读取它。如果这个变量也不存在，SDK 就不会发送任何事件。

在没有进程环境（如浏览器）的运行时中，fallback 不会应用。

debug

打开或关闭调试模式。如果启用了调试，如果发送事件时出现问题，SDK 将尝试打印出有用的调试信息。默认值总是 false。一般不建议在生产环境中打开它，尽管打开 debug 模式不会引起任何安全问题。

release

设置 release（发行版）。某些 SDK 会尝试自动配置 release，但是最好手动设置 release，以确保该 release 与您的 deploy integrations 或 source map uploads 同步。版本名称是字符串，但是 Sentry 会检测到某些格式，并且它们的呈现方式可能有所不同。在 releases 文档中了解有关如何发送 release 数据的更多信息，以便 Sentry 可以告诉您 release 之间的回归并确定潜在的来源。

默认情况下，SDK 会尝试从环境变量 SENTRY_RELEASE 中读取该值（在浏览器 SDK 中，将从 window.SENTRY_RELEASE 中读取该值，如果可用）。

environment

设置环境。此字符串为自由形式，默认情况下不设置。一个 release 可以与多个环境相关联，以便在 UI 中将它们分开（可以考虑staging 与 prod 或类似的方式）。

默认情况下，SDK 将尝试从 SENTRY_ENVIRONMENT 环境变量中读取该值（浏览器 SDK 除外）。

sampleRate

配置错误事件的采样率，范围为 0.0 到 1.0。默认值为 1.0，表示发送了 100％ 的错误事件。如果设置为 0.1，则仅发送 10％ 的错误事件。事件是随机选择的。

maxBreadcrumbs

这个变量控制应该捕获的面包屑( breadcrumbs )总数。默认值为 100。

attachStacktrace

当启用时，堆栈跟踪将自动附加到所有记录的消息。堆栈跟踪总是附加到异常；然而，当设置此选项时，堆栈跟踪也会与消息一起发送。例如，该选项意味着堆栈跟踪显示在所有日志消息的旁边。

该选项默认为 off。

对于有堆栈跟踪和没有堆栈跟踪的事件，Sentry中的分组是不同的。结果，在为某些事件启用或禁用此 flag 时，您将获得新的组。

sendDefaultPii

如果启用此 flag，则某些个人识别信息（PII）将由 active integrations 添加。默认情况下，不发送此类数据。如果可能的话，我们建议默认情况下启用此功能以发送所有此类数据，并使用管理 敏感数据 的功能手动删除您不想发送的内容。

denyUrls

与不应该发送到 Sentry 的错误 URL 相匹配的字符串或正则表达式模式列表。默认情况下，将发送所有错误。这是一个 “contains(包含)” 匹配整个文件 URL。因此，如果你添加 foo.com，它也会匹配 https://bar.com/myfile/foo.com。默认情况下，将发送所有错误。

allowUrls

匹配错误 URL 的字符串列表或正则表达式模式的遗留别名，这些错误 URL 应该专门发送给 Sentry。默认情况下，将发送所有错误。这是一个 “contains(包含)” 匹配整个文件 URL。因此，如果您将 foo.com 添加到它，它也将匹配 https://bar.com/myfile/foo.com。默认情况下，所有错误将被发送。

autoSessionTracking

当设置为 true 时，SDK 将发送 session 事件给 Sentry。所有浏览器 SDK 都支持这一点，每个页面加载都向 Sentry 发送一个 session。

normalizeDepth

Sentry SDK 将任何上下文数据标准化到给定深度。任何包含比其更深的结构的数据的 key 都将被修剪并使用其类型（[Object] 或 [Array]）进行标记，而无需进一步进行操作。默认情况下，walking 的深度为 3 级。

Integration Configuration

对于许多平台，SDK 集成可以与之一起配置。在一些平台上，这是 init() 调用的一部分，而在另一些平台上，则应用不同的模式。

integrations

在一些 SDK 中，在库初始化时通过这个参数配置集成。要了解更多信息，请参阅我们的文档了解特定的集成。

defaultIntegrations

这可以用来禁用默认添加的集成。当设置为 false 时，不会添加默认的集成。

Hooks

这些选项可用于以各种方式 hook SDK，以定制事件的报告。

beforeSend

使用 SDK-specific 事件对象调用此函数，可以返回修改后的事件对象或不返回任何内容，以跳过报告事件。例如，这可以用于在发送前手动剥离 PII。

beforeBreadcrumb

在将面包屑(breadcrumb)添加到作用域(scope)之前，使用 SDK 特定的面包屑(SDK-specific breadcrumb)对象调用此函数。当该函数未返回任何内容时，将删除 breadcrumb。要传递 breadcrumb，请返回第一个参数，其中包含 breadcrumb 对象。回调通常会获得第二个参数（称为“hint”），该参数包含创建 breadcrumb 的原始对象，以进一步自定义面包屑的外观。

Transport Options

Transports 被用来发送事件到 Sentry。可以在某种程度上对传输进行定制，以更好地支持高度特定的部署。

transport

切换出用于发送事件的 transport。如何运作取决于 SDK。例如，它可以用于捕获事件以进行单元测试，或通过需要代理身份验证的更复杂的设置发送事件。

Tracing Options

tracesSampleRate

0 到 1 之间的数字，控制给定事务发送到哨兵的概率百分比。(0表示0%，1表示100%)同样适用于应用程序中创建的所有事务。必须定义这个或 tracesSampler 以启用跟踪。

tracesSampler

一个函数负责确定一个给定的事务将被发送到 Sentry 的概率百分比。它将自动被传递有关事务和创建它的上下文的信息，并且必须返回一个介于 0(被发送的概率为0%)和 1(被发送的概率为100%) 之间的数字。还可以用于过滤事务，对不需要的事务返回0。必须定义这个或 tracesSampleRate 来启用跟踪。

Releases & Health

一个 release 是部署到环境中的代码版本。当您向 Sentry 提供有关 release 的信息时，您可以：

• 确定新版本中引入的问题和回归
• 预测哪个提交引起了问题，谁可能负责
• 通过在提交消息中包含问题编号来解决问题
• 在部署代码时接收电子邮件通知

此外，releases 还用于将 source maps 应用到压缩的 JavaScript 中，以查看原始的、未转换的源代码。

Bind the Version

在配置客户端 SDK 时包含一个 release ID(通常称为 “version” )。这个 ID 通常是一个 git SHA 或自定义版本号。

release 名称不能：

• 包含换行符或空格
• 使用正斜杠(/)，反斜杠(\)，句点(.)，或双句点(..)
• 超过 200 个字符

每个组织的发布是全局的；在它们前面加上一些特定于项目(project-specific)的东西，以方便区分。

Sentry.init({
  release: "my-project-name@2.3.12",
});

在 Node/npm 环境中使用 JavaScript 进行此操作的常见方法是使用process.env.npm_package_version，如下所示：

Sentry.init({
  release: "my-project-name@" + process.env.npm_package_version,
});

如何使版本对代码可用由您决定。例如，您可以使用在构建过程中设置的环境变量。

这会用 release 值标记每个事件。我们建议您在部署新版本之前先告诉 Sentry，因为这将释放一些新功能，如关于 releases 的文档中所述。但是，如果您不这样做，Sentry 会在第一次看到具有该 release ID 的事件时自动在系统中创建一个 release 实体。

配置完 SDK 后，您可以安装 repository integration（存储库集成）或手动为 Sentry 提供自己的提交元数据。阅读有关设置发行版的文档，以获取有关集成，关联提交以及在部署发行版时告知 Sentry 的更多信息。

Release Health

通过观察用户采用率，应用程序使用率，crashes 百分比和 session data 来监视 health of releases。Release health 将提供与用户体验相关的崩溃和错误影响的见解，并通过 release 详细信息，图表和过滤器揭示每个新问题的趋势。

初始化 SDK 后，SDK 将自动管理会话的开始和结束。

Sentry.init({
  autoSessionTracking: true
});

Environments

Sentry 收到带有 environment 标签的事件时，会自动创建环境。环境区分大小写。环境名称不能包含换行符，空格或正斜杠，字符串 “None” 或超过 64 个字符。您不能删除环境，但是可以隐藏它们。

Sentry.init({
  environment: "production",
});

Environments 可帮助您在 sentry.io 的“问题详细信息”页面中更好地过滤 issues，releases 和 user feedback，您可以在 documentation that covers using environments 中了解更多信息。

Filtering and Sampling Events

将 Sentry 添加到你的应用中能够为你提供大量关于错误和性能的非常有价值的信息。大量的信息是有益的——只要这些信息是正确的，数量合理。

Sentry SDK 提供了多个配置选项来帮助您控制这一点，使您既可以过滤掉不需要的事件，又可以从中获取代表性的样本。

Note: Sentry UI 还提供了使用 Inbound Filters 筛选事件的方法。 不过，我们建议您在客户端级别进行过滤，因为这样可以消除发送您实际上不需要的事件的开销。

Filtering Error Events

使用 beforeSend 回调方法并配置，启用或禁用 integrations，将您的 SDK 配置为过滤错误事件。

Using beforeSend

所有 Sentry SDK 都支持 beforeSend 回调方法。在事件发送到服务器之前立即调用 beforeSend，因此这是您可以编辑其数据的最终位置。它接收事件对象作为参数，因此您可以根据自定义逻辑和事件上可用的数据，使用它来修改事件的数据或完全删除（通过返回 null）。

Sentry.init({
  // ...

  beforeSend(event, hint) {
    const error = hint.originalException;
    if (
      error &&
      error.message &&
      error.message.match(/database unavailable/i)
    ) {
      event.fingerprint = ["database-unavailable"];
    }
    return event;
  },
});

还要注意，面包屑(breadcrumbs)可以过滤，如 our Breadcrumbs documentation 所述。

Event Hints

before-send 回调函数同时传递了 event 和第二个参数 hint，它包含一个或多个提示。

通常，hint 保存原始异常，以便提取额外数据或影响分组。在本例中，如果捕获了某种类型的异常，则强制将指纹(fingerprint)转换为普通值：

Sentry.init({
  // ...

  beforeSend(event, hint) {
    const error = hint.originalException;
    if (
      error &&
      error.message &&
      error.message.match(/database unavailable/i)
    ) {
      event.fingerprint = ["database-unavailable"];
    }
    return event;
  },
});

当 SDK 为传输创建一个事件或面包屑(breadcrumb)时，该传输通常是从某种源对象创建的。例如，错误事件通常是从日志记录或异常实例创建的。为了更好地定制，SDK 将这些对象发送给特定的回调( beforeSend、beforeBreadcrumb 或 SDK 中的事件处理器系统)。

Using Hints

1. beforeSend / beforeBreadcrumb
2. eventProcessors

Event 和 breadcrumb 的 hints 是包含用于将事件或面包屑组合在一起的各种信息的对象。通常，hints 保留原始异常，以便可以提取其他数据或影响分组。

对于事件，例如 event_id，originalException，syntheticException（在内部用于生成更清晰的堆栈跟踪），以及您附加的任何其他任意的 data。

对于面包屑，hints 的使用取决于实现。对于 XHR 请求，hint 包含 xhr 对象本身。对于用户交互，hint 包含 DOM 元素和事件名称等。

在此示例中，如果捕获到某种类型的异常，则将指纹(fingerprint)强制为一个公共值：

Sentry.init({
  // ...

  beforeSend(event, hint) {
    const error = hint.originalException;
    if (
      error &&
      error.message &&
      error.message.match(/database unavailable/i)
    ) {
      event.fingerprint = ["database-unavailable"];
    }
    return event;
  },
});

Hints for Events

originalException

• 导致 Sentry SDK 创建事件的原始异常。这对于更改 Sentry SDK 对事件进行分组或提取额外信息的方式非常有用。

syntheticException

• 当引发字符串或非错误(non-error)对象时，Sentry 将创建综合异常，以便您可以获得基本的堆栈跟踪。此异常存储在此处以进一步提取数据。

Hints for Breadcrumbs

event

• 对于通过浏览器事件创建的面包屑，Sentry SDK 通常将事件作为 hint 提供给面包屑。 例如，这可用于将目标 DOM 元素中的数据提取到面包屑中。

level / input

• 对于从控制台日志截取创建的面包屑。这将保留原始控制台日志级别和日志功能的原始输入数据。

response / input

• 用于从 HTTP 请求创建的面包屑。这保存了响应对象（来自 fetch API）和 fetch 函数的输入参数。

request / response / event

• 用于从 HTTP 请求创建的面包屑。它保存了请求和响应对象（来自节点 HTTP API）以及节点事件（response 或 error）。

xhr

• 对于通过旧版 XMLHttpRequest API 通过 HTTP 请求创建的面包屑。这将保留原始的 xhr 对象。

Decluttering Sentry

您可以构造允许的域列表，这可能会引发可接受的异常。例如，如果您的脚本是从 cdn.example.com 加载的，而您的站点是 example.com，则可以将 allowUrls 设置为：

如果您想永远阻止特定的 URL，也可以使用 denyUrls。

在 5.17.0 版之前，allowUrls 和 denyUrls 分别称为 whitelistUrls 和 blacklistUrls。出于向后兼容的原因，仍支持这些选项，但是在 6.0 版中将删除它们。有关更多信息，请参见我们的 Inclusive Language Policy。

此外，我们的社区已为日常工作（例如 Facebook，Chrome 扩展程序等）编制了常见的忽略规则列表。建议您检查一下这些内容，看看它们是否适用于您，这很有用。Here is the original gist。这不是我们 SDK 的默认值；这只是一个广泛示例的亮点。

Sentry.init({
  ignoreErrors: [
    // Random plugins/extensions
    "top.GLOBALS",
    // See: http://blog.errorception.com/2012/03/tale-of-unfindable-js-error.html
    "originalCreateNotification",
    "canvas.contentDocument",
    "MyApp_RemoveAllHighlights",
    "http://tt.epicplay.com",
    "Can't find variable: ZiteReader",
    "jigsaw is not defined",
    "ComboSearch is not defined",
    "http://loading.retry.widdit.com/",
    "atomicFindClose",
    // Facebook borked
    "fb_xd_fragment",
    // ISP "optimizing" proxy - `Cache-Control: no-transform` seems to
    // reduce this. (thanks @acdha)
    // See http://stackoverflow.com/questions/4113268
    "bmi_SafeAddOnload",
    "EBCallBackMessageReceived",
    // See http://toolbar.conduit.com/Developer/HtmlAndGadget/Methods/JSInjection.aspx
    "conduitPage",
  ],
  denyUrls: [
    // Facebook flakiness
    /graph\.facebook\.com/i,
    // Facebook blocked
    /connect\.facebook\.net\/en_US\/all\.js/i,
    // Woopra flakiness
    /eatdifferent\.com\.woopra-ns\.com/i,
    /static\.woopra\.com\/js\/woopra\.js/i,
    // Chrome extensions
    /extensions\//i,
    /^chrome:\/\//i,
    // Other plugins
    /127\.0\.0\.1:4001\/isrunning/i, // Cacaoweb
    /webappstoolbarba\.texthelp\.com\//i,
    /metrics\.itunes\.apple\.com\.edgesuite\.net\//i,
  ],
});

Sampling Error Events

要将错误的代表性样本发送到 Sentry，请在 SDK 配置中将 sampleRate 选项设置为介于 0（已发送错误的0％）和 1（已发送错误的100％）之间的数字。这是一个静态比率，将同样适用于所有错误。例如，要抽样25％的错误：

Sentry.init({ sampleRate: 0.25 });

Note: 误差采样率不是动态的。更改它需要重新部署。此外，设置 SDK 采样率会限制事件源的可见性。为项目设置速率限制（仅在高 volume 时才丢弃事件）可能更适合您的需求。

Filtering Transaction Events

为了防止某些事务被报告给 Sentry，可以使用 tracesSampler 配置选项，该选项允许您提供一个函数来评估当前事务，并在它不是您想要的事务时删除它。(它还允许您以不同的速率对不同的事务进行采样。)

Note: tracesSampler 和 tracesSampleRate 配置选项是互斥的。如果您定义了一个 tracesSampler 来过滤掉某些事务，那么您还必须通过返回您希望它们被采样的速率来处理未过滤的事务。

最简单的形式（仅用于过滤）如下所示：

Sentry.init({
  // ...

  tracesSampler: samplingContext => {
    if ("...") {
      // Drop this transaction, by setting its sample rate to 0%
      return 0;
    } else {
      // Default sample rate for all others (replaces tracesSampleRate)
      return 0.1;
    }
  };
});

要了解有关 tracesSampler 选项的更多信息，请参阅 SDK 的 performance docs。

Sampling Transaction Events

对于 Sentry 的性能监控，我们建议抽样您的数据，有两个原因。首先，尽管捕获单个跟踪涉及的开销最小，但捕获每个页面加载或每个 API 请求的跟踪都有可能向系统添加不希望的负载。其次，启用抽样允许您更好地管理发送到 Sentry 的事件数量，这样您就可以根据组织的需要调整您的数量。

在选择采样率时，目标不是收集太多数据，而是收集足够的数据，以便得出有意义的结论。如果您不确定选择什么速率，那么从一个较低的值开始，随着您对流量模式和 volume 了解的更多，逐渐增加它，直到您找到了一个平衡性能和流量与数据准确性的速率。

要对事务进行取样，可以将 tracesSampleRate 配置选项设置为 0(发送的事务的 0%)到 1(发送的事务的100%)之间的一个数字，或者将 tracesSampler 选项设置为一个函数，该函数将返回这个数字，该数字随事务的不同而变化。

例如，将 tracesSampleRate 选项设置为 0.2 将导致 SDK 只发送 20% 的可能事务事件：

Sentry.init({
  // ...

  tracesSampleRate: 0.2,
});

或者，你可以提供一个 tracesSampler 函数，以不同的速率采样不同的事务:

Sentry.init({
  // ...

  tracesSampler: samplingContext => {
    // Examine provided context data (including parent decision, if any) along
    // with anything in the global namespace to compute the sample rate or
    // sampling decision for this transaction

    if ("...") {
      // These are important - take a big sample
      return 0.5;
    } else if ("...") {
      // These are less important or happen much more frequently - only take 1%
      return 0.01;
    } else if ("...") {
      // These aren't something worth tracking - drop all transactions like this
      return 0;
    } else {
      // Default sample rate
      return 0.1;
    }
  };
});

要了解更多关于 tracesSampler 选项的信息，请查看 SDK 的 performance docs。

Shutdown and Draining

大多数 SDK 的默认行为是在后台通过网络异步发送事件。这意味着如果应用程序意外关闭，某些事件可能会丢失。SDK 提供了应对这种情况的机制。

close 方法可选地接受一个以毫秒为单位的超时，并返回一个 promise，当所有未决事件刷新或超时开始时将 resolve 该 promise。

Sentry.close(2000).then(function() {
  // perform something after close
});

调用 close 后，当前客户端将不能再使用。在关闭应用程序之前只调用 close 是很重要的。

或者，在保持客户端启用状态以继续使用的同时，flush 方法会清空事件队列。

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 描述和文档。

中文文档陆续同步到：

• https://getsentry.hacker-linner.com

我是为少。
微信：uuhells123。
公众号：黑客下午茶。
谢谢点赞支持！