基本选项

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

SDK 可以通过多种选项进行配置。这些选项在不同 SDK 之间 largely 标准化，但为了更好地适应平台特性，也存在一些差异。选项在 SDK 首次初始化时设置。

Options are passed to the init() method as an array:

Copied

\Sentry\init([
    'dsn' => 'https://examplePublicKey@o0.ingest.sentry.io/0',
    'max_breadcrumbs' => 50,
]);

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

`dsn`

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

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

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

`logger`

如果启用，SDK 会在发送事件时打印出调试信息，指示是否出现问题。不建议在生产环境中使用此功能。

Copied

// This logs messages to the provided file path
Sentry\init([
    'logger' => new \Sentry\Logger\DebugFileLogger(filePath: ROOT . DS . 'sentry.log'),
]);

// This logs messages to stdout
Sentry\init([
    'logger' => new \Sentry\Logger\DebugStdOutLogger(),
]);

`release`

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

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

`environment`

设置环境。这个字符串是自由格式，默认设置为 production。一个发布版本可以关联多个环境，以便在 UI 中区分它们（例如 staging 和 production）。

默认情况下，SDK 将尝试从 SENTRY_ENVIRONMENT 环境变量中读取此值。

`error_types`

设置哪些错误将被报告。它接受与 PHP 的 error_reporting 配置参数相同的值。

默认情况下，所有类型的错误都会被报告（等同于 E_ALL）。

`sample_rate`

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

`max_breadcrumbs`

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

`attach_stacktrace`

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

此选项默认是关闭的。

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

`send_default_pii`

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

如果您在移动应用中使用 Sentry，请阅读我们关于移动数据隐私的常见问题，以帮助处理 Apple App Store 和 Google Play 应用的隐私细节。

此选项默认是关闭的。

如果您启用了此选项，请务必使用我们管理 敏感数据 的功能手动移除您不想发送的数据。

`server_name`

此选项可用于提供一个“服务器名称”。当提供时，服务器名称将随事件一起发送并持久保存。对于许多集成，服务器名称实际上对应于设备主机名，即使在机器实际上不是服务器的情况下也是如此。

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

`ignore_exceptions`

一个类名列表，匹配不应发送到 Sentry 的异常。检查提供的类名是否为给定类型或子类型。

`ignore_transactions`

一个字符串列表，匹配不应发送到 Sentry 的事务名称。

`in_app_include`

一个字符串前缀列表，表示属于应用程序的模块名称。此选项优先于 in-app-exclude。

Sentry 区分直接与您的应用程序相关的堆栈帧（“应用程序内”）和其他包（如标准库、框架或其他依赖项）中的堆栈帧。应用程序包会被自动标记为 inApp。这种区别在 sentry.io 中是可见的，默认情况下仅显示“应用程序内”的帧。

`in_app_exclude`

一个字符串前缀列表，表示不属于应用程序的模块名称，而是属于第三方包。被认为是不属于应用程序的模块默认会从堆栈跟踪中隐藏。

此选项可以使用 in_app_include 进行覆盖。

`max_request_body_size`

此参数控制集成是否应捕获 HTTP 请求体。它可以设置为以下值之一：

never: 从不发送请求体。
small: 仅捕获小请求体。具体的小请求体大小取决于 SDK（通常是 4KB）。
medium: 捕获中等和小请求体（通常是 10KB）。
always: 只要 Sentry 能解析，SDK 将始终捕获请求体。

`max_value_length`

事件有效负载中包含文本的值在截断之前的字符数（默认为 1024）。

如果您设置的值非常大，事件可能会超过 1 MiB，并将被 Sentry 丢弃。

`context_lines`

加载文件时，堆栈跟踪中每个帧的上下文行数。

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

`before_send`

此函数会在 SDK 特定的消息或错误事件对象传递时被调用，可以返回修改后的事件对象，或者返回 null 以跳过报告该事件。例如，可以在发送前用于手动剥离 PII（个人身份信息）。

当 before_send 执行时，所有作用域数据已经应用到事件中。进一步修改作用域将不会产生任何效果。

`before_send_transaction`

此函数会在 SDK 特定的事务事件对象传递时被调用，可以返回修改后的事务事件对象，或者返回 null 以跳过报告该事件。例如，可以在发送前用于手动剥离 PII（个人身份信息）。

`before_send_check_in`

此函数会在 SDK 特定的签到事件对象传递时被调用，可以返回修改后的签到事件对象，或者返回 null 以跳过报告该事件。

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

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

`transport`

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

`http_proxy`

当设置时，可以配置一个用于出站请求的代理。这也适用于 HTTPS 请求，除非单独配置了 https-proxy。然而，并非所有 SDK 都支持独立的 HTTPS 代理。SDK 将尝试默认使用系统范围配置的代理（如果可能）。例如，在 Unix 系统上，会读取 http_proxy 环境变量。

`send_attempts`

已废弃. 控制 SDK 尝试重新发送事件到 Sentry 的次数。默认值为 0。

`http_connect_timeout`

尝试连接到服务器时的最大等待秒数。默认值为 2 秒。

`http_timeout`

整个请求和响应的最大执行时间（以秒为单位）。该值还应包括连接阶段的时间，因此应大于 http_connect_timeout 选项的值。默认值为 5 秒。

`traces_sample_rate`

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

`traces_sampler`

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

`trace_propagation_targets`

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

该选项可以包含一个字符串列表，用以匹配传出请求的主机。如果列表中的一个条目与传出请求的主机匹配，则会在该请求中附加追踪数据。

如果不提供 trace_propagation_targets，追踪数据将附加到所有从已 instrumented 客户端发出的请求。要禁用向任何下游服务发送追踪数据，请将此选项设置为空数组 ([])。

配置

环境