过滤

了解如何配置 SDK 以过滤报告给 Sentry 的事件。

当你将 Sentry 添加到应用中时，可以获得关于错误和性能的大量有价值的信息。大量信息是有益的——只要它们是正确的信息，并且数量合理。

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

我们还提供了 入站过滤器 来在 sentry.io 中过滤事件。不过，我们建议在客户端级别进行过滤，因为这样可以避免发送你实际上不需要的事件的开销。了解更多关于事件中的可用字段。

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

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

在 JavaScript 中，您可以使用一个函数来修改事件或返回一个全新的事件。 您可以返回 null 或事件有效负载——不允许返回其他任何值（包括 void）。 如果您返回 null，该事件将被丢弃。

Copied
Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",

  // Called for message and error events
  beforeSend(event) {
    // Modify or drop the event here
    if (event.user) {
      // Don't send user's email address
      delete event.user.email;
    }
    return event;
  },
});

注意，也可以过滤面包屑，具体请参阅我们的面包屑文档。

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

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

Copied
Sentry.init({
  // ...
  beforeSend(event, hint) {
    const error = hint.originalException;
    if (
      error &&
      error.message &&
      error.message.match(/database unavailable/i)
    ) {
      event.fingerprint = ["database-unavailable"];
    }
    return event;
  },
});

有关可用提示的更多信息，请参阅 JavaScript 中的提示。

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

提示在两个地方可用：

  1. beforeSend / beforeBreadcrumb
  2. eventProcessors

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

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

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

Copied
Sentry.init({
  // ...
  beforeSend(event, hint) {
    const error = hint.originalException;
    if (
      error &&
      error.message &&
      error.message.match(/database unavailable/i)
    ) {
      event.fingerprint = ["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 对象。

你可以使用 ignoreErrors 选项来过滤掉与某个模式匹配的错误。此选项接收一个字符串和正则表达式的列表，用于匹配错误消息。使用字符串时，部分匹配将被过滤掉，因此如果需要精确匹配，请使用正则表达式模式。

Copied
Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  ignoreErrors: ["fb_xd_fragment", /^Exact Match Message$/],
});

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

注意： tracesSampler 和 tracesSampleRate 配置选项是互斥的。如果你定义了一个 tracesSampler 来过滤某些事务，你必须通过返回你希望采样的速率来处理未过滤的事务。

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

Copied
// The shape of samplingContext that is passed to the tracesSampler function
interface SamplingContext {
  // Name of the span
  name: string;
  // Initial attributes of the span
  attributes: SpanAttributes | undefined;
  // If the parent span was sampled - undefined if there is no parent span
  parentSampled: boolean | undefined;
}

Sentry.init({
  // ...

  tracesSampler: ({ name, attributes, parentSampled }) => {
    // Do not sample health checks ever
    if (name.includes("healthcheck")) {
      // Drop this transaction, by setting its sample rate to 0%
      return 0;
    }

    // Continue trace decision, if there is any parentSampled information
    if (typeof parentSampled === "boolean") {
      return parentSampled;
    }

    // Else, use default sample rate (replacing tracesSampleRate)
    return 0.5;
  },
});

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

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

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

Copied
Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",

  // Called for transaction events
  beforeSendTransaction(event) {
    // Modify or drop the event here
    if (event.transaction === "/unimportant/route") {
      // Don't send the event to Sentry
      return null;
    }
    return event;
  },
});

你可以使用 ignoreTransactions 选项来过滤掉与某个模式匹配的事务。此选项接收一个字符串和正则表达式的列表，用于匹配事务名称。使用字符串时，部分匹配将被过滤掉，因此如果需要精确匹配，请使用正则表达式模式。

Copied
Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  ignoreTransactions: ["partial/match", /^Exact Transaction Name$/],
});
Previous
采样
Next
关闭和清空
粤ICP备18022507号-4