Runtime Tracing

定位

本文件定义 runtime 内部 Agent Tracer 的逻辑 API，不绑定具体语言签名或 transport。

TypeScript、Python 或其他 runtime 实现 MAY 暴露不同语法糖，但外部语义必须收敛到同一套 tracing 能力。

逻辑对象

• StartSpanOptions
  • 见 schemas/common/tracing.json#/$defs/StartSpanOptions
• TraceContext
  • 见 schemas/common/tracing.json#/$defs/TraceContext
• PropagationCarrier
  • 见 schemas/common/otel.json#/$defs/PropagationCarrier
• AgentSpan
  • 见 schemas/resources/agent-span.json
• TraceEvent
  • 见 schemas/resources/trace-event.json
• TraceSummary
  • 见 schemas/resources/trace-summary.json
• TracerConfig
  • 见 schemas/common/tracing.json#/$defs/TracerConfig
• GenAIObservation
  • 见 schemas/common/otel.json#/$defs/GenAIObservation

标准能力面

• startSpan(options) -> SpanController
  • 创建一个需要手动结束的 running span
• wrap(options, fn) -> T | Promise<T>
  • 自动开始、执行并结束 span
• wrapChild(options, fn) -> T | Promise<T>
  • 复用当前上下文，明确表达创建子 span 的意图
• wrapDetached(options, fn) -> T | Promise<T>
  • 复用当前 trace，但不写入 parentSpanId
• endSpan(spanId, status, error?) -> AgentSpan | null
  • 通过 span 标识手动结束一个活动 span
• getTraceContext() -> TraceContext | null
  • 获取当前上下文中的最小 trace 传播信息
• injectContext(carrier, format?) -> PropagationCarrier
  • 将当前上下文注入 header、text-map 或 environment carrier
• extractContext(carrier, format?) -> TraceContext | null
  • 从外部 carrier 解析 trace 上下文
• withContext(context, fn) -> T | Promise<T>
  • 在指定远端或显式上下文下执行回调
• injectToLogger() -> void
  • 安装 trace 到日志格式化器或 logger context 的注入器
• recordEvent(spanId, event) -> TraceEvent | null
  • 为某个活动 span 追加结构化事件
• recordGenAI(spanId, details) -> TraceEvent | null
  • 记录 LLM / GenAI 输入输出详情，默认映射到 gen_ai.client.inference.operation.details
• destroy(errorMessage?) -> void
  • 释放 tracer，并结束保留中的内部 span 或缓冲导出器

SpanController 合约

• spanId
• rootSpanId
• getSpan()
• setSpanType(spanType)
• setMetadata(partialMetadata)
• setAttributes(partialAttributes)
• addEvent(name, attributes?, payload?)
• recordGenAIDetails(details)
• end(status, error?)

实现 MAY 提供更多 helper，但不得削弱上述标准能力。

语义要求

• wrap MUST 在回调成功时结束为 success，抛错时结束为 failed
• wrapChild 在没有活动上下文时 SHOULD 报错或显式降级为 wrap，实现必须固定一种行为并可测试
• wrapDetached MUST NOT 继承 parentSpanId，但 SHOULD 保留 traceId 与 rootSpanId
• endSpan 对未知或已结束 span MUST 返回空值或 no-op，不得重复导出
• getTraceContext 返回值 MUST 至少包含 traceId 和 spanId
• injectContext / extractContext SHOULD 默认兼容 traceparent、tracestate 和 baggage
• withContext MUST 在回调期内让 wrap / startSpan 看到新的父上下文
• recordEvent MUST 记录到当前 span 或指定 span，不得生成脱离 trace 的孤儿事件
• recordGenAI MAY 将摘要投影到 span attributes，将大内容体投影到 span events 或外部 blob

语言绑定

• TypeScript MAY 暴露位置参数简写：
  • startSpan(spanName, extra)
  • wrap(spanName, fn, extra)
• Python MAY 暴露异步别名：
  • awrap
  • awrap_child
  • awrap_detached

这些差异属于语言层绑定，不影响逻辑契约。

日志注入

• injectToLogger SHOULD 注入：
  • traceId
  • spanId
  • rootSpanId
  • runId
• logger 注入 MUST 是只增不改的上下文增强，不得破坏调用方原有日志字段

GenAI 语义

• LLM / agent 调用 SHOULD 使用 spanKind=client 或等价语义来表达对远端模型服务的调用
• 对于 prompt、message、tool call、tool result、completion、usage 等详情，平台 SHOULD 提供两层表达：
  • 轻量摘要放在 otel.attributes / genAI
  • 大内容体放在 TraceEvent.payload
• recordGenAI 产生的事件名默认是 gen_ai.client.inference.operation.details
• 平台 MUST 支持 contentCaptureMode，以便在 none、redacted、span_attributes、span_events、external_blob 之间治理内容落点

Context Propagation

• runtime SHOULD 同时支持：
  • HTTP header carrier
  • 通用 text-map carrier
  • 子进程 / shell environment carrier
• baggage MUST 视为受治理的附加上下文，不得默认承载 secret 或大 payload

导出与读面

• runtime 内部 tracer MUST 以 AgentSpan 作为统一逻辑对象
• completed span MUST 通过 trace-export.asyncapi.yaml 描述的稳定协议导出
• span event 与 GenAI operation details MUST 能通过同一 trace export 协议导出
• 读面 trace 与 span 查询 MUST 与导出协议共享同一份 schema

实现绑定提示

• 不同语言绑定 MAY 在同步 / 异步命名、参数顺序和 helper API 上存在差异，但不得改变逻辑契约。
• 实现 MAY 引入内部 housekeeping span、vendor span 或 adapter 事件；对外稳定接口必须仍以本规范 schema 为准。
• 如果 exporter 先产出 vendor-specific 或 runtime-specific 事件形状，MUST 在进入平台 trace plane 前归一化为稳定契约。