-
Notifications
You must be signed in to change notification settings - Fork 81
Debug模式的支持和原理
Debug模式提供了在埋点端查询上报内容在服务端解析的功能。主要作用是在部署初期，遇到埋点和落库预期不一致时，埋点端和ghost_sa开发端可以通过Debug模式，进行排查。 这种差异通常发生在ghost_sa部署方式上，当ghost_sa部署在WAF，SLB，端口转发等环境里，请求会经过这些中间件，导致ghost_sa收到的数据和埋点端上报的数据不一致。
| 版本 | 神策官方版 | ghost_sa |
|---|---|---|
| 侧重点 | 埋点数据质量 | 部署质量 |
| 错误提示 | 错误的字段类型，字段长度，字段值等。 | 缺少参数等 |
| 支持SDK | js,iOS,Android,Python,PHP,Java | 理论上所有的SDK都可以支持，验证过js和MiniProgram |
| 开启方式 | SDK开关 | SDK开关和指定URL |
神策官方版Debug模式，主要反馈的是埋点数据的校验，包括字段类型，字段长度，字段值等，重点在数据质量，不提供服务端解析的校验。 ghost_sa的Debug模式，主要是反馈服务端解析的校验，提高部署过程中的体验，解决的是数据正常上报。虽然也会反馈上报内容，但不会做数据质量的校验，因为ghost_sa采用的是行数据库模式，且json存数据，跟神策官方版列存储限定字段的模式不同，埋点数据错误，并不会因为先写入错误数据，导致后续正确数据无法写入。
神策提供了
一共有三种状态，分别是关闭，开启，写入。
| 调试模式 | 接口 | 返回 | 落库 |
|---|---|---|---|
| 关闭 | sa.gif | 43byte空图片 | Yes |
| 开启 | debug | 诊断数据，包含服务器解析到的全部信息 | No |
| 写入 | debug | 诊断数据，包含服务器解析到的全部信息 | Yes |
iOS, Android可以参考这篇了解Debug模式
Python,PHP,Java可以参考这篇了解Debug模式
js sdk，可以在初始化时，增加如下两个参数： debug_mode : true, 这个为true时，开启debug模式，为false时关闭debug模式。 debug_mode_upload : true，在debug_mode开启时，这个值为true，就是写入模式，为false时，就是开启模式。
其他SDK需要自行找方法开启。如iOS和Android SDK，都可以通过搜索debugMode或DebugMode找到对应的参数，进行设置。但是具体怎么设置，需要自行研究。知道怎么进的同学，欢迎联系我更新文档。
在找不到SDK里的Debug开关时，可以直接修改埋点上报地址中的 /sa.gif 为 /debug来开启debug模式。这种开启方式返回数据与SDK Debug开启方式一致，但交互有差异。使用SDK开启方式，界面上会有反馈，使用通用开启方式，需要自己去开发工具里看反馈。他们反馈的内容是相同的。
这种开启方式是符合神策sdk逻辑的，以js sdk为例，无论配置接受地址是 /sa?project=xxx 还是 /sa.gif?project=xxx ，源码里的逻辑都是检测到如果不是sa.gif结尾，就会把sa替换为sa.gif。如果再检测到debug模式开启了，就会再把sa.gif替换为debug。
Debug模式开启后，数据默认是只返回不入库的，这与神策的官方Debug模式一致。
如果需要把数据写入到数据库，可以根据SDK的文档，自行开启debug数据入库。在找不到这个参数时，或者使用通用Debug模式时，可以在上报地址中，增加dryrun=true参数，开启debug数据入库。
Tip
这里dryrun=true是反常识的！但是sdk里就是这么写的。ghost_sa与sdk里写法保持一致。
Important
无论是否开了Kafka模式，即admin.py里 use_kafka = True，debug模式入库都不会经过kafka，而是直接入库。所以Debug数据的落库，只保证落库，没有性能可言，也不会触发access_control和trigger功能。
使用sdk debug模式时，上报请求头通常对返回内容是不做限制的，ghost_sa可以自由返回内容。为了方便解读和sdk判断，返回的内容是经过显示优化的text。直接在调试工具里看，格式就是易读的，不需要做任何format。
使用通用debug模式时，如果上报的请求头没有对内容做限制，则返回内容与sdk debug模式一样。
如果上报的请求头限制了返回内容必须是image，ghost_sa会把返回内容以文字的形式贴在一张图片里返回，格式与sdk debug模式一样。这种情况已知仅存在于js sdk，不使用sdk debug，只使用通用debug，还必须image方式上报的情况。
如果要兼容这种模式，需要在admin.py里，维护font这个值。这个值用来控制返回内容上的字体。因为版权的原因，ghost_sa不提供任何字体，所以需要自行存放，并指定即可。如果不指定字体，在遇到需要image返回时，会返回标准43byte空图片，并在服务端记录一个字体不存在的log。
Tips:字体可以使用NotoSerifCJKsc-Regular.otf。开源免费商用，或者搜思源字体也行，都是MIT协议的，比较安全。