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: 回调函数 38* @ reqBufferSize: 返回的内存长度 39* return: 返回一段内存地址给JS 40*/ 41EMSCRIPTEN_KEEPALIVE uint8_t* Initialize(ReplyFunction replyFunction, uint32_t reqBufferSize) 42 43/* 更新起始结束时间,由JS调用 44 * 45 * @ len: 起始和结束时间组成的字符串长度 46* return: 成功返回0。 47*/ 48EMSCRIPTEN_KEEPALIVE int UpdateTraceTime(int len) 49 50/* 设置TraceStreamer和第三方wasm通信的回调函数,并返回一段内存，由JS调用 51 * 52 * @ sendDataCallBack:与第三方wasm通信的回调函数 53* @ reqBufferSize: 返回的内存长度 54* return: 成功返回0 55*/ 56EMSCRIPTEN_KEEPALIVE uint8_t* TraceStreamer_Set_ThirdParty_DataDealer(SendDataCallBack sendDataCallBack, uint32_t reqBufferSize) 57 58/* TraceStreamer的数据解析接口，由JS调用 59 * 60* @ dataLen: 需要解析的数据源长度 61* return: 成功返回0，失败返回-1 62*/ 63EMSCRIPTEN_KEEPALIVE int TraceStreamerParseDataEx(int dataLen) 64 65/* TraceStreamer停止解析数据，由JS调用 66 * 67* return: 成功返回0，失败返回-1 68*/ 69EMSCRIPTEN_KEEPALIVE int TraceStreamerParseDataOver() 70 71/* 数据库操作接口，由JS调用 72 * 73* @ sqlLen: 需要执行的操作类sql语句长度 74* return: 成功返回0，失败返回-1 75*/ 76EMSCRIPTEN_KEEPALIVE int TraceStreamerSqlOperateEx(int sqlLen) 77 78/*清空wasm内存中的内容，由JS调用 79 * 80* return: 成功返回0，失败返回-1 81*/ 82EMSCRIPTEN_KEEPALIVE int TraceStreamerReset() 83 84/*执行查询类sql语句，由JS调用 85 * 86* @ sqlLen: 需要执行的查询类sql语句长度 87* return: 成功返回0，失败返回-1 88*/ 89EMSCRIPTEN_KEEPALIVE int TraceStreamerSqlQueryEx(int sqlLen) 90 91/*取消sql查询，由JS调用。 92 * 93* return: 成功返回0。 94*/ 95EMSCRIPTEN_KEEPALIVE int TraceStreamerCancel() 96 97/*发送数据给第三方wasm解析，由TraceStreamer调用 98 * 99* @ pluginData: 第三方插件的数据源 100* @ len: 数据源长度 101* @ componentName: 第三方插件名称 102* return: 成功返回0 103*/ 104int TraceStreamer_Plugin_Out_SendData(const char* pluginData, int len, const std::string componentName) 105 106/* 初始化配置接口，由JS调用 107 * 108* @ dataLen: 配置字符串的长度 109* return: 成功返回0 110*/ 111EMSCRIPTEN_KEEPALIVE int TraceStreamer_Init_ThirdParty_Config(int dataLen) 112 113} // extern "C" 114``` 115 116### 可以执行如下命令查看应用帮助 117```./trace_streamer --help``` 118 119### TraceStreamer支持解析的事件列表 120通过```./trace_streamer -i``` 121查看支持的事件列表。 122支持的事件列表参见[SupportEventList.md](./doc/des_support_event.md)。 123## TraceStreamer重要概念介绍 124### 进程和线程标识符 125``` 126在通用操作系统中，进程号（pid/tgid）和线程号（tid）可能会被重复用于标识不同的进程或者线程。所以在trace数据源中，进程号（pid）和线程号（tid）也可能被重用。 127TraceStreamer在解析数据过程中，使用ipid(internal pid)唯一标识进程， itid(internal tid)唯一标识线程。 128``` 129### 计量器 130用来记录系统中各种随时间连续变化的数值。例如： CPU的频率， 内存的使用量， 界面刷新频率。 131#### 举例 132CPU频率： 133 134内存占用： 135 136 137### 过滤器 138TraceStreamer设计过程中使用了流式处理的思想，数据从入口进入以后，就像进入一条河流，从上游流向下游，在河道中央有很多过滤器，每种过滤器会将流过的数据中自己关注的内容吸附捕捉到。最终，每个过滤器都拥有了大量同类型的数据，而且这些数据都是按时间序列排列的。TraceStreamer使用filterid来标识同一种用途的数据，可以方便在UI中绘制。 139 140 141## Stat表设计 142具体内容参见 [des_stat](./doc/des_stat.md)。 143## TraceStreamer开发环境搭建和编译运行指引 144 145本应用使用gn作为构建工具。 146### 开发环境 147可以在ubuntu、mac、windows下执行开发和编译，建议使用vscode开发工具。 148在windows平台上，需使用支持c++17标准的clang编译器。 149# 对外部的依赖 150本应用依赖与sqlite、protobuf(htrace解析部分依赖)、nlohmann_json。 151本应用同时依赖于src/protos/protogen.sh目录下文件来生成相关pb.h，pb.cc文件。 152_____ 153 154### 编译linux和Mac应用 155在目录下有build.sh脚本，在不同的平台上会判断系统版本，编译相应系统的应用。 156``` 157./build.sh linux 158./build.sh macx 159``` 160 161### 编译wasm 162``` 163./build.sh wasm 164``` 165 166### 开始编译 167本工具建议独立编译，通过部署第三方依赖库，emsdk，可编译出支持不同平台的应用。 168具体方法可参考[compile_trace_streamer](./doc/compile_trace_streamer.md)。
