Sentry(v20.12.1) K8S 云原生架构探索，SENTRY FOR 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 方法会清空事件队列。