Span Lifecycle

标准状态

• running
• success
• failed
• cancelled
• timeout

合法转移

• running -> success
• running -> failed
• running -> cancelled
• running -> timeout

规则

• startSpan MUST 创建一个 running span，并立刻固定 traceId、spanId、rootSpanId 和 startTime
• span 的第一个终态写入 MUST 胜出，后续重复 end MUST 是幂等 no-op
• timeout 是平台或 tracer 主动施加的终态，语义上不同于业务主动 failed
• 终态 span MUST 具备 endTime 与 durationMs
• 终态 span SHOULD 同时携带终态时刻的 metrics 快照

触发源

• runtime 用户代码
  • 手动 end('success' | 'failed' | 'cancelled')
• tracer 包装器
  • wrap / wrapChild / wrapDetached 自动结束
• timeout 调度器
  • 到期强制结束为 timeout
• runtime 销毁或异常清理
  • destroy(errorMessage?) 导致保底终止

导出规则

• span 进入终态后 MUST 最多导出一次稳定 completed event
• span 生命周期中的 TraceEvent MAY 在运行中追加，也 MAY 在 exporter flush 时批量发出
• 导出失败时允许重试，但重试 MUST 以 traceId + spanId 去重
• 读面投影 MUST NOT 因重复 completed event 产生多个 span 版本
• span event 导出失败时，去重键 SHOULD 至少包含 traceId + spanId + eventId
• gen_ai.client.inference.operation.details 等大 payload 事件 MAY 独立于 completed span 导出

约束

• parentSpanId 如果存在，MUST 指向同一 trace 中的合法祖先或当前上下文父 span
• spanId MUST 在 trace 内唯一
• rootSpanId MUST 在同一 trace 内保持稳定，不得在 span 生命周期中被重写