上下文
自定义上下文允许您将任意数据(字符串、列表、字典)附加到事件中。
自定义上下文允许您将任意数据附加到事件中。通常,这些上下文会在其生命周期内与捕获的任何问题共享。您无法搜索这些上下文数据,但可以在问题页面上查看它们:
如果您需要能够搜索自定义数据,请使用标签。
附加自定义数据的最佳方式是使用结构化上下文。上下文必须始终是一个对象,其值可以是任意的。
首先,您需要像往常一样导入 SDK:
import * as Sentry from "@sentry/browser";
然后,使用 setContext
并为上下文指定一个唯一名称:
Sentry.setContext("character", {
name: "Mighty Fighter",
age: 19,
attack_type: "melee",
});
上下文名称没有限制。在上下文对象中,所有键都是允许的,除了 type
,它被内部使用。
默认情况下,Sentry SDK 会将嵌套的结构化上下文数据规范化到最多三层深。超过这个深度的数据将被修剪,并用其类型标记。要调整此默认行为,请使用 normalizeDepth
SDK 选项。
了解更多关于常见上下文的约定,请参阅 上下文接口开发文档。
在发送上下文时,请考虑有效负载大小的限制。Sentry 不建议在上下文中发送整个应用程序状态和大型数据块。如果超出最大有效负载大小,Sentry 将返回 HTTP 错误 413 Payload Too Large
并拒绝该事件。当使用 keepalive: true
时,请求可能会无限期地处于挂起状态。
Sentry SDK 会尽力适应您发送的数据并修剪过大的上下文有效负载。某些 SDK 可以截断事件的部分内容;更多详情,请参阅 SDK 数据处理的开发文档。
某些上下文数据可以直接提供给 captureException
和 captureMessage
调用。提供的数据将与当前作用域中已存储的数据合并,除非通过回调方法显式清除。
此功能有三种不同的变体:
- 包含可更新属性的普通对象
- 从中提取属性的作用域实例
- 接收当前作用域作为参数并允许修改的回调函数
我们可以传递以下上下文键:tags
、extra
、contexts
、user
、level
、fingerprint
。
Sentry.captureException(new Error("something went wrong"), {
tags: {
section: "articles",
},
});
明确清除已在作用域中存储的内容:
Sentry.captureException(new Error("clean as never"), (scope) => {
scope.clear();
scope.setTag("clean", "slate");
return scope;
});
使用 Scope 实例传递数据(其属性仍将与全局作用域合并):
const scope = new Sentry.Scope();
scope.setTag("section", "articles");
Sentry.captureException(new Error("something went wrong"), scope);
使用 Scope 实例传递数据并忽略全局配置的作用域属性:
const scope = new Sentry.Scope();
scope.setTag("section", "articles");
Sentry.captureException(new Error("something went wrong"), () => scope);
上下文存储在当前作用域中,因此当作用域被移除(“弹出”)时,上下文也会被清除。您可以推送和弹出自己的作用域,以将上下文数据应用到特定的代码块或函数。
Sentry 支持两种不同的方式来清除上下文:
- 修改、覆盖或清除当前作用域中的值。
- 创建一个临时作用域来捕获异常。
使用以下代码片段,user
上下文将被更新,适用于当前作用域中所有未来的事件:
Sentry.setUser(someUser);
如果您想从当前作用域中移除所有数据,可以调用:
Sentry.getCurrentScope().clear();
以下代码仅会为 withScope
回调中捕获的错误配置 user
上下文。之后,上下文将自动恢复到之前的状态:
Sentry.withScope(function (scope) {
scope.setUser(someUser);
Sentry.captureException(error);
});
要了解更多关于设置作用域的信息,请参阅我们的 Scopes 和 Hubs 文档。
额外数据已弃用,建议使用结构化上下文。
Sentry 曾经支持通过 setExtra
添加非结构化的“额外数据”。