1# TraceStreamer工具说明 2TraceStreamer是一个trace数据解析程序，可以将一个trace文本文件或者基于proto序列化的二进制文件转换成为sqlite数据库的形式。 TraceStreamer使用C++实现，支持在ohos, linux, mac等系统上使用，具有良好的跨平台特性。 3 4## 关于TraceStreamer的使用说明 5TraceStreamer工具可以2种方式使用： 61. 可以将系统离线trace文件解析并转为db，此工具支持基于文本的trace和基于proto的trace。 72. TraceStreamer工具还可以WebAssembly的方式在浏览器中运行，需提供相关接口给js文件。 8 9### 导出db模式 10在导出db模式下，通过下面的指令： 11``` 12./trace_streamer trace文件路径名 -e 导出db路径名.db 13``` 14可以将trace文件转为db文件。 15本应用支持在ohos, linux, mac使用。 16在数据导出之后，会在本地目录下生成一个trace_streamer.log文件，在导出db的目录下生成一个数据库文件同名，.db.ohos.ts后缀的文件。 17文件内容如下： 18``` 19当前时间戳:执行结果（数字） 20应用运行时间 21``` 22执行结果解释如下： 23``` 240 代表执行成功 1 表示输入文件不匹配， 2 表示解析错误， 3其他错误。 25``` 26#### __关于db文件的说明__ 27可以使用sqliteexport或DB Browser for SQLite工具加载生成的db，通过查看stat表，可以浏览当前数据一共有多少类数据，各类数据都收到多少条，数据是否正常等情况。在meta表会记录数据库导出时的一些系统信息，比如导入和导出的文件全路径，解析时间等信息。 28meta表可以选择不导出（有些情况下会暴露系统敏感信息），在导出时添加 -nm选项即可。 29更多db文件的介绍，可以参考[doc/des_tables.md](./doc/des_tables.md)。 30 31### 内置浏览器模式 32TraceStreamer可以WebAssembly方式在浏览器中运行，相关接口在wasm模式下生成的trace_streamer_builtin.js文件中，js可以使用的接口如下使用如下接口访问trace_streamer: 33``` 34extern "C" { 35/* 初始化wasm，在JS中注册回调函数，并返回一段可复用的内存空间，由JS调用 36 * 37 * @ replyFunction: 回调函数，返回json格式的数据。 38 * @ reqBufferSize: js在wasm中申请的内存大小。 39 * @ replyTLVFunction: 回调函数，返回proto格式的sql查询结果。 40 * @ ffrtConvertedReply: 回调函数，返回ffrt转换后生成的新trace文件。 41 * return: 返回一段内存地址给JS 42*/ 43EMSCRIPTEN_KEEPALIVE uint8_t *Initialize(uint32_t reqBufferSize, 44 ReplyFunction replyFunction, 45 TLVReplyFunction replyTLVFunction, 46 ReplyFunction ffrtConvertedReply) 47 48extern "C" { 49/* 初始化wasm，在JS中注册大文件切割或按时间切割文件的回调函数，并返回一段可复用的内存空间，由JS调用 50 * 51 * @ splitFileFunction: 回调函数, 返回大文件切割，或者按时间切割后生成的数据。 52 * @ reqBufferSize: js在wasm中申请的内存大小。 53 * return: 返回一段内存地址给JS 54*/ 55EMSCRIPTEN_KEEPALIVE uint8_t *InitializeSplitFile(SplitFileFunction splitFileFunction, uint32_t reqBufferSize) 56 57/* 通知wasm,按时间切割文件的时间信息已发送，并且通知时间信息大小为dataLen字节 58 * 59 * @ dataLen 切割文件的时间信息长度。 时间数据保存在InitializeSplitFile接口申请的内存中。数据格式:"startTS;endTS;"。 60 * return: bool类型。解析切割时间信息成功返回true,否则返回false。 61*/ 62EMSCRIPTEN_KEEPALIVE int TraceStreamerSplitFileEx(int dataLen) 63 64/* 通知wasm,按时间切割的文件信息已发送，并且通知发送的文件信息大小为dataLen字节 65 * 66 * @ dataLen 已经发送的被切割的文件数据长度，数据内容保存在InitializeSplitFile接口申请的内存中。 67 * @ isFinish bool类型， 被切割的文件数据发送完成为true, 否则为false。 68 * return: 切割成功返回0,否则返回-1。 69*/ 70EMSCRIPTEN_KEEPALIVE int TraceStreamerReciveFileEx(int32_t dataLen, int32_t isFinish) 71 72/* JS在wasm中申请一段内存，用于传输config配置信息。如： ffrt convert开关，animation开关，taskpool开关等 73 * 74 * @ reqBufferSize JS准备申请的内存大小。 75 * return: 返回一段内存地址给JS。 76*/ 77EMSCRIPTEN_KEEPALIVE uint8_t *InitializeParseConfig(uint32_t reqBufferSize) 78 79/* JS通知wasm已经发送了config信息，并通知发送的数据大小。 wasm解析config信息。 80 * 81 * @ dataLen JS发送config信息大小， 数据内容保存在InitializeParseConfig接口申请的内存中。 82 * return: wasm解析config信息成功返回0，否则返回-1。 83*/ 84EMSCRIPTEN_KEEPALIVE int TraceStreamerParserConfigEx(int dataLen) 85 86/* JS通知wasm已经发送大文件切割的时间信息，并通知发送的数据大小。 wasm解析大文件切割的时间信息。 87 * 88 * @ dataLen JS发送大文件切割时间信息长度。时间信息格式为proto数据的1024头，保存在InitializeSplitFile接口申请的内存中。 89 * return: wasm解析大文件切割时间信息成功返回0，否则返回-1。 90*/ 91EMSCRIPTEN_KEEPALIVE int TraceStreamerGetLongTraceTimeSnapEx(int dataLen) 92 93/* JS通知wasm已经发送大文件切割的文件数据，并通知发送的数据大小。 94 * 95 * @ dataLen JS发送大文件切割文件数据大小。 96 * @ isFinish JS发送数据是否结束。 97 * @ pageNum 准备按照第pageNum个文件的时间范围，切割大文件。 98 * return: wasm解析大文件切割时间信息成功返回0，否则返回-1。 99*/ 100EMSCRIPTEN_KEEPALIVE int TraceStreamerLongTraceSplitFileEx(int dataLen, int32_t isFinish, uint32_t pageNum) 101 102/* 导入so重新符号化业务，JS通知wasm申请内存保存导入so的文件名称，并设置导入so重新符号化的回调函数。 103 * 104 * @ parseELFCallback 回调函数 105 * @ reqBufferSize 申请的文件大小 106 * return: 返回一段内存给JS。 107*/ 108EMSCRIPTEN_KEEPALIVE uint8_t *InitFileName(ParseELFFunction parseELFCallback, uint32_t reqBufferSize) 109 110/* 更新起始结束时间,由JS调用 111 * 112 * @ len: 起始和结束时间组成的字符串长度 113 * return: 成功返回0。 114*/ 115EMSCRIPTEN_KEEPALIVE int UpdateTraceTime(int len) 116 117/* 设置TraceStreamer和第三方wasm通信的回调函数,并返回一段内存，由JS调用 118 * 119 * @ sendDataCallBack:与第三方wasm通信的回调函数 120* @ reqBufferSize: 返回的内存长度 121* return: 成功返回0 122*/ 123EMSCRIPTEN_KEEPALIVE uint8_t* TraceStreamerSetThirdPartyDataDealer(SendDataCallBack sendDataCallBack, uint32_t reqBufferSize) 124 125/* 设置TraceStreamer可以打印的日志级别，由JS调用 126 * 127 * @ level: 允许打印日志的最低级别。 128*/ 129EMSCRIPTEN_KEEPALIVE void TraceStreamerSetLogLevel(uint32_t level) 130 131/* TraceStreamer的数据解析接口，由JS调用 132 * 133* @ dataLen: 需要解析的数据源长度 134* return: 成功返回0，失败返回-1 135*/ 136EMSCRIPTEN_KEEPALIVE int TraceStreamerParseDataEx(int dataLen, bool isFinish) 137 138/* 导入so重新符号化业务的下载so文件接口，由JS调用 139 * 140 * @ totalLen: 传输的文件总长度。 141 * @ fileNameLen: 传输的文件名长度。 142 * @ dataLen: 当前调用传输的文件数据长度。 143 * @ finish: 当前文件是否传输结束。 144 * return: wasm下载并保存该文件成功返回0，失败返回-1 145*/ 146EMSCRIPTEN_KEEPALIVE int32_t TraceStreamerDownloadELFEx(int32_t totalLen, 147 int32_t fileNameLen, 148 int32_t dataLen, 149 int32_t finish) 150 151/* TraceStreamer停止解析数据，由JS调用 152 * 153* return: 成功返回0，失败返回-1 154*/ 155EMSCRIPTEN_KEEPALIVE int TraceStreamerParseDataOver() 156 157/* 数据库操作接口，由JS调用，返回json格式的sql查询结果。 158 * 159* @ sqlLen: 需要执行的操作类sql语句长度 160* return: 成功返回0，失败返回-1 161*/ 162EMSCRIPTEN_KEEPALIVE int TraceStreamerSqlOperateEx(int sqlLen) 163 164/*清空wasm内存中的内容，由JS调用 165 * 166* return: 成功返回0，失败返回-1 167*/ 168EMSCRIPTEN_KEEPALIVE int TraceStreamerReset() 169 170/*执行查询类sql语句，由JS调用 171 * 172* @ sqlLen: 需要执行的查询类sql语句长度 173* return: 成功返回0，失败返回-1 174*/ 175EMSCRIPTEN_KEEPALIVE int TraceStreamerSqlQueryEx(int sqlLen) 176 177/*取消sql查询，由JS调用。 178 * 179* return: 成功返回0。 180*/ 181EMSCRIPTEN_KEEPALIVE int TraceStreamerCancel() 182 183/*执行查询类sql语句，由JS调用。返回proto格式的sql查询结果。 184 * 185* @ sqlLen: 需要执行的查询类sql语句长度 186* return: 成功返回0，失败返回-1 187*/ 188EMSCRIPTEN_KEEPALIVE int32_t TraceStreamerSqlQueryToProtoCallback(int32_t sqlLen) 189/*执行metrics数据查询 190 * 191* @ sqlLen: 需要执行的查询类sql语句长度 192* return: 成功返回0，失败返回-1 193*/ 194EMSCRIPTEN_KEEPALIVE int32_t TraceStreamerSqlMetricsQuery(int32_t sqlLen) 195 196/*发送数据给第三方wasm解析，由TraceStreamer调用 197 * 198* @ pluginData: 第三方插件的数据源 199* @ len: 数据源长度 200* @ componentName: 第三方插件名称 201* return: 成功返回0 202*/ 203int TraceStreamerPluginOutSendData(const char* pluginData, int len, const std::string componentName) 204 205/*返回解析数据库 206 * 207 * @ fun: 回调函数，负责返回解析生成的数据库。 208 * return: 成功返回0 209*/ 210EMSCRIPTEN_KEEPALIVE int32_t WasmExportDatabase(ExportDBCallback fun) 211 212/* 初始化配置接口，由JS调用 213 * 214* @ dataLen: 配置字符串的长度 215* return: 成功返回0 216*/ 217EMSCRIPTEN_KEEPALIVE int TraceStreamerInitThirdPartyConfig(int dataLen) 218 219} // extern "C" 220``` 221 222### 可以执行如下命令查看应用帮助 223```./trace_streamer --help``` 224 225### TraceStreamer支持解析的事件列表 226通过```./trace_streamer -i``` 227查看支持的事件列表。 228支持的事件列表参见[SupportEventList.md](./doc/des_support_event.md)。 229## TraceStreamer重要概念介绍 230### 进程和线程标识符 231``` 232在通用操作系统中，进程号（pid/tgid）和线程号（tid）可能会被重复用于标识不同的进程或者线程。所以在trace数据源中，进程号（pid）和线程号（tid）也可能被重用。 233TraceStreamer在解析数据过程中，使用ipid(internal pid)唯一标识进程， itid(internal tid)唯一标识线程。 234``` 235### 计量器 236用来记录系统中各种随时间连续变化的数值。例如： CPU的频率， 内存的使用量， 界面刷新频率。 237#### 举例 238CPU频率： 239 240内存占用： 241 242 243### 过滤器 244TraceStreamer设计过程中使用了流式处理的思想，数据从入口进入以后，就像进入一条河流，从上游流向下游，在河道中央有很多过滤器，每种过滤器会将流过的数据中自己关注的内容吸附捕捉到。最终，每个过滤器都拥有了大量同类型的数据，而且这些数据都是按时间序列排列的。TraceStreamer使用filterid来标识同一种用途的数据，可以方便在UI中绘制。 245 246 247## Stat表设计 248具体内容参见 [des_stat](./doc/des_stat.md)。 249## TraceStreamer开发环境搭建和编译运行指引 250 251本应用使用gn作为构建工具。 252### 开发环境 253可以在ubuntu、mac、windows下执行开发和编译，建议使用vscode开发工具。 254在windows平台上，需使用支持c++17标准的clang编译器。 255# 对外部的依赖 256本应用依赖与sqlite、protobuf(htrace解析部分依赖)、nlohmann_json。 257本应用同时依赖于src/protos/protogen.sh目录下文件来生成相关pb.h，pb.cc文件。 258_____ 259 260### 编译linux和Mac应用 261在目录下有build.sh脚本，在不同的平台上会判断系统版本，编译相应系统的应用。 262``` 263./build.sh linux 264./build.sh macx 265``` 266 267### 编译wasm 268``` 269./build.sh wasm 270``` 271 272### 开始编译 273本工具建议独立编译，通过部署第三方依赖库，emsdk，可编译出支持不同平台的应用。 274具体方法可参考[compile_trace_streamer](./doc/compile_trace_streamer.md)。
