Tracing

角色

Tracing 表示 runtime、agent、tool、LLM 调用和后台任务的因果执行视图，是运行态可观测性的标准对象模型。

核心对象

• TraceContext
  • 进程内或跨边界传播的最小上下文，至少包含 traceId 与当前 spanId
• PropagationCarrier
  • traceparent、tracestate、baggage 等跨进程 carrier
• AgentSpan
  • 一次可观测执行片段，记录身份、语义、时间、状态、错误与资源指标
• TraceEvent
  • 归属于某个 span 的细粒度事件，可表达 OTel-style 事件、LLM 输入输出详情和外部引用
• TraceSummary
  • 由 span 聚合出的读模型，用于 run 级 trace 列表、筛选与概览
• TracerConfig
  • tracer 的超时、导出、日志注入、指标采样和 metadata 治理配置
• GenAIObservation
  • 面向 LLM / agent 调用的结构化语义投影，承载输入消息、输出消息、tool context、usage 和 provider 属性

拓扑要求

• 一个 AgentSpan MUST 只属于一个 traceId
• 一个 Trace MUST 只属于一个 runId
• 一个 run MAY 拥有多个 trace
• rootSpanId 表示当前 trace 的主根 span 标识
• parentSpanId 表示直接父 span；为空不代表 span 不属于当前 trace
• wrapDetached 产生的 span MAY 清空 parentSpanId，但 SHOULD 保留原 traceId 和 rootSpanId
• 因此 trace 的逻辑结构是有主根的因果图，而不是严格要求单棵树
• span MAY 挂载 links，用于表达 batch、fan-in、消息队列或 remote parent 等非树形关系

互操作要求

• 稳定 tracing 模型 MUST 支持：
  • OTel-style spanKind
  • attributes / links / events
  • W3C Trace Context 兼容 carrier
  • W3C Baggage 兼容 carrier
• TraceContext SHOULD 同时保留解析后的 traceId / spanId 和序列化后的 carrier 视图
• genAI 结构化对象 SHOULD 能无损映射到 otel.attributes 与 TraceEvent
• 对于体量较大的 LLM 输入输出，平台 SHOULD 优先使用 TraceEvent 或外部 blob 引用，而不是无条件塞入 span 顶层属性

聚合要求

• TraceSummary MUST 可由 span 事实流增量投影得到
• TraceSummary.status MUST 由 span 集合推导，而不是由单独手工写入
• 推荐推导顺序：
  • 只要存在未终止 span，则 trace 为 running
  • 否则只要存在 timeout span，则 trace 为 timeout
  • 否则只要存在 failed span，则 trace 为 failed
  • 否则只要存在 cancelled span，则 trace 为 cancelled
  • 否则如果 span 集合不完整或存在缺口，则 trace 为 partial
  • 其他情况为 success

关联要求

• span MUST 可关联到 orgId、agentId、runId 和 runSpaceId
• span SHOULD 允许关联 contextId
• 日志、artifact、checkpoint、消息事件 SHOULD 能通过 traceId 或 spanId 与 tracing 读模型关联
• logger 注入 SHOULD 至少携带 traceId 与 spanId
• 对于 LLM span，读模型 SHOULD 允许关联：
  • conversationId
  • 输入 / 输出 message 序列
  • tool call / tool result
  • usage / token accounting

数据治理

• metadata MAY 存放业务标签、模型名、参数摘要和输入统计
• metadata MUST NOT 默认包含 secret、token、明文凭证或原始用户敏感输入
• GenAIObservation 与 TraceEvent.payload 中的原始 prompt / completion 内容 MUST 受 capture mode 控制
• 默认 capture mode SHOULD 是 none 或 redacted
• 如使用 external_blob，读面 MUST 返回受控引用，而不是无权限公开原始内容
• 系统生成的 housekeeping span MAY 存在；如暴露给读面，SHOULD 可被过滤或默认隐藏

平台要求

• Tracing 是平台级能力，MUST NOT 只作为某个 SDK 的私有调试工具存在
• runtime 本地 API、trace export 和 trace query MUST 指向同一份稳定模型
• 如果 tracer、vendor SDK 或 exporter 先产出内部事件，再接入统一 trace ingest，MUST 通过适配层收敛到稳定 schema
• 平台 SHOULD 同时提供：
  • 平台原生结构化字段
  • OTel-compatible projection
  • 受治理的 LLM 内容捕获能力