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 细节 | 只打自定义、忽略约定键 | 与现成仪表盘对不上 |
业界常见做法对比
领先路径常见是:先对齐 semconv → 业务用稳定前缀枚举 → 入口注入低基数身份;不是一上来把排障字段全塞进 attribute。
| 做法 | 优点 | 代价 / 边界 |
|---|---|---|
| 优先 Semantic Conventions | http.* / db.* 以及身份类约定键可对齐生态仪表盘(键名以当前官方 semconv 为准) | 要查现行文档;旧教程键可能已更名 |
| 业务属性用稳定前缀 + 枚举 | 如 app.order_state=paid(有限状态) | 要治理字典;禁止无限自由文本当维度 |
| 入口注入低基数身份上下文 | 鉴权后统一挂内部用户 ID 一类字段(一次) | ID 仍可能敏感;要采样、访问控制与保留策略 |
| 高基数进日志 / exemplar | 保住排障细节,不炸属性索引 | 两套查询路径;团队要会「trace ↔ 日志」关联 |
代价先说清:挂得越多,检索越好看——同时存储、索引基数与合规面一起变实。Attributes 不是万能存储。
心智模型:运单栏目,不是整箱明细
主比喻:快递运单。
- Span = 一张运单(这次调用做了什么)。
- Attributes = 运单上的标准栏目(目的地省市区、签收状态)+ 少量业务戳(易碎、到付)。
- 整箱发货明细 = 日志 / 附件——别贴在运单正面。
类比局限一句说清:运单解释「基数与可读性」;解释不了具体后端(Tempo / Jaeger / 商业 APM)的属性索引限额与计费模型——那是产品合同,不是 OTel 语义本身。
该挂 / 不该挂
宜挂低 / 中基数、可聚合的标签;慎挂 / 勿挂无限值与 PII 明文。
| 宜挂(低 / 中基数) | 慎挂 / 勿挂 |
|---|---|
| 操作类型枚举、结果码、租户 / 环境 | 邮箱、手机、身份证、地址明文 |
| 资源类型、HTTP 路由模板(非裸 URL + query) | 每次不同的 UUID 当「唯一筛选维度」却无上限与关联策略 |
| 内部用户 ID(若合规允许) | 整段 request / response body |
| 归一化后的错误类型 | 未截断的堆栈整段当 attribute 值 |
身份相关:公开约定里常见 enduser.id / user.id 一类概念——优先内部不可逆标识或内部主键,并配合采集管道脱敏与保留策略。具体键名与是否推荐以当前官方 semconv 为准;下文伪代码里的键仅为教学示意。
挂在哪一层
入口一次写身份上下文;业务 span 挂枚举状态;出站 / DB 优先官方 instrumentation,少手写重复约定键。
常见三层(教学分法,非产品强制):
- 入口中间件 / 过滤器:鉴权后写身份 / 会话等低基数上下文(一次,向下传播)。
- 业务 span:关键用例
StartSpan,挂业务枚举状态(如结账步骤)。 - 出站 HTTP / DB 客户端:尽量用官方或社区 instrumentation,自动带上约定的
http.*/db.*(以当前官方 semconv 为准)。
教学伪流程
先入口注入稳定身份,再在业务边界挂枚举——不要把自由文本与 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 后端重新用成「带索引的日志库」。
-
高基数当 attribute
订单号、请求 UUID、带 query 的完整 URL 全进属性索引 → 后端爆炸或账单失控。 -
PII 明文进 attribute
手机号、邮箱、地址进每条 span;合规与访问控制一起炸。默认当敏感,先过合同。 -
忽略语义约定
自造my_http_code一类键,现成仪表盘与告警规则全部对不上;后人还要维护翻译层。 -
每个函数新建 span、无业务边界
噪声淹没信号;检索成本上升,却答不出「这笔结账卡在哪一步」。 -
用 attribute 代替结构化日志与指标
Attributes 擅长维度检索与聚合;长文本、高频计数、无限基数明细仍应走日志 / metrics / exemplar。 -
只挂自定义、关掉官方 instrumentation
为「统一风格」手写一套 HTTP / DB 字段,往往比官方约定更难对齐生态。
选型结论
- Attributes 服务检索与聚合:守基数与隐私;别当日志垃圾桶。
- 先约定、再业务前缀枚举:semconv 对齐生态;业务用稳定字典,禁止自由句墙。
- 入口注入低基数身份:一次写清;ID 仍可能敏感,配采样与保留。
- 高基数细节走日志 / exemplar:接受两套查询路径,换索引与账单可控。
- OTel 不当万能存储:Events / Status / Metrics / Logs 各有合同;挂错层只会换一种事故形态。
键名与推荐字段会随官方 semconv 演进——选型结论钉的是基数、隐私、分层挂载,不是某一版键名快照。