用途
ai-python-telemetry 用于为 AI SDK for Python 添加遥测、追踪或 OpenTelemetry 导出，也适用于从持久化（durable）或 Serverless 执行中上报 span。该模块位于 ai.experimental_telemetry，属于实验性功能，可能变更或被移除。
主要能力
启用遥测
在注册适配器或路由到 sink 之前，不会报告任何内容。遥测关闭时，span 为空操作（id=""，不读取时钟，push() 不执行任何操作）。可通过 is_enabled() 检查状态。
OpenTelemetry 导出
执行标准的 OpenTelemetry 流程（tracer provider + OTLP exporter），然后调用 ai.experimental_telemetry.register(otel.OtelAdapter())。需要 ai[otel] 额外依赖。
消息内容捕获为可选开启：otel.OtelAdapter(capture_content=True) 或设置环境变量 OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true。
在检查点之前调用 OtelAdapter.flush()，在进程退出时调用 OtelAdapter.shutdown()；exporter 会进行缓冲。
框架 span
框架会自动打开 span：RunSpanData、LoopTurnSpanData、AiStreamSpanData、AiGenerateSpanData、ToolExecutionSpanData、HookSpanData。
在适配器中根据 span.data 的类型进行分发；span 事件包括 FIRST_TOKEN、RESPONSE_COMPLETE、HOOK_DEFERRED、HOOK_RESOLVED、HOOK_CANCELLED。
用户 span
使用 async with span("name") as sp: 会自动打时间戳、推送、嵌套并记录异常。
sp.set_attrs(...) 用于设置属性；sp.add_event(name) 用于记录里程碑。
类型化 span：任何带有 kind 字段的 Pydantic 模型都是 SpanData；使用 span(MyData(...)) 打开，并直接赋值 sp.data 字段。
自定义适配器
协议：on_span_start / on_span_event / on_span_end（均为必需），通过 register() 注册——否则会抛出 TypeError。失败会被记录并跳过。
推荐使用 @adapter 装饰器构建厂商桥接：每个 span 一个异步生成器，循环 yield 直到 None，然后读取 span.data / span.error。也可用于 call 为异步生成器方法的类，以支持带配置或状态的适配器。
可继承 OtelAdapter 并重写 span_name() / span_attrs() 来调整 OpenTelemetry 输出。
持久化与 Serverless 执行
在工作流主体内，将 span 路由到 sink 而不是适配器，并将投递保留在步骤中；在安装确定性时钟和随机数后，agent 运行和 span() 上下文管理器可在主体内工作。对于跨进程边界的 span，使用低层 API。
在主体内收集：sink = DictSink()，在 async with use_sink(sink): 下运行，然后使用 model_dump(mode="json") 序列化 sink.finished_spans。
从步骤投递：await push_all(payload)。
手动生命周期：create_span() 然后 stamp_start() / stamp_end() / push()；除非推送，否则不会报告任何内容。
跨进程继续 trace：使用 Span.model_validate(...) 恢复，通过 async with use_span(restored): 或 span(..., parent=restored) 将其作为父级。
确定性时间戳：use_time(workflow.time_ns)；使用 now_ns() 读取环境时钟。
use_sink、use_span 和 use_time 是异步上下文管理器；它们也可作为异步函数的装饰器，但不能与普通 with 一起使用。
错误序列化为 SpanError（SpanError.from_exception(exc)），因此在另一个进程中失败的 span 仍可上报。
使用方式
安装 ai[otel] 额外依赖后，完成 OpenTelemetry 的 tracer provider 与 OTLP exporter 配置，再注册 OtelAdapter。在持久化或 Serverless 场景中，改用 sink 收集并在步骤中投递，或使用低层 API 手动管理 span 生命周期。
适用场景
适用于需要为 AI SDK for Python 添加追踪、遥测或 OpenTelemetry 导出的场景，以及需要在持久化工作流或 Serverless 函数中上报 span、跨进程继续 trace 的场景。
限制
ai.experimental_telemetry 为实验性功能，可能变更或被移除。默认不报告任何数据，必须注册适配器或路由到 sink。消息内容捕获默认关闭，需显式开启。OpenTelemetry 导出需要 ai[otel] 额外依赖。use_sink、use_span、use_time 不能与普通 with 一起使用。