一起来刷 Sentry For Go 官方文档之 Enriching Events

添加 Context

自定义上下文允许您将任意数据附加到事件。您无法搜索这些，但可以在问题页面上查看它们：

如果需要能够搜索自定义数据，则需要使用标签。

要配置附加上下文:

sentry.ConfigureScope(func(scope *sentry.Scope) {
	scope.SetExtra("character.name", "Mighty Fighter")
})

注意，上下文的外部值必须是一个 dictionary/map/object，而内部值可以是任意的。

发送上下文时，请注意最大有效负载大小，尤其是如果您希望将整个应用程序状态作为额外数据发送时。Sentry不建议使用此方法，因为应用程序状态可能非常大，并且很容易超过 Sentry 在单个事件有效负载上的最大200kB。发生这种情况时，您会收到HTTP Error 413 Payload Too Large 消息，作为服务器响应，或者（当您将 keepalive: true 设置为 fetch 参数时），该请求将永远处于待处理状态（例如，在 Google Chrome 中）。

Sentry 将尽力容纳您发送的数据，但 Sentry 会修剪较大的上下文有效负载或完全截断这些有效负载。

有关更多详细信息，请参阅有关SDK数据处理的开发人员文档。

Extra Data, Additional Data(额外数据)

如果遇到 “extra”（在代码中为 SetExtra ）或 “Additional Data”（在用户界面中）的任何用法，请在头脑上将其替换为上下文。大多数 SDK 不推荐使用 Extra，而是使用上下文。

识别用户

用户包含一些关键信息，这些信息构成了 Sentry 中的唯一身份。每个选项都是可选的，但必须存在一个选项才能使 Sentry SDK 捕获用户：

id

您的用户内部标识符。

username

用户名。通常用作比内部ID更好的标签。

email

用户名的替代（或添加）。Sentry 知道电子邮件地址，并且可以显示 Gravatars 之类的内容并解锁消息传递功能。

ip_address

用户的IP地址。如果用户未经身份验证，Sentry 将 IP 地址用作用户的唯一标识符。Sentry 将尝试从 HTTP 请求数据中提取此信息（如果有）。

识别用户：

sentry.ConfigureScope(func(scope *sentry.Scope) {
	scope.SetUser(sentry.User{Email: "jane.doe@example.com"})
})

可以将其他 key/value 对指定为元数据，Sentry SDK会将这些键/值对与用户一起存储。

自定义标签

标签是既可索引又可搜索的 key/value 字符串对。标签具有强大的 UI 功能，例如过滤器和标签分布图。标签还可以帮助您快速访问相关事件，并查看一组事件的标签分布。标签的常见用法包括主机名，平台版本和用户语言。

我们将自动为一个事件的所有标签建立索引，以及 Sentry 看到标签的频率和最后一次。我们还将跟踪不同标签的数量，并可以帮助您确定各种问题的热点。

定义标签很容易，并将它们绑定到当前范围，确保范围内的所有未来事件都包含相同的标签：

sentry.ConfigureScope(func(scope *sentry.Scope) {
	scope.SetTag("page.locale", "de-at");
})

某些标签由 Sentry 自动设置。强烈建议您不要覆盖这些标签，而应使用自己的名称命名。

一旦开始发送标记的数据，您将在Sentry Web UI中看到它：“项目”页面侧栏中的过滤器，在事件内进行汇总以及在聚合事件的“标签”页面上。

面包屑

Sentry 使用面包屑创建事件发生之前的事件线索。这些事件与传统日志非常相似，但是可以记录更丰富的结构化数据。

此页面概述了手动面包屑记录和自定义。了解有关“Issue Details”页面上显示的更多信息， 以及如何过滤面包屑以快速解决问题。

:::tip 了解 SDK 使用情况

想要修改面包屑界面的开发人员可以使用专用于面包屑界面的开发人员文档详细了解此内容。:::

手动面包屑

每当发生有趣的事情时，您都可以手动添加面包屑。例如，如果用户通过身份验证或发生其他状态更改，则可以手动记录面包屑。

sentry.AddBreadcrumb(&sentry.Breadcrumb{
	Category: "auth",
	Message: "Authenticated user " + user.email,
	Level: sentry.LevelInfo,
});

自动面包屑

SDK 及其相关的集成将自动记录许多类型的面包屑。例如，浏览器 JavaScript SDK 将自动记录所有位置更改。

定制面包屑

SDK 允许您通过 before_breadcrumb hook 自定义面包屑。此 hook 传递了已经组装好的面包屑，并且在某些SDK中传递了可选提示。该函数可以修改面包屑，或通过返回 null 来决定完全放弃它：

sentry.Init(sentry.ClientOptions{
	BeforeBreadcrumb: func(breadcrumb *sentry.Breadcrumb, hint *sentry.BreadcrumbHint) *sentry.Breadcrumb {
		if breadcrumb.Category == "auth" {
			return nil
		}
		return breadcrumb
	},
})

用户反馈

