Sentry 开发者贡献指南 - SDK 开发(性能监控)

内容整理于官方开发文档

系列

• Docker Compose 部署与故障排除详解
• K8S + Helm 一键微服务部署
• Sentry 开发者贡献指南 - 前端(ReactJS生态)
• Sentry 开发者贡献指南 - 后端服务(Python/Go/Rust/NodeJS)
• Sentry 开发者贡献指南 - 前端 React Hooks 与虫洞状态管理模式

性能监控指南

本文档介绍了 SDK 应如何通过分布式跟踪添加对性能监控的支持。

• https://docs.sentry.io/product/performance/distributed-tracing/

这应该提供 SDK 需要实现的 API 的概述，而不强制要求内部实现细节。

参考实现：

• @sentry/tracing
  (JavaScript)
  • https://github.com/getsentry/sentry-javascript/tree/master/packages/tracing
• Python SDK
  • https://github.com/getsentry/sentry-python/blob/master/sentry_sdk/tracing.py

SDK 配置

通过设置两个新的 SDK 配置选项之一来启用跟踪，tracesSampleRate 和 tracesSampler。如果未设置，则两者都默认为 undefined，从而选择如何加入跟踪。

tracesSampleRate

这应该是介于 0.0 和 1.0(含)之间的 float/double，表示任何给定 transaction 将被发送到 Sentry 的百分比机会。
因此，0.0 是 0% 的机会(不会发送)，而 1.0 是 100% 的机会(都将发送)。
此 rate 同样适用于所有 transaction；
换句话说，每个 transaction 都应该有相同的随机机会以 sampled = true 结束，等于 tracesSampleRate。

tracesSampler

这应该是一个 callback，在 transaction 开始时调用，它将被赋予一个 samplingContext 对象，并且应该返回一个介于 0.0 和 1.0 之间的采样率_对于所讨论的 transaction_。
此采样率的行为方式应与上面的 tracesSampleRate 相同，不同之处在于它仅适用于新创建的 transaction，因此可以以不同的 rate 对不同的 transaction 进行采样。
返回 0.0 应该强制删除 transaction(设置为 sampled = false)，返回 1.0 应该强制发送 transaction(设置 sampled = true)。

可选地，tracesSampler callback 也可以返回一个布尔值来强制进行采样决策(false 等同于 0.0，true 等同于 1.0)。
如果返回两种不同的数据类型在实现语言中不是一个选项，则可以安全地省略这种可能性。

maxSpans

由于 transaction payload 在摄取端强制执行最大大小，因此 SDK 应限制附加到事务的 span 数。
这类似于如何限制面包屑和其他任意大小的列表以防止意外误用。
如果在达到最大值后添加新的 span，SDK 应删除 span 并理想地使用内部日志记录来帮助调试。

maxSpans 应该作为一个内部的、不可配置的、默认为 1000 的常量来实现。如果在给定的平台中有理由，它可能会变得可配置。

maxSpans 限制还可以帮助避免永远不会完成的 transaction(在 span 打开时保持 transaction 打开的平台中)，防止 OOM 错误，并通常避免降低应用程序性能。

Event 变更

在撰写本文时，transaction 是作为 Event 模型的扩展实现的。

Transaction 的显着特征是 type: "transaction"。

除此之外，Event 获得了新的字段：spans、contexts.TraceContext。

新的 Span 和 Transaction 类

在内存中，span 构建了一个定时操作的概念树(conceptual tree)。
我们称整个 span tree 为 transaction。
有时我们使用术语 "transaction" 来指代作为整棵树的 span tree，有时特指树的 root span。

通过网络，transaction 被序列化为 JSON 作为增强的 Event，并作为 envelope 发送。
不同的 envelope 类型用于优化摄取(因此我们可以以不同于其他事件的方式路由 “transaction events”，主要是 “error events”)。

在 Sentry UI 中，您可以使用 Discover 查看所有类型的事件，并使用 Issues 和 Performance 部分分别深入研究 errors 和 transactions。面向用户的跟踪文档解释了更多产品级别的概念。

• https://docs.sentry.io/product/performance/distributed-tracing/#traces-transactions-and-spans

Span 类将每个单独的 span 存储在 trace 中。

Transaction 类就像一个 span，有几个主要区别：

• Transaction 有 name，span 没有。
• 在 span 上调用 finish 方法会记录 span 的结束时间戳。对于 transaction，finish 方法另外向 Sentry 发送一个事件。

Transaction 类可能继承自 Span，但这是一个实现细节。
从语义上讲，transaction 既表示 span tree 的 top-level span，也表示向 Sentry 报告的单位。

• Span 接口

  • 创建 Span 时，将 startTimestamp 设置为当前时间
  • SpanContext 是 Span 的属性集合(可以是一个实现细节)。如果可能，SpanContext 应该是不可变的。
  • Span 应该有一个方法 startChild，它使用当前 span 的 id 作为新 span 的 parentSpanId 创建一个新的 span，并将当前 span 的 sampled 值复制到新 span 的 sampled 属性
  • startChild 方法应遵守 maxSpans 限制，一旦达到限制，SDK 不应为给定的 transaction 创建新的子 span。
  • Span 应该有一个名为 toSentryTrace 的方法，它返回一个字符串，该字符串可以作为名为 sentry-trace 的 header 发送。
  • Span 应该有一个名为 iterHeaders(适应平台的命名约定)的方法，它返回一个可迭代的或 header 名称和值的映射。这是一个包含 return {"sentry-trace": toSentryTrace()} 的薄 wrapper。 请参阅 continueFromHeaders 以了解为什么存在这种情况，并且在编写集成(integration)时应该首选。

• Transaction 接口

  • 一个 Transaction 内部包含一个子 Span 的平面列表(不是树结构)
  • Transaction 还有一个 setName 方法来设置 transaction 的名称
  • Transaction 在创建时收到一个 TransactionContext(新属性与 SpanContext 是 name)
  • 由于 Transaction 继承了 Span，因此它具有所有 Span 可用的函数并且可以像 Span 一样进行交互
  • 一个 transaction 要么被采样(sampled = true)，要么被取消采样(sampled = false)，一个在 transaction 的生命周期中被继承或设置一次的决定，并且在任何一种情况下都会传播给所有的 children。不应将未抽样的 transaction 发送给 Sentry。
  • TransactionContext 应该有一个叫做 fromSentryTrace 的 static/ctor 方法，它用从 sentry-trace header<