上下文

自定义上下文允许您将任意数据(字符串、列表、字典)附加到事件中。

自定义上下文允许您将任意数据附加到事件中。通常,这些上下文会在其生命周期内与捕获的任何问题共享。您无法搜索这些上下文数据,但可以在问题页面上查看它们:

Custom contexts as viewed on the Additional Data section of an event

如果您需要能够搜索自定义数据,请使用标签

附加自定义数据的最佳方式是使用结构化上下文。上下文必须始终是一个对象,其值可以是任意的。

首先,您需要像往常一样导入 SDK:

Copied
import * as Sentry from "@sentry/browser";

然后,使用 setContext 并为上下文指定一个唯一名称:

Copied
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 数据处理的开发文档

某些上下文数据可以直接提供给 captureExceptioncaptureMessage 调用。提供的数据将与当前作用域中已存储的数据合并,除非通过回调方法显式清除。

此功能有三种不同的变体:

  1. 包含可更新属性的普通对象
  2. 从中提取属性的作用域实例
  3. 接收当前作用域作为参数并允许修改的回调函数

我们可以传递以下上下文键:tagsextracontextsuserlevelfingerprint

Copied
Sentry.captureException(new Error("something went wrong"), {
  tags: {
    section: "articles",
  },
});

明确清除已在作用域中存储的内容:

Copied
Sentry.captureException(new Error("clean as never"), (scope) => {
  scope.clear();
  scope.setTag("clean", "slate");
  return scope;
});

使用 Scope 实例传递数据(其属性仍将与全局作用域合并):

Copied
const scope = new Sentry.Scope();
scope.setTag("section", "articles");
Sentry.captureException(new Error("something went wrong"), scope);

使用 Scope 实例传递数据并忽略全局配置的作用域属性:

Copied
const scope = new Sentry.Scope();
scope.setTag("section", "articles");
Sentry.captureException(new Error("something went wrong"), () => scope);

上下文存储在当前作用域中,因此当作用域被移除(“弹出”)时,上下文也会被清除。您可以推送和弹出自己的作用域,以将上下文数据应用到特定的代码块或函数。

Sentry 支持两种不同的方式来清除上下文:

  1. 修改、覆盖或清除当前作用域中的值。
  2. 创建一个临时作用域来捕获异常。

使用以下代码片段,user 上下文将被更新,适用于当前作用域中所有未来的事件:

Copied
Sentry.setUser(someUser);

如果您想从当前作用域中移除所有数据,可以调用:

Copied
Sentry.getCurrentScope().clear();

以下代码仅会为 withScope 回调中捕获的错误配置 user 上下文。之后,上下文将自动恢复到之前的状态:

Copied
Sentry.withScope(function (scope) {
  scope.setUser(someUser);
  Sentry.captureException(error);
});

要了解更多关于设置作用域的信息,请参阅我们的 Scopes 和 Hubs 文档

额外数据已弃用,建议使用结构化上下文。

Sentry 曾经支持通过 setExtra 添加非结构化的“额外数据”。