基本选项

了解如何配置 SDK。这些选项在 SDK 首次初始化时设置，并作为对象传递给 init 函数。

SDK 可以使用多种选项进行配置。这些选项在 SDK 之间大致标准化，但有一些差异以更好地适应平台的特殊性。选项在 SDK 首次初始化时设置。

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

Copied

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

SDK 之间的常见选项列表。这些选项在所有 SDK 中大致相同，但为了更好地支持平台，可能存在一些细微的差异。可以从环境变量（如 SENTRY_DSN、SENTRY_ENVIRONMENT、SENTRY_RELEASE）中读取的选项会自动读取。

`dsn`

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

在没有进程环境的运行时（如浏览器）中，这种回退不适用。

了解更多关于 DSN 利用的信息。

`debug`

打开或关闭调试模式。如果启用了调试模式，SDK 将尝试在发送事件时打印有用的调试信息。默认值始终为 false。通常不建议在生产环境中启用它，尽管启用 debug 模式不会导致任何安全问题。

`dist`

设置应用程序的分发版本。分发版本用于区分同一应用程序发布版本的不同构建或部署变体。例如，分发版本可以是 Xcode 构建的构建号或 Android 构建的版本代码。分发版本的最大长度为 64 个字符。

`release`

设置发布版本。某些 SDK 可能会尝试自动配置发布版本，但最好手动设置以确保发布版本与部署集成或源映射上传同步。发布版本名称是字符串，但 Sentry 会检测某些格式并可能以不同的方式呈现。了解更多关于如何发送发布数据以便 Sentry 可以告诉你不同发布版本之间的回归并识别潜在来源的信息，请参阅发布文档或沙盒。

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

`environment`

设置环境。此字符串是自由格式的，默认情况下未设置。一个发布版本可以关联多个环境，以便在 UI 中将它们分开（例如 staging 与 prod 或类似）。

默认情况下，SDK 将尝试从 SENTRY_ENVIRONMENT 环境变量中读取此值（对于浏览器 SDK 不适用）。

`sampleRate`

配置错误事件的采样率，范围为 0.0 到 1.0。默认值为 1.0，这意味着 100% 的错误事件将被发送。如果设置为 0.1，则只有 10% 的错误事件将被发送。事件是随机选择的。

`maxBreadcrumbs`

此变量控制应捕获的面包屑总数。默认值为 100，但你可以将其设置为任何数字。然而，你应该意识到 Sentry 有一个最大有效负载大小，任何超过该有效负载大小的事件将被丢弃。

`maxCacheItems`

缓存中保留的最大信封数量。SDK 使用信封将数据（如事件、附件、用户反馈和会话）发送到 sentry.io。一个信封可以包含多个项目，例如一个带有两个附件的事件。根据 SDK 的使用情况，信封的大小可能会有所不同。如果本地缓存中的信封数量超过 maxCacheItems，SDK 将删除最旧的信封并将会话迁移到下一个信封，以维护发布健康统计的完整性。默认值为 30。

`attachStacktrace`

启用时，堆栈跟踪会自动附加到所有记录的消息中。堆栈跟踪始终附加到异常；但是，当启用此选项时，堆栈跟踪也会与消息一起发送。例如，这意味着堆栈跟踪会出现在所有日志消息旁边。

此选项默认开启。

Sentry 中带有堆栈跟踪和不带堆栈跟踪的事件的分组是不同的。因此，当你为某些事件启用或禁用此标志时，你将获得新的分组。

`sendDefaultPii`

如果启用此标志，某些个人身份信息 (PII) 将由活动集成添加。默认情况下，不会发送此类数据。

如果你在移动应用中使用 Sentry，请阅读我们的移动数据隐私常见问题解答，以协助处理 Apple App Store 和 Google Play 应用隐私详细信息。

此选项默认关闭。

如果你启用此选项，请确保使用我们的管理敏感数据 的功能手动删除你不想发送的内容。

`ignoreErrors`

