DSH plugin 插件开发的可诊断性:日志、事件与只读状态怎么留证据,线上故障怎么复现
插件开发做到能上线,只差一步:让故障自己说话。 很多插件出问题时,日志里只有一句 undefined,重启之后现场消失,剩下只能靠猜。DSH插件 的诊断能力不靠框架赠送,而是你在写代码时决定留下哪些证据。
DSH plugin 出问题时你希望看到什么
先假想一次故障,再倒推该记哪些字段。(来源)
拿三个问题问自己:
- 它在做什么? 当前处于初始化、就绪还是已停止,最近一次成功是什么时候。
- 它为什么停下? 错误码、失败阶段、是否被取消,而不是只有一句“失败了”。
- 它现在是什么状态? 条目数、队列长度、上次读到哪个位置。
这三个问题的答案,决定了你要暴露哪些状态字段、在哪些位置打日志。反过来,如果一个问题都答不上来,说明插件的内部状态对外完全不可见。
诊断设计的目标不是“日志多”,而是“一条日志能定位到一段代码,一个状态能回答一个疑问”。
日志:DSH plugin 一条只带一个事实
把多个事实塞进一行日志,等于把可检索性换成可读性。(来源)
一条好日志通常长这样:固定前缀 + 一个动作 + 一个结果。固定前缀让 grep 能命中,动作说明发生了什么,结果说明成败。
三条实践:
- 前缀固定 — 例如统一带插件名,避免与其他插件的输出混在一起。
- 一条一个事实 — “读取完成”和“解析失败”分成两条,不要写成“读取完成但解析失败、条目 3 个”。
- 错误带阶段 — 初始化失败、注册失败、调用失败是三种问题,日志里要能区分。
热路径上还要克制:每个请求都打印完整对象,会让日志量和 CPU 一起上涨。把细节留给状态查询,日志只留“发生了”和“结果如何”。
事件作为 DSH plugin 的诊断通道
事件适合广播“发生了什么”,不适合承载“必须完成什么”。(来源)
进程内事件没有持久化、没有重放,监听器抛错也不该影响发布方。这三点决定了它的定位:通知与观察。
适合用事件表达的内容:
- 阶段变化 — 索引构建开始、完成、失败。
- 外部可见的副作用 — 写入了哪个文件、刷新了哪个缓存。
- 给其他插件的扩展点 — 允许别人在你的流程里插入行为。
不适合的:必须送达的通知、需要重试的任务、会改变主流程结果的分支。这些应该用方法调用或后台任务,否则一旦没有监听器,行为就悄悄不同了。
只读状态比日志更适合 DSH plugin 排障
状态能随时查,日志只能等下一次复现。(来源)
只读状态的写法很简单:在插件里维护一组字段(就绪标记、条目数、最近一次错误、上次成功时间),通过一个查询入口返回快照。查询时不做重活,也不触发初始化。
它的价值在三个场景特别明显:
- “现在到底有没有数据” — 直接看条目数,不用翻日志。
- “是不是卡在初始化” — 看就绪标记与最近错误,比猜快得多。
- “泄漏有没有发生” — 隔一段时间查一次计数,趋势一眼可见。
状态字段要跟着 Fiber 走:插件卸载后这些字段应当失效,而不是留在一个模块级对象里,让下一次加载读到上一轮的残留。
DSH plugin 不要把敏感值写进日志
“打印出来方便排查”是泄漏凭据最常见的原因。(来源)
凭据在配置里是引用,值由提供方持有;一旦你把 resolve 的结果写进日志,就等于绕过了整条脱敏链路。遥测侧还有 session-telemetry/record 这条 waterfall 负责变换记录,但那只覆盖走遥测通道的数据,不覆盖你自己 console.log 的内容。
可以打印的元信息:来源层(env、file、user-env)、是否已配置、长度、解析耗时。不能打印的:值本身、完整的请求头、文件内容片段。
DSH plugin 诊断自检五条
上线前过一遍,能省掉一半“无法复现”的工单。(来源)
- 每个失败分支都有日志,且带错误码与阶段。
- 关键流程有阶段事件,外界能知道“开始、完成、失败”。
- 暴露了只读状态,能回答“现在是什么情况”。
- 日志里没有凭据、文件内容与完整请求头。
- 状态字段随插件卸载失效,不会跨实例残留。
验证:让故障可复现
诊断能力的验收标准是:不看代码也能定位。(来源)
- 人为制造一次初始化失败,断言日志里能读到失败阶段与错误码,而不只是“失败”。
- 让一次调用抛错,断言只读状态里的“最近错误”同步更新。
- 连续触发两次热重载,断言状态字段没有残留上一轮的计数。
- 把凭据引用指向已配置的值,断言日志只出现来源层与长度,不出现值。
- 订阅阶段事件,断言开始与完成各收到一次,且没有重复通知。
如果第 3 步看到计数翻倍,说明状态存在模块作用域;第 4 步出现明文,说明日志绕过了脱敏约定。
遥测侧的脱敏与通道分工,可以对照会话遥测与脱敏;加载阶段的排查手段见插件本地调试。
一句话收束: 一条日志只讲一个事实,事件只负责通知与观察,状态字段随时可查且随实例失效,凭据永不落日志;三样凑齐,故障才不用靠猜。
常见问题
DSH plugin 的日志按“一条日志只带一个事实”来打,关键路径各一条即可。运行期不限制你打日志,但同步打日志会占加载与请求的时间,热路径上应避免拼接大对象;需要细节时用只读状态查询补,而不是把每个变量都打印出来。
DSH plugin 的事件建议只做诊断与通知。事件是进程内广播,没有持久化与重放,监听器抛错也不该影响发布方;把它当业务通道会在“没人监听时怎么办”上失守。业务流程用方法调用或服务,事件用来告诉外界发生了什么。
DSH plugin 的只读状态在排障时比日志更完整。日志只是时间点快照,只能看到打日志那一刻;只读状态能随时查询当前条目数、就绪标记与最近一次错误,不用等下一次复现。把关键计数做成状态字段,是最省成本的诊断投入。
不能,DSH plugin 的日志不该直接打印配置值与请求头。凭据以引用形式存在配置里,值由提供方持有,明文落日志等于绕过脱敏;遥测侧还有 session-telemetry/record 这条 waterfall 负责脱敏。日志只打印来源层、是否配置、长度这类元信息,不要打印值本身。
相关术语
- ctx.emit
- ctx.emit 是发布进程内事件的入口,事件没有持久化与重放,适合通知与诊断,不适合承载必须送达的业务流程。— DeepSeek Harness 官方文档 - 插件与生命周期
- session-telemetry/record
- session-telemetry/record 是每条导出遥测记录必经的 waterfall,监听器可变换记录,不调用 next 即替换下层全部逻辑。— DeepSeek Harness 官方参考 - 会话遥测
- 只读状态
- 只读状态是插件对外暴露的当前快照,查询时现算或读缓存,不触发副作用,适合排障时替代追加日志。— DeepSeek Harness 官方文档 - 插件与生命周期
- Fiber
- Fiber 是每个插件实例的生命周期作用域,插件卸载后其登记被清理,诊断字段也应随实例一起失效。— DeepSeek Harness 官方文档 - 插件与生命周期
来源
- DeepSeek Harness 官方参考 - 会话遥测· deepseek-ai
- DeepSeek Harness 官方文档 - 插件与生命周期· deepseek-ai