feat: 新增宿主接入 trace 的工具并把 trace_id 随会话内容入库 --story=136129662

[Vellun7]

背景

TAPD #136129662：会话记录里没有任何指向实际执行链路的线索，排障只能靠时间戳和 session_code 去 APM 上翻。

根因 / 现状：

• ChatSessionContent 只有 turn_id（标识一轮 user-ai 对话），缺一个标识这轮实际调用链的 id，从一条会话记录跳不到 APM。
• BkAidevAgentInstrumentor 刻意不把自己的 TracerProvider 注册为全局（见其 docstring），宿主若自建一个，产出的 span 会落在另一棵树上且无处上报。
• 自己起进程驱动 Agent 的宿主（企微长连接是第一个，Celery worker、常驻消费者同理）没有统一接入点，只能各写各的。

改动

改动一：新增 aidev_agent/utils/tracing.py

• current_trace_id()：读当前 span 的 32 位 hex trace id，无有效 span 返回空串。不像 turn_id 那样逐层透传参数，因为 OTel context 本来就跟着执行走，再铺一条平行参数链只会多出漏传的可能。
• start_request_span()：为一次请求开 root span 并 yield 其 trace id。显式传空 Context() 强制成为 root —— 常驻 worker 线程上可能残留上一次未 detach 的 OTel context（LangChain 回调在生成器被中途丢弃时不保证走到 on_chain_end），继承过去会让不同请求共用同一个 trace id。
• setup_tracing()：装上全局 TracerProvider（优先复用 Agent SDK 的 provider，取不到则 standalone 兜底）并 instrument requests，让出站调用自动带 traceparent。日志里的 provider=agent_sdk|standalone|existing 标明 span 去了哪。
• 整个模块在 otel extras 缺失时降级为空操作：宿主不该因为缺一个观测依赖就起不来，落库这类核心链路更不能被拖垮。

改动二：trace_id 随会话内容入库

• 新增 BaseSessionWriter._stamp_trace_id()，把当前 trace id 盖进 payload.property，与 turn_id 并列；user 输入落库、assistant 内容创建 / 更新、ask-user-question 收尾四条写入路径统一走它。无有效 span 时不写空值。
• aidev_bkplugin 的 SessionManager.create_chat_session_content 同样补上 trace_id。

改动三：新增 get_agent_tracer_provider()

• 暴露 BkAidevAgentInstrumentor 已启动的 provider，供宿主复用同一套 exporter 与 resource。直接读单例属性而不是构造 BkAidevAgentInstrumentor()：BaseInstrumentor.__new__ 返回单例，但 __init__ 仍会重跑并把 _otel_service 抹回 None。

改动四：依赖

• opentelemetry-instrumentation-requests==0.54b1 加入 opentelemetry extras；它与 opentelemetry-sdk 一并加入 dev 组供单测使用。

测试

• src/agent/tests/utils/test_tracing.py（新增）：请求级 trace 隔离、线程 context 污染下仍为 root、provider 选择、出站 traceparent 注入、console exporter。
• src/agent/tests/services/event_handlers/test_session_content_trace_id.py（新增）：创建 / 更新 / user 记录三条路径的 trace_id 落库，以及无 span 时不写 key。
• 回归：src/agent/tests/services/event_handlers 17 passed；src/plugins/aidev_bkplugin/tests/services 87 passed, 1 skipped。

兼容性

• 无 breaking：trace_id 是 property 下的新增 key，无有效 span 时整个 key 不写入，老数据与老调用方不受影响。
• setup_tracing() 是宿主显式调用的可选入口，不调用则现有行为完全不变。
• 前端若要做「从会话记录跳 APM」，后续对接 property.trace_id 即可。

关联

tapd: #136129662

发起人：

• cursoragent
• @Vellun7

Made with Cursor