一个字符串或正则表达式模式的列表，用于匹配不应发送到 Sentry 的错误消息。匹配这些字符串或正则表达式的消息在发送到 Sentry 之前将被过滤掉。使用字符串时，部分匹配也会被过滤掉，因此如果需要精确匹配，请使用正则表达式。默认情况下，所有错误都会发送。

`ignoreTransactions`

一个字符串或正则表达式模式的列表，用于匹配不应发送到 Sentry 的事务名称。匹配这些字符串或正则表达式的事务在发送到 Sentry 之前将被过滤掉。使用字符串时，部分匹配也会被过滤掉，因此如果需要精确匹配，请使用正则表达式。默认情况下，典型的 API 健康检查请求所涉及的事务会被过滤掉。

一个字符串或正则表达式模式的数组，用于匹配创建错误的脚本的 URL。在这些 URL 上创建的错误不会发送到 Sentry。如果您使用此选项，当顶级堆栈帧文件 URL 包含或匹配 denyUrls 数组中的至少一个条目时，错误将不会被发送到 Sentry。数组中的所有字符串条目将通过 stackFrameUrl.contains(entry) 进行匹配，而所有正则表达式条目将通过 stackFrameUrl.match(entry) 进行匹配。

这种匹配逻辑适用于捕获的异常，而不适用于原始消息事件。默认情况下，所有错误都会发送。

`allowUrls`

一个字符串或正则表达式模式的数组，用于匹配创建错误的脚本的 URL。只有在这些 URL 上创建的错误才会发送到 Sentry。如果您使用此选项，只有当顶级堆栈帧文件 URL 包含或匹配 allowUrls 数组中的至少一个条目时，错误才会被发送到 Sentry。数组中的所有字符串条目将通过 stackFrameUrl.contains(entry) 进行匹配，而所有正则表达式条目将通过 stackFrameUrl.match(entry) 进行匹配。

例如，如果您将 'foo.com' 添加到数组中，那么在 https://bar.com/myfile/foo.com 上创建的错误将被捕获，因为 URL 会通过“包含”逻辑进行匹配，并且 URL 的最后一段包含 foo.com。

这种匹配逻辑适用于捕获的异常，而不适用于原始消息事件。默认情况下，所有错误都会发送。

如果您的脚本是从 cdn.example.com 加载的，而您的网站是 example.com，您可以将 allowUrls 设置为以下内容，以仅捕获在这些位置的脚本中创建的错误：

Copied

Sentry.init({
  allowUrls: [/https?:\/\/((cdn|www)\.)?example\.com/],
});

`autoSessionTracking`

当设置为 true 时，SDK 将会话事件发送到 Sentry。这在所有浏览器 SDK 中都受支持，每个页面加载和页面导航都会向 Sentry 发送一个会话。在移动 SDK 中，当应用程序进入后台超过 30 秒时，会话将结束。

`maxValueLength`

单个值的最大字符数，在超过此长度时将被截断（默认为 250）。

`normalizeDepth`

Sentry SDK 会将任何上下文数据规范化到给定的深度。超出此深度的数据将被修剪，并使用其类型标记（如 [Object] 或 [Array]），而不再进一步遍历树。默认情况下，遍历深度为三层。

`normalizeMaxBreadth`

这是在 SDK 规范化上下文数据时，任何给定对象或数组中包含的最大属性或条目数。超出此深度的数据将被丢弃。（默认为 1000）

`attachScreenshot`

在发生错误时捕获应用程序的屏幕截图并将其作为附件包含。了解更多关于使用屏幕截图丰富事件的信息，请参阅我们的屏幕截图文档。

(新版本 4.11.0)

`attachViewHierarchy`

在发生错误时渲染应用程序整个视图层次结构的 JSON 表示，并将其作为附件包含。了解更多关于使用视图层次结构丰富事件的信息，请参阅我们的视图层次结构文档。

`enabled`

指定此 SDK 是否应将事件发送到 Sentry。默认为 true。将此设置为 enabled: false 不会阻止 Sentry 仪器化带来的所有开销。要完全禁用 Sentry，请根据环境条件调用 Sentry.init。

`enableCaptureFailedRequests`

