过滤

当您将 Sentry 添加到应用程序中时，可以获得许多关于错误和性能的宝贵信息。大量信息是好的——只要它是正确的信息，并且量适中。

Sentry SDK 提供了多个配置选项来帮助您过滤事件。

我们还提供了 入站过滤器 以在 sentry.io 中过滤事件。不过，我们建议在客户端级别进行过滤，因为这可以消除发送不需要的事件的开销。了解更多关于 事件中的字段 的信息。

过滤错误事件

通过使用 before_send 回调方法和配置、启用或禁用集成来配置 SDK 以过滤错误事件。

使用 before_send

所有 Sentry SDK 都支持 before_send 回调方法。因为它在事件发送到服务器之前立即调用，这是您最后一次决定不发送数据或编辑数据的机会。before_send 接收事件对象作为参数，您可以根据自定义逻辑和事件中的数据来修改事件数据或通过返回 null 完全丢弃事件。

在 Laravel 配置中，可以使用闭包来修改事件或返回一个全新的事件。如果返回 null，事件将被丢弃。

'before_send' => function (\Sentry\Event $event): ?\Sentry\Event {
    return $event;
},

请注意，面包屑也可以被过滤，具体方法如下

事件提示

before_send 回调传递了两个参数：event 和一个名为 hint 的第二个参数，hint 包含一个或多个提示。

通常，hint 包含原始异常，以便提取其他数据或影响分组。在此示例中，如果捕获到某种类型的异常，则强制将指纹设置为一个通用值：

'before_send' => function (\Sentry\Event $event, ?\Sentry\EventHint $hint): ?\Sentry\Event {
    // Ignore the event if the original exception is an instance of MyException
    if ($hint !== null && $hint->exception instanceof MyException) {
      return null;
    }

    return $event;
},

当 SDK 创建事件或面包屑以进行传输时，该传输通常从某种源对象创建。例如，错误事件通常从日志记录或异常实例创建。为了更好的自定义，SDK 将这些对象发送到某些回调（before_send、before_breadcrumb 或 SDK 中的事件处理器系统）。

使用提示

提示在两个地方可用：

1. before_send / before_breadcrumb
2. eventProcessors

事件和面包屑的 hints 是包含各种信息的对象，用于构建事件或面包屑。通常，hints 包含原始异常，以便提取其他数据或影响分组。

对于事件，提示包含的属性有 event_id、originalException、syntheticException（用于内部生成更清晰的堆栈跟踪）以及任何其他附加的 data。

对于面包屑，提示的使用取决于实现。对于 XHR 请求，提示包含 xhr 对象本身；对于用户交互，提示包含 DOM 元素和事件名称等。

'before_send' => function (\Sentry\Event $event, ?\Sentry\EventHint $hint): ?\Sentry\Event {
    if ($hint !== null && $hint->exception !== null && str_contains($hint->exception->getMessage(), 'database unavailable')) {
        $event->setFingerprint(['database-unavailable']);
    }

    return $event;
},

事件的提示

originalException

导致 Sentry SDK 创建事件的原始异常。这对于更改 Sentry SDK 如何对事件进行分组或提取其他信息非常有用。

syntheticException

当引发字符串或非错误对象时，Sentry 会创建一个合成异常，以便您可以获取基本的堆栈跟踪。此异常存储在这里以进行进一步的数据提取。

面包屑的提示

event

对于从浏览器事件创建的面包屑，Sentry SDK 通常会将事件作为提示提供给面包屑。这可以用于从目标 DOM 元素中提取数据到面包屑中，例如。

level / input

对于从控制台日志拦截创建的面包屑。这包含原始的控制台日志级别和传递给日志函数的原始输入数据。

response / input

对于从 HTTP 请求创建的面包屑。这包含响应对象（来自 fetch API）和传递给 fetch 函数的输入参数。

request / response / event

对于从 HTTP 请求创建的面包屑。这包含请求和响应对象（来自 Node.js HTTP API）以及 Node.js 事件（response 或 error）。

xhr

对于使用旧版 XMLHttpRequest API 创建的 HTTP 请求面包屑。这包含原始的 xhr 对象。

使用 ignore_exceptions

您可以使用 ignore_exceptions 选项来过滤掉与特定类型或子类型匹配的错误。

'ignore_exceptions' => [
    UnauthenticatedException::class,
],

过滤事务事件

为了防止某些事务被报告给 Sentry，可以使用 traces_sampler 或 before_send_transaction 配置选项，这允许您提供一个函数来评估当前事务并在不需要时丢弃它。

使用 traces_sampler

注意： traces_sampler 和 traces_sample_rate 配置选项是互斥的。如果您定义了一个 traces_sampler 来过滤某些事务，您还必须处理未过滤的事务情况，并返回您希望对它们进行采样的速率。

在最简单的形式中，仅用于过滤事务，如下所示：

'traces_sampler' => function (\Sentry\Tracing\SamplingContext $context): float {
    if ($context->getParentSampled()) {
        // If the parent transaction (for example a JavaScript front-end)
        // is sampled, also sample the current transaction
        return 1.0;
    }

    if (some_condition()) {
        // Drop this transaction, by setting its sample rate to 0
        return 0;
    }

    // Default sample rate for all other transactions (replaces `traces_sample_rate`)
    return 0.25;
},

它还允许您以不同的速率对不同的事务进行采样。

如果当前正在处理的事务具有父事务（来自调用此服务的上游服务），父（上游）采样决策将始终包含在采样上下文数据中，以便您的 traces_sampler 可以选择是否以及何时继承该决策。在大多数情况下，继承是正确的选择，以避免分布式跟踪中断。中断的跟踪将不包括所有服务。请参见 继承父采样决策 以了解更多信息。

了解更多关于 配置采样率 的信息。

使用 before_send_transaction

在 Laravel 配置中，可以使用闭包来修改事务事件或返回一个全新的事件。如果返回 null，事件将被丢弃。

'before_send_transaction' => function (\Sentry\Event $transaction): ?\Sentry\Event {
    return $transaction;
},

使用 ignore_transactions

您可以使用 ignore_transactions 选项来过滤掉与特定字符串匹配的事务。

'ignore_transactions' => [
    'GET /health',
],

过滤检查事件

使用 before_send_check_in

在 Laravel 配置中，可以使用闭包来修改检查事件或返回一个全新的事件。如果返回 null，事件将被丢弃。

'before_send_check_in' => function (\Sentry\Event $event): ?\Sentry\Event {
    $checkIn = $event->getCheckIn();
    $checkInEnvironment = $checkIn->getEnvironment();

    if ($checkInEnvironment !== 'production') {
        return null;
    }

    return $event;
},