Span Attributes 别当日志垃圾桶:基数、隐私与语义约定

Span Attributes 别当日志垃圾桶:基数、隐私与语义约定

Hello,我是小兔大白糖。 Trace 通了,排障仍要问「哪个用户、哪笔业务」。同事往 span 上狂打订单号、手机号、整段 JSON——Grafana / 后端一卡,账单涨,合规来问。Attributes(属性,span 上的键值维度)到底该怎么挂?

写成这篇,给要做 OpenTelemetry span attributes 业界调研 的初中级后端同学:不是某仓库落地清单,而是可复述的挂载心智模型。

说明:文中的键名、伪流程与对比表均为教学脱敏 / 示意。语义约定(Semantic Conventions,下文简称 semconv)键名以当前官方文档为准,勿死记旧键。读完带走的是选型与治理清单,不是可粘贴的内部实现。

估计阅读时间:10 分钟


目录


为什么现在要关心

硬规则一:Attributes 是给「查得着、可聚合」用的维度,不是日志垃圾桶——高基数(cardinality,近似「可能出现的不同值数量」;订单号级无限值)会打爆索引与账单。

链路刚打通时,团队最容易犯两种对称错误:

你看到的现象常见真相
按用户 / 订单筛不到 trace没挂稳定身份或业务枚举;只剩难聚合的自由文本
看板卡死、存储与账单暴涨把 UUID、裸 URL+query、整段 body 当 attribute
合规问「谁把手机号打进遥测了」把 PII(可识别个人身份的信息)明文铺进每条 span
现成 HTTP / DB 仪表盘对不上忽略官方 semconv,另起一套自定义键

同站可观测相关可对照:Context 要传不要存见 /blog/go_context_pass_not_store/。本文只钉一件事:Attributes 挂什么、挂在哪、以及高基数与隐私的边界。


问题空间:查得着 vs 打爆索引

硬规则二:身份类字段先过隐私合同——能关联到真人的 ID,默认当敏感;优先稳定低基数标签 + 受控关联,不要把 PII 明文铺进每条 span。

OpenTelemetry 公开模型里:一条 Trace 由多个 Span 组成;Attributes 是挂在 span(或资源)上的键值维度。另有 Events(时间线上的事件)、Status(成功 / 错误语义)。自定义字段 = 在约定命名空间上扩展,不是发明第二套遥测。

需求错误做法常见真相
按用户筛 trace每条 span 塞邮箱 / 手机高基数 + PII
标业务步骤自由字符串墙无法聚合;无语义约定
库 / HTTP 细节只打自定义、忽略约定键与现成仪表盘对不上
Attributes 服务检索与聚合;高基数细节应走日志或 exemplar,而非每条 span 的属性索引
Attributes 服务检索与聚合;高基数细节应走日志或 exemplar,而非每条 span 的属性索引 · 点击查看 SVG 原图

业界常见做法对比

领先路径常见是:先对齐 semconv → 业务用稳定前缀枚举 → 入口注入低基数身份;不是一上来把排障字段全塞进 attribute。

做法优点代价 / 边界
优先 Semantic Conventionshttp.* / db.* 以及身份类约定键可对齐生态仪表盘(键名以当前官方 semconv 为准)要查现行文档;旧教程键可能已更名
业务属性用稳定前缀 + 枚举如 app.order_state=paid(有限状态)要治理字典;禁止无限自由文本当维度
入口注入低基数身份上下文鉴权后统一挂内部用户 ID 一类字段(一次)ID 仍可能敏感;要采样、访问控制与保留策略
高基数进日志 / exemplar保住排障细节,不炸属性索引两套查询路径;团队要会「trace ↔ 日志」关联

代价先说清:挂得越多,检索越好看——同时存储、索引基数与合规面一起变实。Attributes 不是万能存储。


心智模型:运单栏目,不是整箱明细

主比喻:快递运单。

  • Span = 一张运单(这次调用做了什么)。
  • Attributes = 运单上的标准栏目(目的地省市区、签收状态)+ 少量业务戳(易碎、到付)。
  • 整箱发货明细 = 日志 / 附件——别贴在运单正面。
心智模型:Span Attributes 如运单标准栏目;高基数明细如整箱发货清单应走日志而非贴满运单
心智模型:Span Attributes 如运单标准栏目;高基数明细如整箱发货清单应走日志而非贴满运单 · 点击查看 SVG 原图

