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

与 b3 header 不同,sentry-trace header 不应该只包含一个采样决策,没有 traceid 或 spanid 值。有 无论采样决策如何,始终包含 traceid 和 spanid,这样做也简化了实现。

除了在 Sentry 的情况下外,
还有一个原因是下游系统使用 Sentry 捕获 error 事件。可以在那时做出决定,对跟踪进行采样,以便为报告的崩溃提供跟踪数据。

sentry-trace = sampled

这实际上对于代理将其设置为 0 并选择退出跟踪很有用。

Static API 变更

Sentry.startTransaction 函数应该接受两个参数 - 传递给 Transaction 构造函数的 transactionContext 和一个包含要传递给 tracesSampler(如果已定义)的数据的可选的 customSamplingContext 对象。

它创建一个绑定到当前 hub 的 Transaction 并返回实例。
用户与实例交互以创建子 span,因此,必须自己跟踪它。

Hub 变更

引入一个名为 traceHeaders 的方法

此函数返回 header(string)sentry-trace

该值应该是当前在 Scope 上的 Span 的 trace header 字符串

引入一个名为 startTransaction 的方法

采用与 Sentry.startTransaction 相同的两个参数

创建一个新的 Transaction 实例

应按照本文档 \'Sampling\' 部分中更详细的描述实施抽样

修改名为 captureEvent 或 captureTransaction 的方法

不要为 transaction 设置 lastEventId

Scope 变更

Scope 持有对当前 Span 或 Transaction 的引用。

Scope 引入 setSpan

这可以在内部使用,来传递 Span / Transaction,以便集成可以将子项附加到它

在 Scope(旧版)上设置 transaction 属性应该覆盖存储在 Scope 中的 Transaction 的名称,如果有的话。
这样,即使用户无法直接访问 Transaction 的实例,我们也可以让用户选择更改 transaction 名称。

与 beforeSend 和事件处理器的交互

beforeSend 回调是我们认为最重要的特殊 Event Processor。适当的事件处理器通常被认为是内部的。

Transaction 应该通过 beforeSend。但是,它们仍然由事件处理器处理。
这是在将 transaction 作为 event 的当前实现处理的一些灵活性与为 transaction 和 span 的不同生命周期 hook 留出空间之间的折衷。

动机:

面向未来:如果用户依赖 beforeSend 进行 transaction,
这将使最终在不破坏用户代码的情况下实现单个 span 摄取变得复杂。
在撰写本文时,transaction 作为 event 发送,但这被视为实现细节。

API 兼容性:用户拥有他们现有的 beforeSend 实现,只需要处理错误事件。
我们将 transaction 作为一种新型 event 引入。
当用户升级到新的 SDK 版本并开始使用跟踪时,他们的 beforeSend 将开始看到他们的代码不打算处理的新类型。
在 transaction 之前,他们根本不必关心不同的事件类型。
有几种可能的后果:破坏用户应用程序;默默地和无意地放弃 transaction;
transaction 事件以令人惊讶的方式修改。

就可用性而言,beforeSend 不适合删除 transaction,就像删除 error 一样。
Error 是一个时间点事件。当 error 发生时,用户在 beforeSend 中有完整的上下文,
并且可以在它进入 Sentry 之前修改/丢弃事件。对于交易,transaction 是不同的。
创建 transaction,然后将它们打开一段时间,同时创建 child span 并将其附加到它。
同时传出的 HTTP 请求包括当前 transaction 与其他服务的采样决策。
在 span 和 transaction 完成后,将 transaction 放入类似 beforeSend 的钩子中会在跟踪中留下来自其他服务的孤立 transaction。
同样,在此后期将采样决策修改为 "yes" 也会产生不一致的痕迹。

跟踪上下文(实验性)

为了对跟踪进行采样,我们需要沿着调用链传递 trace id 以及做出采样决策所需的信息,即所谓的 跟踪上下文(trace context)。

协议

Trace 信息作为编码的 tracestate header 在 SDK 之间传递,SDK 预计会拦截和传播这些 header。

对于向 sentry 提交的事件,trace context 作为嵌入在 Envelope header 中的 JSON 对象发送,key 为 trace。

跟踪上下文

无论采用何种传输机制,trace context 都是具有以下字段的 JSON 对象:

trace_id (string, required) - UUID V4 编码为不带破折号的十六进制序列(例如771a43a4192642f0b136d5159a501700),它是一个由 32 个十六进制数字组成的序列。这必须与提交的 transaction item 的 trace id 匹配。

public_key (string, required) - 来自 SDK 使用的 DSN 的 Public key。它允许 Sentry 通过基于起始项目解析相同的规则集来对跨多个项目的跟踪进行采样。

release (string, optional) - 客户端选项中指定的版本名称,通常是:package@x.y.z+build。 这应该与 transaction event payload 的 release 属性匹配*

environment - 客户端选项中指定的 environment 名称,例如 staging。 这应该与 transaction event payload 的 environment 属性匹配*

user (object, optional) - 包含以下字段的 scope 的 user context 的子集:

id (string, optional) - 用户上下文的 id 属性。

segment (string, optional) - 用户数据包中的 segment 属性值(如果存在)。将来,该字段可能会被提升为用户上下文的适当属性。

transaction (string, optional) - 在 scope 上设置的 transaction 名称。这应该与 transaction event payload 的 transaction 属性匹配*

内容版权声明:除非注明,否则皆为本站原创文章。

转载注明出处:https://www.heiqu.com/zzyfdf.html