README.md
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<br>
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文件的介绍，可以参考[des_tables.md](des_tables.md)。
30<br>
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```./trace_streamer --help```
117
118### TraceStreamer支持解析的事件列表
119通过```./trace_streamer -i```
120查看支持的事件列表。
121支持的事件列表参见[SupportEventList.md](des_support_event.md)。
122<br><br>
123## TraceStreamer重要概念介绍
124### 进程和线程标识符
125在通用操作系统中，进程号（pid/tgid）和线程号（tid）可能会被重复用于标识不同的进程或者线程。所以在trace数据源中，进程号（pid）和线程号（tid）也可能被重用。
126TraceStreamer在解析数据过程中，使用ipid(internal pid)唯一标识进程， itid(internal tid)唯一标识线程。
127<br>
128### 计量器
129用来记录系统中各种随时间连续变化的数值。例如： CPU的频率， 内存的使用量， 界面刷新频率。
130#### 举例
131CPU频率：
132
133内存占用：
134
135<br>
136### 过滤器
137TraceStreamer设计过程中使用了流式处理的思想，数据从入口进入以后，就像进入一条河流，从上游流向下游，在河道中央有很多过滤器，每种过滤器会将流过的数据中自己关注的内容吸附捕捉到。最终，每个过滤器都拥有了大量同类型的数据，而且这些数据都是按时间序列排列的。TraceStreamer使用filterid来标识同一种用途的数据，可以方便在UI中绘制。
138
139
140## Stat表设计
141具体内容参见 [des_stat](des_stat.md)
142## TraceStreamer开发环境搭建和编译运行指引
143
144本应用使用gn作为构建工具。
145### 开发环境
146可以在ubuntu、mac、windows下执行开发和编译，建议使用vscode开发工具。
147在windows平台上，需使用支持c++17标准的clang编译器。
148# 对外部的依赖
149本应用依赖与sqlite、protobuf(htrace解析部分依赖)、nlohmann_json。
150本应用同时依赖于src/protos/protogen.sh目录下文件来生成相关pb.h，pb.cc文件
151_____
152
153### 编译linux和Mac应用
154在目录下有build.sh脚本，在不同的平台上会判断系统版本，编译相应系统的应用
155```
156./build.sh linux
157./build.sh macx
158```
159
160### 编译wasm
161```
162./build.sh wasm
163```
164
165### 开始编译
166本工具建议独立编译， 通过部署第三方依赖库，emsdk，可编译出支持不同平台的应用。
167具体方法可参考[compile_trace_streamer](compile_trace_streamer.md)。
