日志多不等于能查清
线上出了问题，翻日志看到满屏的请求开始、请求结束，中间夹杂着异常堆栈。想知道这次调用为什么读了那个文件、是谁授权的、前后重试了几次，却发现这些信息散在三个地方，还缺了关键的一环。
可追溯不是把更多文本写进文件，而是让一次操作能被完整重建。判断标准是四个问题：谁发起的、基于什么输入和状态、做了什么动作、结果如何。四个问题都能答上来，才算一条完整的记录。
从文本改成事件
自由文本适合人读，不适合检索。同样的意思写成不同句子，聚合时就对不上。可行的方式是把每条日志当成一个事件，字段固定，值受控。
最小字段集包括：时间、事件类型、关联标识、主体、动作、目标资源、结果状态、耗时、错误码。业务上需要的维度再加，比如租户、任务、步骤序号。
关联标识是串起全过程的关键。一次用户请求生成一个 trace 标识，它触发的每次工具调用、每次读写都带上同一个标识，同时带自己的 span 标识和父级标识。事后按 trace 一查，调用树就出来了。
事件类型要少而稳定。类型膨胀到几十种，等于没有分类。常用的几类够用：请求接收、决策、工具调用、状态变更、错误、完成。字段值也尽量用枚举，状态只允许成功、失败、进行中几种，不要一会儿写 ok、一会儿写 done，聚合时又得写一堆兼容分支。
不该记的东西
密钥、令牌、完整证件号、银行卡号、精确住址，这些不能进日志。需要排查时用脱敏后的形式，或者只记哈希和末四位。
超大的原始内容也不适合直接落日志。整页 HTML、完整模型输出、几兆的请求体，写进去会让日志系统变慢，检索也变贵。合理做法是记长度、摘要和外部存储的引用。
还有一个容易忽略的点：不要把用户输入拼进查询条件。拼接字符串既会破坏结构，也给了注入的机会。参数化写入，字段就是字段。
日志本身的访问权限也要管。审计记录能看出谁在什么时候做了什么，它本身就是敏感数据。按角色限制读取范围，读取行为也要留痕，否则追溯链条在最外层就断了。
一段结构化写入
importjson,time,uuid SECRET_KEYS={"token","api_key","password","cookie"}defevent(trace_id,kind,**fields):rec={"ts":round(time.time(),3),"trace":trace_id,"span":uuid.uuid4().hex[:16],"kind":kind,# request / decision / tool / state / error"actor":fields.pop("actor","agent"),}rec.update({k:vfork,vinfields.items()ifknotinSECRET_KEYS})print(json.dumps(rec,ensure_ascii=False,sort_keys=True))字段顺序固定、键名稳定，后续才能用同一套查询。写入端不要做业务判断，比如“这条不重要就不记”，重要性往往在事后才显现。
审计和调试日志最好分开存放。审计要求完整、只追加、保留期长；调试要求详细、可丢弃。混在一起，要么审计被噪声淹没，要么为了审计把调试日志留得太久。
保留期按用途定。审计记录需要一个明确的最短保留时间和清理任务，调试日志可以短得多。清理本身也要留记录：删了什么范围、按什么规则删、什么时候删的。
检索入口要提前设计，至少支持按 trace、按时间范围加主体、按错误码三种查询。高频路径可以采样，但错误和状态变更不要采样；恰恰是这些低频事件，出事时最需要完整。
SELECTts,kind,actor,fields->>'tool'AStool,fields->>'status'ASstatusFROMaudit_eventsWHEREtrace=:trace_idORDERBYts;最后是完整性。审计记录写入后不允许修改，只能追加。如果存储支持，定期对一批记录做哈希链或者签名，能证明中间没有被删改；做不到签名，至少要做到写入后只读。
日志的价值不在数量，而在需要的时候能不能回答问题。按这四个问题设计字段，比事后补一堆文本更有用。