当用户遇到错误时，Sentry 可以收集其他反馈。当您通常可以呈现简单的错误页面（经典的 500.html）时，这种类型的反馈很有用。

要收集反馈，请使用可嵌入的 JavaScript 小部件，该小部件将请求并收集用户的姓名，电子邮件地址以及发生的情况的描述。提供反馈后，Sentry 会将反馈与原始事件配对，从而使您对问题有更多见解。

下面的屏幕截图提供了“用户反馈”小部件的示例，尽管您的个性化可能因您的自定义而有所不同：

收集反馈

要集成小部件，您需要运行 2.1 版或更高版本的 JavaScript SDK。该小部件将使用您的公共 DSN 进行身份验证，然后传入在您的后端生成的事件 ID。

如果您希望使用窗口小部件的替代产品，或者没有 JavaScript 前端，则可以使用用户反馈API。

确保您有可用的 JavaScript SDK：

<script
  src="https://browser.sentry-cdn.com/5.27.2/bundle.min.js"
  integrity="sha384-+69fdGw+g5z0JJXjw46U9Ls/d9Y4Zi6KUlCcub+qIWsUoIlyimCujtv+EnTTHPTD"
  crossorigin="anonymous"
></script>

然后，您需要调用 showReportDialog 并传递生成的事件 ID。从所有对 CaptureEvent 和 CaptureException 的调用都返回此事件 ID。还有一个名为 LastEventId 的函数，该函数返回最近发送的事件的 ID。

<script>
  Sentry.init({ dsn: "https://examplePublicKey@o0.ingest.sentry.io/0" });
  Sentry.showReportDialog({
    eventId: "{{ event_id }}",
  });
</script>

自定义小部件

您可以根据组织的需要自定义窗口小部件，尤其是为了本地化目的。所有选项都可以通过 showReportDialog 调用传递。

Sentry 的自动语言检测(例如 lang=de)的覆盖

作用域与 Hub

捕获事件并将其发送到 Sentry 后，SDK 会将事件数据与当前作用域中的额外信息合并。SDK 通常会在框架集成中为您自动管理范围，而您无需考虑它们。但是，您应该知道什么是范围以及如何利用它来发挥自己的优势。

什么是 Scope，什么是 Hub

你可以把 hub 看作中心点，我们的 SDK 使用它来将事件路由到 Sentry。当您调用 init() 时，将创建一个 hub，并在其上创建一个 client 和一个 blank scope。然后，该中心与当前线程相关联，并将在内部持有一个作用域堆栈。

范围将包含应与事件一起发送的有用信息。例如，上下文或面包屑存储在 scope 上。当推入作用域时，它将继承父作用域的所有数据， 并且当其弹出时，所有修改都将还原。

默认的 SDK 集成将智能地推送和弹出作用域。例如，Web 框架集成将在您的路由或控制器周围创建和销毁作用域。

Scope 和 Hub 如何工作

在开始使用 SDK 时，将自动为您创建开箱即用的 Scope 和 Hub。除非您正在编写集成或希望创建或销毁作用域，否则您不太可能与 Hub 直接交互。另一方面，范围更面向用户。您可以在任何时候调用 configure-scope 来修改存储在该 Scope 上的数据。例如，它用于修改上下文。

在内部调用全局函数(如 capture_event )时，Sentry 会发现当前 Hub 并要求它捕获一个事件。然后，hub 将在内部将事件与最顶层 Scope 的数据合并。

配置 Scope

在使用作用域时，最有用的操作是 configure-scope 函数。它可用于重新配置当前范围。例如，这可以用来添加自定义标记或通知 sentry 关于当前经过身份验证的用户。

sentry.ConfigureScope(func(scope *sentry.Scope) {
	scope.SetTag("my-tag", "my value")
	scope.SetUser(sentry.User{
		ID: "42",
		Email: "john.doe@example.com",
	})
})

这也可以应用在注销时取消设置用户:

要了解哪些有用的信息可以与作用域关联，请参阅上下文文档。

局部作用域

我们还支持一次性推送和配置 scope。这通常被称为 with-scope 或 push-scope， 如果您只想用一个特定事件发送数据，这也非常有用。在下面的示例中，我们使用该函数仅为一个特定的错误附加一个级别和一个标签:

sentry.WithScope(func(scope *sentry.Scope) {
	scope.SetTag("my-tag", "my value");
	scope.SetLevel(sentry.LevelWarning);
	// will be tagged with my-tag="my value"
	sentry.CaptureException(errors.New("my error"))
})

// will not be tagged with my-tag
sentry.CaptureException(errors.New("my error"))

虽然这个示例看起来与 configure-scope 类似，但它有很大的不同， 因为 configure-scope 实际上更改了当前活动的作用域， 所以对 configure-scope 的所有后续调用将保留这些更改。

而另一方面，使用with-scope创建当前作用域的克隆，并将保持隔离，直到函数调用完成。因此，通过调用作用域上的clear，您可以在这里设置不想放在其他地方的上下文信息， 或者根本不附加任何上下文信息，而“全局”作用域保持不变。