Trace、版本与成本:让一次Agent请求可以被解释
拆解trace与span、并行时间轴、模型工具版本、token费用以及敏感信息最小化记录。
用户说“这次比昨天慢,还答错了”,仅有一条最终答案日志无法判断原因。需要知道请求走了哪个模型与提示版本、检索了什么数据版本、调用了哪些工具、哪一步重试,以及时间花在排队、网络还是生成上。可观测性要连接行为与版本,而不是把所有原始内容永久写进日志。
Trace是一次工作,span是其中一段
trace关联一次跨组件操作,span表示一段有开始结束时间的工作。请求根span下可以有检索、权限检查、模型生成与工具执行等子span。父子关系说明调用结构;并行或异步任务还需要上下文传播与适当的关联,不能只靠同一个用户ID猜测归属。
每段记录稳定操作名、状态、错误类型、重试次数、服务与工具版本。模型调用还需要模型标识、提示模板版本、解码配置摘要与token用量;检索需要索引、embedding与文档快照版本。高基数字段如请求ID适合trace检索,通常不直接作为所有指标的标签,以免造成监控系统成本爆炸。
并行时间不能直接相加
本例检索为0到40ms,权限检查为10到50ms,生成50到150ms。各span耗时相加为40+40+100=180ms,但请求墙钟是150ms,因为前两个阶段重叠30ms。时间区间并集为150ms;如果中间有排队空档,并集也可能小于请求总时长。
端到端延迟应从请求生命周期测量,关键路径用于定位瓶颈。跨机器时钟偏移会影响时间轴,应结合单调时钟耗时与同步策略;不能凭子span负耗时断定工具倒退执行。流式服务还需区分首token时间、token间隔和总完成时间。
完整实验:时间并集、字段白名单和假设费用
用Python 3.13执行 python -X utf8 trace_cost.py。时间轴与单价都是显式教学输入,未调用任何付费API,也不是实时价格或延迟测试。
"""固定时间轴与假设单价,验证并行时延和脱敏;不测真实API价格。"""
SPANS=[{'id':'retrieve','parent':'request','start':0,'end':40},
{'id':'policy','parent':'request','start':10,'end':50},
{'id':'generate','parent':'request','start':50,'end':150}]
def union_duration(spans):
intervals=sorted((s['start'],s['end']) for s in spans);total=0;end=None
for start,stop in intervals:
if stop<start:raise ValueError('negative interval')
total+=stop-start if end is None or start>end else max(0,stop-end)
end=stop if end is None else max(end,stop)
return total
def redact(event):return {k:v for k,v in event.items() if k in {'trace_id','model_version','prompt_version','input_tokens','output_tokens','status'}}
if __name__=='__main__':
print('各span耗时之和',sum(s['end']-s['start'] for s in SPANS))
print('时间区间并集',union_duration(SPANS),'请求墙钟',150)
event={'trace_id':'t1','model_version':'demo-v1','prompt_version':'p2','input_tokens':1000,'output_tokens':200,'secret':'不可记录','status':'ok'}
print('允许字段',redact(event))
print('假设每百万输入2输出8的费用',round((1000*2+200*8)/1_000_000,6))实际输出:
各span耗时之和 180
时间区间并集 150 请求墙钟 150
允许字段 {'trace_id': 't1', 'model_version': 'demo-v1', 'prompt_version': 'p2', 'input_tokens': 1000, 'output_tokens': 200, 'status': 'ok'}
假设每百万输入2输出8的费用 0.0036假设每百万输入token单价2、输出8,1000输入加200输出费用为(1000×2+200×8)/一百万=0.0036。生产计费还可能区分缓存读取、缓存写入、推理token、工具费用和阶梯价格,应使用对应版本的真实用量与账单核对。失败与重试也可能产生费用。
记录足够信息,同时减少泄漏
程序使用允许字段列表,丢弃secret。真实应用不能依靠一个名为secret的字段检查:敏感信息可能藏在prompt、工具结果、异常栈和URL中。优先记录ID、类型、长度和脱敏摘要,必要原文使用受控存储、访问权限、保留期和审计,而不是默认进入所有日志。
采样策略应兼顾成本与排障:错误、长尾时延或高风险路径可以提高保留比例,但不能用偏向失败的trace样本直接估计总体错误率。总体指标从完整计数或正确加权样本计算。避免日志记录异常反过来让主请求失败,同时监控日志丢失。
版本关联后才能做回归分析
比较新旧版本时,确认请求任务分布、模型路由和知识快照一致。trace能帮助找到候选丢失或工具重试,但不自动证明因果;需要离线回放或受控实验。基础概念参见OpenTelemetry Traces。本篇程序没有接入真实OTel collector,演示的是时间与记录契约。
综合边界推演与面试追问
一个request trace下retrieve=0–40ms、policy=10–50ms、generate=50–150ms,span耗时之和180而墙钟150。关联同一请求ID和父子span,模型m1/prompt p2/index i3及工具版本解释这次到底用了什么。
全量原文日志方便排查却扩大隐私与存储成本,优先白名单字段和受控引用;错误trace多采样利于诊断却不能直接估总体错误率。1000输入/200输出用假设单价2/8每百万得0.0036,缓存与失败尝试仍需另计。
慢请求先拆排队、网络、工具、生成与重试,确认并行重叠而非相加;跨机器时间异常检查时钟。用量异常核对usage与账单,泄漏检查prompt/工具结果/URL/异常而不仅secret字段。版本不同需回放或受控实验,trace相关不自动证明因果。
课后练习展开习题收起习题
先独立作答,再展开参考思路。检查自己的解释是否包含机制、条件和反例。
trace和span分别表达什么?
参考思路与常见误区
trace关联一次完整跨组件操作,span表示其中有时间边界的一段工作;父子和关联关系帮助还原并行、异步与重试。
常见误区:每条普通日志就是一个完整trace。
40ms与40ms两任务重叠30ms,再生成100ms,总时长多少?
参考思路与常见误区
无额外空档时40+40-30+100=150ms,span耗时之和180ms不是墙钟。应实际测根请求与关键路径。
常见误区:所有子span耗时直接相加。
1000输入200输出,每百万单价2和8,假设费用多少?
参考思路与常见误区
(1000×2+200×8)/1000000=0.0036,单位跟随单价。真实费用还需按缓存、推理、失败重试和工具账单核对。
常见误区:只按输出token估价。
如何减少trace泄露敏感信息?
参考思路与常见误区
优先字段白名单、ID和脱敏摘要,原文按需进入受控存储,配权限、保留期和审计;异常、URL和工具返回也要覆盖。
常见误区:只删除名叫password的字段。
多保留错误trace后能直接计算总体错误率吗?
参考思路与常见误区
不能,采样向错误倾斜。总体比例应使用完整计数或正确采样权重,同时保留错误trace用于排障。
常见误区:观测样本比例一定等于真实流量比例。