基本选项

了解如何配置 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）会自动读取。

如果您使用的是需要前缀才能将环境变量暴露给客户端的框架或运行时（如 Next.js 中的 NEXT_PUBLIC_ 和 Vite 中的 VITE_），必须在 init() 函数中设置这些选项。这些选项不会自动读取到客户端。这适用于 NEXT_PUBLIC_ 在 Next.js 和 VITE_ 在 Vite 等其他框架。

`dsn`

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

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

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

`debug`

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

`release`

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

默认情况下，SDK 将尝试从 window.SENTRY_RELEASE.id 中读取此值（如果可用）。

`environment`

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

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

`tunnel`

设置用于传输捕获事件的 URL。这可以用于绕过广告拦截器或更精细地控制发送到 Sentry 的事件。使用此选项时仍需添加 DSN，以便在生成的 Sentry 数据上设置必要的属性。此选项 需要实现 自定义服务器端点。了解更多并查看示例，请参阅处理广告拦截器。

`sampleRate`

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

`maxBreadcrumbs`

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

`attachStacktrace`

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

默认情况下，此选项是关闭的。

Sentry 中带有堆栈跟踪和不带堆栈跟踪的事件分组方式不同。因此，当您为某些事件启用或禁用此标志时，您会看到新的分组。

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

弃用通知

从 SDK 版本 8.43.0 开始，autoSessionTracking 选项已被弃用。您可以在浏览器环境中使用 BrowserSession 集成，在 Node.js 运行时使用 Http 集成（通过 trackIncomingRequestsAsSessions 选项）。

`initialScope`

要设置到初始作用域的数据。初始作用域可以定义为对象或回调函数，如下所示。

对象：

Copied

Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  debug: true,
  initialScope: {
    tags: { "my-tag": "my value" },
    user: { id: 42, email: "john.doe@example.com" },
  },
});

回调函数：

Copied

Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  debug: true,
  initialScope: (scope) => {
    scope.setTags({ a: "b" });
    return scope;
  },
});

`maxValueLength`

单个值的最大字符数，在截断之前（默认值为 250）。

`normalizeDepth`

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

`normalizeMaxBreadth`

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

`enabled`

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

`sendClientReports`

将此布尔值设置为 false 以禁用发送客户端报告。客户端报告是一种协议功能，允许客户端向 Sentry 发送关于自身的状态报告。它们目前主要用于发出从未发送的事件的结果。

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

`integrations`

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

`defaultIntegrations`

此选项用于禁用默认添加的集成。当设置为 false 时，不会添加任何默认集成。

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

`beforeSend`

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

在执行 beforeSend 时，所有作用域数据已应用于事件。进一步修改作用域将不会有任何效果。

`beforeSendTransaction`

此函数在发送 SDK 特定的事务事件对象时调用，可以返回一个修改后的事务事件对象，或返回 null 以跳过事件报告。例如，可以在发送前手动剥离 PII。

`beforeSendSpan`

在 Sentry JavaScript SDK v9.0.0 中，通过 beforeSendSpan 返回 null 来丢弃 span 的功能将被移除。回调函数将仅允许修改 span 属性。

此函数在发送序列化的 span 对象时调用，可以返回一个修改后的 span 对象，或返回 null 以跳过发送 span。这可能用于手动从 span 中剥离 PII 或从 span 树中移除单个 span。此函数仅针对根 span 的子 span 调用。如果要修改或丢弃根 span 及其所有子 span，请使用 beforeSendTransaction 代替。

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

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

`transport`

切换用于发送事件的传输。这取决于 SDK 的工作方式。例如，可以用于捕获单元测试中的事件，或通过需要代理身份验证的更复杂设置发送事件。

`transportOptions`

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

headers: 包含每个请求要发送的标头的对象。用于 SDK 的 fetch 和 XHR 传输。
fetchOptions: 包含传递给 fetch 调用的选项的对象。用于 SDK 的 fetch 传输。

传输

基本选项

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

`dsn`

`debug`

`release`

`environment`

`tunnel`

`sampleRate`

`attachStacktrace`

`ignoreErrors`

`ignoreTransactions`

`denyUrls`

`allowUrls`

`autoSessionTracking`

弃用通知

`initialScope`

`maxValueLength`

`normalizeDepth`

`normalizeMaxBreadth`

`enabled`

`sendClientReports`

`integrations`

`defaultIntegrations`

`beforeSend`

`beforeSendTransaction`

`beforeSendSpan`

`transport`

`transportOptions`

`enableTracing`

`tracesSampleRate`

`tracesSampler`