启用后，此功能会自动捕获 HTTP 客户端错误（如错误响应代码）作为错误事件并报告给 Sentry。

(新版本 5.3.0)

对于许多平台 SDK，集成可以在初始化时进行配置。在某些平台上，这作为 init() 调用的一部分进行，在其他平台上，则适用不同的模式。

`integrations`

在某些 SDK 中，集成是通过此参数在库初始化时进行配置的。有关更多信息，请参阅特定集成的文档。

`defaultIntegrations`

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

这可以用于禁用默认启用的集成，如果 SDK 检测到相应的框架或库已安装。当设置为 false 时，这些集成将不会默认启用。

这些选项可以用于以各种方式钩住 SDK 以自定义事件的报告。

`beforeSend`

此函数在发送之前被调用，并传入一个 SDK 特定的消息或错误事件对象。它可以返回一个修改后的事件对象，或返回 null 以跳过事件的报告。例如，可以在发送之前手动剥离 PII。

在执行 beforeSend 时，所有范围数据已经应用到事件中。进一步修改范围将不会有任何效果。

`beforeSendTransaction`

此函数在发送之前被调用，并传入一个 SDK 特定的事务事件对象。它可以返回一个修改后的事务事件对象，或返回 null 以跳过事件的报告。一种使用方式是在发送之前手动剥离 PII。

此函数在面包屑添加到范围之前被调用，并传入一个 SDK 特定的面包屑对象。如果函数没有返回任何内容，面包屑将被丢弃。要传递面包屑，请返回第一个参数，其中包含面包屑对象。回调通常会获取第二个参数（称为“提示”），其中包含创建面包屑的原始对象，以便进一步自定义面包屑的外观。

传输用于将事件发送到 Sentry。传输可以在一定程度上进行自定义，以更好地支持高度特定的部署。

`transport`

切换用于发送事件的传输方式。具体实现取决于 SDK。例如，它可以用于捕获事件以便进行单元测试，或者通过需要代理认证的更复杂设置发送事件。

`transportOptions`

用于配置传输的选项。这是一个对象，包含以下可能的可选键：

headers: 包含每次请求发送的头信息的对象。由 SDK 的 fetch 和 XHR 传输使用。
fetchOptions: 包含传递给 fetch 调用的选项的对象。由 SDK 的 fetch 传输使用。

`shutdownTimeout`

控制在关闭之前等待的秒数。Sentry SDK 从后台队列发送事件。此队列有一定的缓冲时间来处理待处理的事件。默认值因 SDK 而异，但通常约为两秒。设置此值过低可能会导致命令行应用程序发送事件时出现问题。设置此值过高会导致在网络连接问题的情况下，应用程序阻塞较长时间。

`enableTracing`

一个布尔值，如果为 true，将生成并捕获事务和跟踪数据。如果未定义 tracesSampleRate，这将把 tracesSampleRate 设置为推荐的默认值 1.0。请注意，tracesSampleRate 和 tracesSampler 优先于此选项。

`tracesSampleRate`

一个介于 0 和 1 之间的数字，控制给定事务被发送到 Sentry 的百分比概率。（0 表示 0%，1 表示 100%。）适用于应用程序中创建的所有事务。必须定义此选项或 tracesSampler 以启用跟踪。

`tracesSampler`

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

`tracePropagationTargets`

一个可选属性，用于控制哪些下游服务接收跟踪数据，形式为在任何传出 HTTP 请求中附加的 sentry-trace 和 baggage 头。

该选项可以包含一个字符串列表或正则表达式列表，用于匹配传出请求的 URL。如果列表中的某个条目与传出请求的 URL 匹配，则跟踪数据将附加到该请求。字符串条目不需要完全匹配，这意味着只要请求的 URL 包含通过该选项提供的字符串即视为匹配。

如果未提供 tracePropagationTargets，跟踪数据将附加到应用程序（移动、桌面、电视）发出的每个传出请求。在 Web 环境中，跟踪数据仅附加到 URL 包含 localhost 或以 '/' 开头的传出请求（例如 GET /api/v1/users）。

如果你选择使用此选项，请遵循原生初始化指南。

应用卡顿