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

例子：

{ "trace_id": "771a43a4192642f0b136d5159a501700", "public_key": "49d0f7386ad645858ae85020e393bef3", "release": "myapp@1.1.2", "environment": "production", "user": { "id": "7efa4978da177713df088f846f8c484d", "segment": "vip" }, "transaction": "/api/0/project_details" } Envelope Headers(信封头)

当通过 Envelope 向 Sentry 发送 transaction 事件时，必须在 trace 字段下的 envelope header 中设置 trace 信息。

这是一个包含 trace context 的最小 envelope header 的示例（尽管 header 不包含换行符，但在下面的示例中添加了换行符以提高可读性）：

{ "event_id": "12c2d058d58442709aa2eca08bf20986", "trace": { "trace_id": "771a43a4192642f0b136d5159a501700", "public_key": "49d0f7386ad645858ae85020e393bef3" // other trace attributes } } Tracestate Headers(跟踪状态头)

将跟踪上下文传播到其他 SDK 时，Sentry 使用 。有关如何将这些 header 传播到其他 SDK 的更多信息，请参阅 "Trace Propagation"。

Tracestate header 包含几个特定于供应商的不透明数据。根据 HTTP 规范，这些多个 header 值可以通过两种方式给出，通常由 HTTP 库和开箱即用的框架支持：

用逗号连接：tracestate: sentry=<data>,other=<data>

重复：tracestate: sentry=<data> tracestate: other=<data>

要创建 tracestate header 的内容：

将完整的 trace context 序列化为 JSON，包括 trace_id。

如果字符串在平台上的表示方式不同，则将生成的 JSON 字符串编码为 UTF-8。

使用 base64 对 UTF-8 字符串进行编码。

去除尾随填充字符 (=)，因为这是一个保留字符。

在前面加上 "sentry="，导致 "sentry=<base64>"。

如上所述加入 header。

通过去除尾随填充，默认的 base64 解析器可能会检测到不完整的 payload。选择允许丢失 = 或允许截断 payload 的解析模式。

例如：

{ "trace_id": "771a43a4192642f0b136d5159a501700", "public_key": "49d0f7386ad645858ae85020e393bef3", "release": "1.1.22", "environment": "dev", "user": { "segment": "vip", "id": "7efa4978da177713df088f846f8c484d" } }

将编码为

ewogICJ0cmFjZV9pZCI6ICI3NzFhNDNhNDE5MjY0MmYwYjEzNmQ1MTU5YTUwMTcwMCIsCiAgInB1YmxpY19rZXkiOiAiNDlkMGY3Mzg2YWQ2NDU4NThhZTg1MDIwZTM5M2JlZjMiLAogICJyZWxlYXNlIjogIjEuMS4yMiIsCiAgImVudmlyb25tZW50IjogImRldiIsCiAgInVzZXIiOiB7CiAgICAic2VnbWVudCI6ICJ2aXAiLAogICAgImlkIjogIjdlZmE0OTc4ZGExNzc3MTNkZjA4OGY4NDZmOGM0ODRkIgogIH0KfQ

并导致 header

tracestate: sentry=ewogIC...IH0KfQ,other=[omitted]

（注意 header 末尾的第三方条目；新的或修改的条目总是添加到左侧，因此我们将 sentry= 值放在那里。另请注意，尽管此处为了清晰起见省略了编码值, 在真正的 header 中，将使用完整的值。）

实施指南

支持此 header 的 SDK 必须：

创建新的 trace context 时使用 scope 信息

为包含 transaction 的 envelope 添加带有 trace context 的 envelope header

将 tracestate HTTP header 添加到传出的 HTTP 请求以进行传播

在适用的情况下拦截对 tracestate HTTP header 的传入 HTTP 请求，并将它们应用到 local trace context

背景

这是性能指南涵盖的 trace ID 传播的扩展。
根据统一 API 跟踪规范，Sentry SDK 通过集成向传出请求添加 HTTP header sentry-trace。
最重要的是，此 header 包含 trace ID，它必须与 transaction event 的 trace id 以及下面的 trace context 的 trace id 匹配。

trace context 应在 中定义的附加 tracestate header 中传播。
请注意，我们必须保持与 W3C 规范的兼容性，而不是专有的 sentry-trace header。
除了 Sentry SDK 放置的内容之外，tracestate header 还包含供应商特定的不透明数据。

Client 选项

虽然 trace context 正在开发中，但它们应该在内部 trace_sampling 布尔值 client 选项后面进行门控。该选项默认为 false，不应在 Sentry 文档中记录。

根据平台命名指南，该选项应该适当地区分大小写：

trace_sampling (snake case)

traceSampling (camel case)

TraceSampling (pascal case)

setTraceSampling (Java-style setters)

添加 Envelope Header

在以下任何一种情况下，SDK 应将 envelope header 添加到传出 envelope 中：

envelope 包含 transaction event。

scope 有一个 transaction 绑定。