类比局限一句说清:运单解释「基数与可读性」;解释不了具体后端(Tempo / Jaeger / 商业 APM)的属性索引限额与计费模型——那是产品合同,不是 OTel 语义本身。


该挂 / 不该挂

宜挂低 / 中基数、可聚合的标签;慎挂 / 勿挂无限值与 PII 明文。

宜挂(低 / 中基数)慎挂 / 勿挂
操作类型枚举、结果码、租户 / 环境邮箱、手机、身份证、地址明文
资源类型、HTTP 路由模板(非裸 URL + query)每次不同的 UUID 当「唯一筛选维度」却无上限与关联策略
内部用户 ID(若合规允许)整段 request / response body
归一化后的错误类型未截断的堆栈整段当 attribute 值

身份相关:公开约定里常见 enduser.id / user.id 一类概念——优先内部不可逆标识或内部主键,并配合采集管道脱敏与保留策略。具体键名与是否推荐以当前官方 semconv 为准;下文伪代码里的键仅为教学示意。


挂在哪一层

入口一次写身份上下文;业务 span 挂枚举状态;出站 / DB 优先官方 instrumentation,少手写重复约定键。

常见三层(教学分法,非产品强制):

  1. 入口中间件 / 过滤器:鉴权后写身份 / 会话等低基数上下文(一次,向下传播)。
  2. 业务 span:关键用例 StartSpan,挂业务枚举状态(如结账步骤)。
  3. 出站 HTTP / DB 客户端:尽量用官方或社区 instrumentation,自动带上约定的 http.* / db.*(以当前官方 semconv 为准)。
挂载三层:入口注入低基数身份;业务 span 挂枚举;出站与 DB 优先官方 instrumentation
挂载三层:入口注入低基数身份;业务 span 挂枚举;出站与 DB 优先官方 instrumentation · 点击查看 SVG 原图

教学伪流程

先入口注入稳定身份,再在业务边界挂枚举——不要把自由文本与 body 当 attribute。

on_request:
  span = current_span(ctx)
  set_attr(span, "user.id", internal_id)       # 合规允许时;键名以现行 semconv 为准
  set_attr(span, "session.id", session_id)     # 注意基数与保留策略

on_business_step(ctx, step_enum):
  ctx, span = start_span(ctx, "checkout." + step_enum)
  set_attr(span, "app.checkout.step", step_enum)  # 枚举,非自由句
  ...
  end(span)

以上为教学示意(十余行),非某语言 SDK 抄录。user.id / session.id / app.* 仅示意命名空间分工;上线前请对照当前官方 semconv 与你们的隐私合同。


常见坑

从架构视角看,下面几条会把 Tracing 后端重新用成「带索引的日志库」。

  1. 高基数当 attribute
    订单号、请求 UUID、带 query 的完整 URL 全进属性索引 → 后端爆炸或账单失控。

  2. PII 明文进 attribute
    手机号、邮箱、地址进每条 span;合规与访问控制一起炸。默认当敏感,先过合同。

  3. 忽略语义约定
    自造 my_http_code 一类键,现成仪表盘与告警规则全部对不上;后人还要维护翻译层。

  4. 每个函数新建 span、无业务边界
    噪声淹没信号;检索成本上升,却答不出「这笔结账卡在哪一步」。

  5. 用 attribute 代替结构化日志与指标
    Attributes 擅长维度检索与聚合;长文本、高频计数、无限基数明细仍应走日志 / metrics / exemplar。

  6. 只挂自定义、关掉官方 instrumentation
    为「统一风格」手写一套 HTTP / DB 字段,往往比官方约定更难对齐生态。


选型结论

  1. Attributes 服务检索与聚合:守基数与隐私;别当日志垃圾桶。
  2. 先约定、再业务前缀枚举:semconv 对齐生态;业务用稳定字典,禁止自由句墙。
  3. 入口注入低基数身份:一次写清;ID 仍可能敏感,配采样与保留。
  4. 高基数细节走日志 / exemplar:接受两套查询路径,换索引与账单可控。
  5. OTel 不当万能存储:Events / Status / Metrics / Logs 各有合同;挂错层只会换一种事故形态。

键名与推荐字段会随官方 semconv 演进——选型结论钉的是基数、隐私、分层挂载,不是某一版键名快照。