基本选项

了解如何配置 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 将尝试从 SENTRY_RELEASE 环境变量中读取此值。

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

serverName

此选项可用于提供“服务器名称”。提供后，服务器名称将随事件一起发送并持久化。对于许多集成，服务器名称实际上对应于设备的主机名，即使该机器实际上不是服务器。

大多数 SDK 将尝试自动发现此值。

ignoreErrors

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

ignoreTransactions

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

autoSessionTracking

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

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 发送关于自身的状态报告。它们目前主要用于发出从未发送的事件的结果。

includeLocalVariables

将此布尔值设置为 true 以将堆栈局部变量添加到堆栈跟踪中。默认值为 false。

有关更多高级配置选项，请参阅本地变量集成选项文档。

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

integrations

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

defaultIntegrations

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

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

beforeSend

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

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

beforeSendTransaction

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

beforeSendSpan

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

beforeBreadcrumb

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

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

transport

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

transportOptions

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

  • headers: 包含每个请求要发送的标头的对象。
  • proxy: 用于出站请求的代理。可以是 http 或 https。
  • caCerts: CA 证书的路径或路径列表，或 CA 证书的缓冲区。
  • httpModule: 用于请求的自定义 HTTP 模块。默认为原生的 http 和 https 模块。
  • keepAlive: 确定是否在请求之间保持套接字连接。默认为 false。

shutdownTimeout

控制在关闭之前等待的秒数。Sentry SDK 从后台队列发送事件。此队列被赋予一定的时间来清空待处理事件。默认值因 SDK 而异，但通常约为两秒。将此值设置得太低可能会导致从命令行应用程序发送事件出现问题。将此值设置得太高会导致用户体验网络连接问题时应用程序阻塞很长时间。

enableTracing

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

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，跟踪数据将附加到从已仪器化的客户端发出的每个传出请求。

Previous
配置
Next
环境
粤ICP备18022507号-4