手动埋点是什么
自动埋点覆盖的是框架层（HTTP 请求、数据库调用、消息收发），业务语义（下单、扣库存、对账）必须手动补：显式起一个命名清晰的 span、设置业务属性、标记成功或失败状态，并在异常时记录异常对象。只有补上这一层，链路才不只是「调了哪些接口」，而是「业务发生了什么」。
基本信息
| 核心 API | tracer.start_as_current_span(name) |
|---|---|
| 命名习惯 | 动作 + 对象（order.create） |
| 属性 | span.set_attribute(key, value) |
| 状态 | span.set_status(StatusCode.ERROR, desc) |
| 异常 | span.record_exception(e) |
| 命名要求 | 低基数，避免拼入 ID |
典型使用场景
- 给关键业务动作（下单、支付、发券）补 span，便于按业务维度分析耗时
- 在异常分支标记状态并记录异常，让错误请求在链路里一眼可见
- 为外部依赖调用（下游 HTTP、第三方支付）补 span，区分自身与外部耗时
- 给 span 附上业务属性（渠道、商品类型），支持按维度筛选
- 定位「总耗时长但框架 span 都很短」的间隙到底花在哪
- 排查跨服务问题时，用带业务语义的 span 名替代模糊的「调用了接口」
Python 手动埋点
Python 手动埋点
tracer = trace.get_tracer("orders")
with tracer.start_as_current_span("order.create") as span:
span.set_attribute("order.type", "flash_sale") # 业务属性
try:
order_id = create_order(req)
span.set_attribute("order.result", "created")
except StockOut as e:
span.set_status(Status(StatusCode.ERROR, "stock out"))
span.record_exception(e) # 记录异常对象
raise常用操作
| 操作 | 方法 | 用途 |
|---|---|---|
| 起 span | start_as_current_span | 创建并挂到当前上下文 |
| 加属性 | set_attribute | 补充业务维度 |
| 标状态 | set_status | 区分成功与失败 |
| 记异常 | record_exception | 保留异常类型与堆栈 |
| 加事件 | add_event | 标记关键时间点 |
手动 span 命名用「动作 + 对象」（order.create、stock.hold），保持低基数便于聚合；把订单号拼进 span 名会让统计失去意义。
属性与 span 名的取舍：命名要低基数，取值多样的信息放进属性，这样既能聚合又保留明细。
异常要同时 set_status 与 record_exception：只设状态会丢失异常信息，只记异常则状态仍显示成功。
手动 span 应包裹真正有意义的业务边界，而不是每行代码都加一个，过细的粒度会让链路图难以阅读。