Rust tracing 技能用于在 litellm-rust 中新增或修改 Rust 诊断追踪,涉及路由 span、subscriber layer 以及向 Python logger 的投递。
用途与总体原则
该技能要求全程使用上游 tracing,包括 #[tracing::instrument]、事件与 span 传播。采集与投递基础设施集中放在 crates/tracing 中。直接使用上游导入仍会到达已配置的 subscriber;重新导出宏并不能控制投递。此路径不要引入 Rust log 或 pyo3-log。
组件职责
litellm-tracing 负责共享 subscriber layer、span 字段采集与诊断处理。适配器应保持可组合,形式为 tracing_subscriber::Layer,由 Logger 提供宿主设置。运行时相关的投递属于宿主桥接层。Python 桥接直接投递到现有 Python SDK logger,保留其 handler、过滤、脱敏与请求关联。crates/tracing 中不要包含 Python 依赖。
宿主与传播
宿主负责配置 subscriber。Python 执行应限定在其捕获的 dispatch 范围内,而不是安装进程级 subscriber。在派生任务与返回的流中同时传播 span 上下文与 dispatch。
核心插桩
在核心中,对原生调用与托管机器共享的执行进行插桩。使用一致的路由、模型、提供方、流式与结果字段。状态记录放在共享提供方边界,而不是把基础日志分散到各 handler 中。上游 HTTP 状态与路由成功状态应保持分离。
字段与敏感信息
使用 skip_all 与显式选择的字段。基础追踪排除请求体、凭据、头部与原始错误字符串。避免自动捕获 ret 或 err 中的敏感值。载荷诊断应单独处理,并受现有脱敏机制约束。
流与 span 生命周期
返回的流在耗尽、出错或丢弃前保留其路由 span,且只有一个终止结果。Builder 构造不会启动 trace。不要在 await 期间持有 span entry guard。诊断追踪与生命周期回调及 CustomLogger dispatch 保持分离。
组合与测试
使用 litellm_tracing::sink_layer 将 sink 与其他 subscriber layer 组合。它会把 span 字段继承到事件中,并发出带耗时信息的 span 关闭摘要。修改此行为时,应测试可观察记录、并发隔离、动态过滤、敏感字段排除以及流取消。
实现细节可参考 tracing API 与 subscriber layer 相关文档。