[Feat] Add OpenTelemetry tracing for RL rollout workflows

[YanhuiDua]

概述

这个 PR 为 XTuner RL rollout 增加 tracing 能力，并通过 xtuner.v1.rl.trace 提供 XTuner 级别的 trace API。

用户不需要直接依赖 OpenTelemetry SDK，也不需要关心 collector、exporter、Ray runtime env 等实现细节；只需要在 RL config 中开启 trace，并在自定义业务路径中使用 XTuner 提供的 trace API，即可把 controller、worker、
agent loop、judger、infer backend、session server 等路径上的执行信息串到同一条 trace 中。

这套能力主要用于排查 rollout 慢、失败、断链、异常传播和跨进程调用耗时问题。

使用方式

开启 trace

在 RL config 中配置 TraceConfig：

from xtuner.v1.rl.trace import TraceConfig

trace_config = TraceConfig(
    enabled=True,
    output_dir="work_dirs/trace",
    service_name="xtuner-rollout",
    viewer_enabled=True,
)

Trace API

公共接口统一从 xtuner.v1.rl.trace 暴露。API 分为三层：basic API、XTuner endpoint API、context propagation API。

Basic API

Basic API 是 XTuner 封装的 trace primitive，适合普通本地阶段、临时埋点、自定义业务代码和手动 context 管理。

API	作用
trace_span(name, attributes=None, parent_carrier=None)	创建当前 span
trace_function(name=None, attributes=None)	给同步或异步函数包一层 span
trace_event(name, attributes=None)	在当前 span 上记录 event
set_trace_attribute(key, value)	写单个 attribute
set_trace_attributes(attributes)	批量写 attributes
inject_trace_context(carrier=None)	把当前 context 写入 carrier
extract_trace_context(carrier)	从 carrier 取出 TraceContext
attach_trace_context(context)	在当前 scope 激活 TraceContext

示例：

from xtuner.v1.rl.trace import trace_span, trace_event, set_trace_attributes

with trace_span("agent.localhost.infer.run", attributes={"xtuner.task_name": task_name}):
    result = await infer_engine.generate(request)
    set_trace_attributes({"xtuner.status": "ok"})
    trace_event("infer.finished", {"num_tokens": result.num_tokens})

Trace SKILL

本PR新增SKILL: .claude/skills/xtuner-trace/
使用示例如下：

Use $xtuner-trace to add trace observation for session_server read_response latency.
Use $xtuner-trace to review whether this Ray rollout call propagates trace context correctly.
Use $xtuner-trace to instrument localhost agent validate stage.

Viewer使用方式

XTuner 提供面向 rollout 的 trace viewer。它不是新的 trace 后端，而是把 Jaeger 或本地 trace JSONL 中的原始 spans 按 rollout 语义聚合成样本视图。

训练启动后会有类似的日志：

[XTuner][2026-07-08 07:35:10][INFO] XTuner trace viewer enabled: url=http://0.0.0.0:18080, host=0.0.0.0, port=18080. Restart with: python -m xtuner.tools.trace_viewer.server --trace-jsonl work_dirs/qwen3vl_35b_grpo_mixdata/otel/20260708-073509-409337-5a14f69c/traces/traces.jsonl --live-jsonl work_dirs/qwen3vl_35b_grpo_mixdata/otel/20260708-073509-409337-5a14f69c/traces/live.jsonl --service xtuner-rollout --run-id 20260708-073509-409337-5a14f69c --host 0.0.0.0 --port 18080 --jaeger-query-url http://127.0.0.1:16686

`
sample状态总览：提供每个阶段的平均耗时、有哪些sample卡在了什么阶段等信息

每条sample调用链

后续计划

• 对比不开trace的性能
• 支持黑盒Agent 细粒度观测（恢复出来LLM generate， tool call的调用链）
• 观测RL训练全部阶段
• 增加对Rollout轨迹的观测

[YanhuiDua]

@claude review