埋点排错日志怎么留证据：只记录事件阶段，不记录整包请求

排查“客户端发送成功报表没有数据”时最容易临时加一句console.log(req.body)。它确实能显示请求却可能把令牌、邮箱、完整 URL、Cookie 或业务属性一起写进排错日志。更稳妥的方法是先定义排错所需的最小证据再按字段白名单生成结构化记录。本文由 SensorFlow 项目维护方整理AI 辅助起草下方仅为离线合成示例不是 SensorFlow 已内置的日志配置也不是对真实用户数据的测试。一、日志要回答什么问题一条埋点排错记录至少要能区分请求是否进入接收层、是否被验证拒绝、是否进入后续处理、是否出现可查询的测试记录。received、rejected、persisted是本文合成示例中的阶段名称不应未经核对就照搬为某个产品的实际状态码。建议保留测试事件 ID、事件名、阶段、结果码、受控路由模板和发生时间。不要把“请求正文完整保存”当作诊断能力。OWASP 的日志指南明确提醒会话标识、访问令牌、密码和敏感个人数据通常不应直接进入日志。OpenTelemetry 的敏感数据处理指南也强调最小化采集并说明具体哪些数据敏感仍需由实施团队根据场景判断。二、先选字段再处理字符串对调试数据做“先整包序列化再用正则遮住敏感值”很脆弱新字段、嵌套对象或不同编码都可能漏过。此处先构造一个全新的输出对象只放约定字段。字段本身仍须验证例如事件 ID 若由邮箱拼成就不能因为字段名叫event_id而当作安全值。完整 URL 常带查询参数。Node 的URL 文档说明search和searchParams对应查询部分。因此这里不记录url只允许预先登记的路由模板。这个选择不等于所有路由模板都无敏感信息生产字典仍需审核。三、运行一个不联网的白名单示例保存为safe-log.cjs执行node safe-log.cjs。它只使用 Node 内置的严格断言不会向任何网站上传数据。下面的 ID、邮箱和令牌都是合成占位符。constassertrequire(node:assert/strict);conststagesnewSet([received,rejected,persisted]);constnamesnewSet([page_view,signup_success]);constroutesnewSet([/signup,/orders/:orderId]);functionsafeCode(value){if(typeofvalue!string||!/^t-[A-Za-z0-9]{1,20}$/.test(value)){thrownewError(invalid synthetic test ID);}returnvalue;}functionpick(value,allowed,label){if(!allowed.has(value))thrownewError(invalid label);returnvalue;}functiondebugLine(input){constoutput{test_event_id:safeCode(input.test_event_id),event_name:pick(input.event_name,names,event name),stage:pick(input.stage,stages,stage),route_template:pick(input.route_template,routes,route),error_class:input.stagerejected?pick(input.error_class,newSet([schema,auth]),error class):null};returnJSON.stringify(output);}constraw{test_event_id:t-A1,event_name:signup_success,stage:rejected,route_template:/signup,error_class:schema,email:privateexample.test,access_token:synthetic-secret,url:https://example.test/signup?tokensynthetic-secret};constlinedebugLine(raw);assert.equal(JSON.parse(line).stage,rejected);assert.equal(JSON.parse(line).error_class,schema);assert.equal(line.includes(privateexample.test),false);assert.equal(line.includes(synthetic-secret),false);assert.equal(line.includes(https://),false);assert.throws(()debugLine({...raw,test_event_id:privateexample.test}));assert.throws(()debugLine({...raw,stage:received\nFAKE}));assert.throws(()debugLine({...raw,route_template:/orders/123}));console.log(line);console.log(PASS: 8 synthetic log checks);通过时会输出一条只有五个受控字段的 JSON 日志行并完成八条断言。这里使用 JSON 编码和枚举/长度约束也是在减少换行注入和超长输入造成的排查困难OWASP 的日志注入说明解释了不可信输入如何伪造日志行。四、白名单之外还要验收什么这段代码没有实现真实 SDK 接收、身份关联、追踪系统或日志存储。上线前还应检查三件事第一日志采集器、反向代理和异常上报器是否另行记录了完整 URL 或请求体第二谁能读日志、保存多久、备份如何处理第三测试事件 ID 能否与接收日志、存储行和报表查询对应。只保护应用的一条console.log不代表整条链路完成脱敏。排错的目标是让差异可定位而不是留下最多原始数据。对一个合成测试事件写清“在哪个阶段消失、凭哪条受控证据判断”通常比贴出整包真实请求更有用。