过滤
了解如何配置您的 SDK 以过滤报告给 Sentry 的事件。
当您将 Sentry 添加到您的应用程序时,会获得大量关于错误和性能的有价值信息。大量的信息是好的——只要它是正确且适量的信息。
Sentry 提供了 入站过滤器,您可以为每个项目启用这些过滤器以在 sentry.io 中过滤各种事件。您可以使用我们预定义的入站过滤器(例如,过滤已知的浏览器扩展),也可以添加自己的基于消息的过滤器。
然而,我们建议在客户端级别进行过滤,因为这可以避免发送不需要的事件所带来的开销。Sentry SDK 提供了几种配置选项,本文档中对此进行了描述,以帮助您过滤事件。要了解更多可用于过滤的事件字段,请参阅 事件有效负载。
通过使用 beforeSend
回调方法以及配置、启用或禁用集成,您可以配置 SDK 以过滤错误事件。
您可以使用 ignoreErrors
选项来过滤与特定模式匹配的错误。此选项接收一个字符串和正则表达式的列表,用于匹配错误消息。当使用字符串时,部分匹配的错误将被过滤掉。如果您需要进行精确匹配,请改用正则表达式模式。
Sentry.init({
dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
ignoreErrors: ["fb_xd_fragment", /^Exact Match Message$/],
});
您可以配置一个 beforeSend
回调方法来过滤错误事件。由于它在事件发送到服务器之前立即被调用,因此这是您决定是否不发送数据或编辑数据的最后机会。beforeSend
接收事件对象作为参数,并根据自定义逻辑和事件中的可用数据,您可以修改事件的数据或通过返回 null
完全丢弃该事件。
在 JavaScript 中,您可以使用一个函数来修改事件或返回一个全新的事件。 您可以返回 null
或事件有效负载——不允许返回其他任何值(包括 void
)。 如果您返回 null
,该事件将被丢弃。
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;
},
});
另外需要注意的是,面包屑(breadcrumbs)也可以被过滤,具体请参阅 我们的 Breadcrumbs 文档。
beforeSend
回调不仅接收 event
,还接收第二个参数 hint
,其中包含一个或多个提示。
通常,hint
包含原始异常,以便从中提取额外数据或影响分组。在以下示例中,如果捕获了特定类型的异常,则强制指纹设置为一个通用值:
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 中的事件处理器系统)。
提示在两个地方可用:
beforeSend
/beforeBreadcrumb
eventProcessors
事件和面包屑的 hints
是包含各种信息的对象,用于组装事件或面包屑。通常,hints
包含原始异常,以便从中提取额外数据或影响分组。
对于事件,hints
包含以下属性:
event_id
originalException
syntheticException
(用于生成更清晰的堆栈跟踪,内部使用)- 任意附加的
data
对于面包屑,hints
的使用取决于具体实现。例如:
- 对于 XHR 请求,
hint
包含 xhr 对象本身; - 对于用户交互,
hint
包含 DOM 元素和事件名称等。
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
对象。
您可以构建一个错误的允许域名列表。只有在这些域内创建的错误才会被捕获。例如,如果您的脚本是从 cdn.example.com
加载的,而您的网站是 example.com
,您可以将 allowUrls
设置为:
Sentry.init({
allowUrls: [/https?:\/\/((cdn|www)\.)?example\.com/],
});
如果您希望阻止特定 URL 上创建的错误被发送到 Sentry,也可以使用 denyUrls
。
适用于从版本 8.10.0 开始的基于浏览器的 SDK
thirdPartyErrorFilterIntegration
允许您过滤来自第三方的错误,例如浏览器扩展、注入代码的浏览器或也使用 Sentry 的第三方服务的小部件。此集成可以帮助减少与您自己的应用程序代码无关的噪声。
前提条件:要使用 thirdPartyErrorFilterIntegration
,请确保您正在使用打包工具和 Sentry 的打包工具插件之一。
此集成通过在构建过程中用“应用程序密钥”标记您的 JavaScript 文件来工作。运行时,如果发生错误,此集成会检查堆栈跟踪中每个堆栈帧的应用程序密钥。这使您可以过滤掉带有“未标记”堆栈帧的错误,这些错误通常表示第三方代码。
要设置此集成并用应用程序密钥标记您的 JavaScript 文件,请首先将 applicationKey
选项传递给您的 Sentry 打包工具插件。这可以是任意字符串,用于标识您的应用程序代码:
// vite.config.ts
import { defineConfig } from "vite";
import { sentryVitePlugin } from "@sentry/vite-plugin";
export default defineConfig({
plugins: [
sentryVitePlugin({
applicationKey: "your-custom-application-key",
}),
],
});
接下来,在您的 Sentry 初始化中添加 thirdPartyErrorFilterIntegration
:
Sentry.init({
integrations: [
Sentry.thirdPartyErrorFilterIntegration({
// Specify the application keys that you specified in the Sentry bundler plugin
filterKeys: ["your-custom-application-key"],
// Defines how to handle errors that contain third party stack frames.
// Possible values are:
// - 'drop-error-if-contains-third-party-frames'
// - 'drop-error-if-exclusively-contains-third-party-frames'
// - 'apply-tag-if-contains-third-party-frames'
// - 'apply-tag-if-exclusively-contains-third-party-frames'
behaviour: "drop-error-if-contains-third-party-frames",
}),
],
});
filterKeys
选项接收一个字符串数组,这些字符串应与打包工具插件选项中设置的 applicationKey
值相匹配。除非您的网站托管了来自多个构建过程的文件,否则该数组应仅包含一个项。
behaviour
选项定义了如何处理包含第三方代码堆栈帧的错误。您可以选择四种模式:
"drop-error-if-contains-third-party-frames"
:丢弃包含至少一个第三方堆栈帧的错误事件。"drop-error-if-exclusively-contains-third-party-frames"
:丢弃仅包含第三方堆栈帧的错误事件。"apply-tag-if-contains-third-party-frames"
:保留所有错误事件,但如果错误包含至少一个第三方堆栈帧,则应用third_party_code: true
标签。"apply-tag-if-exclusively-contains-third-party-frames"
:保留所有错误事件,但如果错误仅包含第三方堆栈帧,则应用third_party_code: true
标签。
如果您选择仅应用标签的模式,这些标签可以在 Sentry 中用于通过 third_party_code
标签在问题搜索栏中过滤您的问题流。
thirdPartyErrorFilterIntegration
不适用于 Sentry Loader Script 或 CDN Bundles。这是因为 Sentry Loader Script 和 CDN Bundles 被该集成检测为“第三方”。这会导致几乎所有的事件都应用所选的行为,因为 Sentry SDK 包装了许多浏览器原生的 API。
要防止某些事务被报告给 Sentry,可以使用 tracesSampler
或 beforeSendTransaction
配置选项,这些选项允许您提供一个函数来评估当前事务并在不需要时丢弃它。
您可以使用 ignoreTransactions
选项来过滤与特定模式匹配的事务。此选项接收一个字符串和正则表达式的列表,用于匹配事务名称。当使用字符串时,部分匹配的事务将被过滤掉。如果您需要进行精确匹配,请改用正则表达式模式。
Sentry.init({
dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
ignoreTransactions: ["partial/match", /^Exact Transaction Name$/],
});
注意: tracesSampler
和 tracesSampleRate
配置选项是互斥的。如果您定义了一个 tracesSampler
来过滤某些事务,则还必须处理未过滤事务的情况,通过返回您希望采样的比率。
最简单的形式,仅用于过滤事务时,它看起来像这样:
// 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
可以选择是否以及何时继承该决策。在大多数情况下,继承是正确的选择,以避免破坏分布式跟踪。断裂的跟踪将不会包含所有您的服务。更多详情请参阅 继承父级采样决策。
了解更多关于 配置采样率 的信息。
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;
},
});
自 Javascript SDK 版本 8.2.0
起可用。
要防止某些跨度被报告给 Sentry,可以使用 beforeSendSpan
配置选项,该选项允许您提供一个函数来修改和丢弃子跨度。此函数仅对根跨度的子跨度调用。如果您想修改或丢弃根跨度及其子跨度,请使用 beforeSendTransaction
。
在 Sentry JavaScript SDK v9.0.0 中,通过 beforeSendSpan
返回 null
来丢弃 span 的功能将被移除。回调函数将仅允许修改 span 属性。
Sentry.init({
dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
// Called for spans
beforeSendSpan(span) {
// Modify or drop the span here
if (span.description === "unimportant span") {
// Don't send the span to Sentry
return null;
}
return span;
},
});