1# FaultLoggerd组件 2 3## 简介 4 5Faultloggerd部件是OpenHarmony中C/C++运行时崩溃临时日志的生成及管理模块。面向基于 Rust 开发的部件，Faultloggerd 提供了Rust Panic故障日志生成能力。系统开发者可以在预设的路径下找到故障日志，定位相关问题。 6 7## 架构 8 9 10 11* Native InnerKits 接口 12 * SignalHandler：信号处理器，接收系统异常信号，触发抓取进程异常时的现场信息。 13 * BackTrace：本地回栈库，提供进程内本地回栈能力。 14 * DumpCatcher：堆栈信息抓取工具库，提供了抓取指定进程和线程的堆栈栈信息的能力。 15 * FaultloggerdClient：崩溃临时日志管理客户端，接收申请文件描述符、堆栈导出等请求。 16* Rust 接口 17 * PanicHandler：Rust PANIC故障处理器，封装faultloggerd回栈能力支持rust模块PANIC故障回栈。 18 * Rustc Demangle：Rust 符号demangle库，支持Rust模块mangled符号解析。 19* Faultlogger Daemon 服务 20 * FaultloggerdServer：核心服务处理模块，接收并处理客户端的请求。 21 * FaultloggerdSecure：权限校验模块，对运行时崩溃日志生成和抓取提供权限管理和校验能力。 22 * FaultloggerdConfig：崩溃临时日志管理模块。 23 * FaultloggerdPipe：数据管道传输管理模块，提供数据传输管道申请和管理能力。 24* 工具 25 * DumpCatcher Command Tool：提供命令行形式的主动抓栈工具，仅在Debug版本提供。 26 * ProcessDump：进程信息抓取二进制工具，通过命令行方式提供抓取指定进程、线程堆栈信息的能力。 27 * crasher：崩溃构造器，提供了崩溃构造和模拟能力。 28 * Rust Panic Maker：Rust PANIC 故障构造器，提供了构造Rust模块的故障构造能力。 29 30目前主要支持对以下C/C++运行时崩溃异常信号的处理： 31 32| 信号值 | 信号 | 解释 | 触发原因 | 33| ------ | --------- | --------------- | ------------------------------------------------------------ | 34| 4 | SIGILL | 非法指令 | 执行了非法指令，通常是因为可执行文件本身出现错误，或者试图执行数据段，堆栈溢出时也有可能产生这个信号。 | 35| 5 | SIGTRAP | 断点或陷阱异常 | 由断点指令或其它trap指令产生。 | 36| 6 | SIGABRT | abort发出的信号 | 调用abort函数生成的信号。 | 37| 7 | SIGBUS | 非法内存访问 | 非法地址，包括内存地址对齐（alignment）出错。比如访问一个四个字长的整数，但其地址不是4的倍数。它与SIGSEGV的区别在于后者是由于对合法存储地址的非法访问触发的（如访问不属于自己存储空间或只读存储空间）。 | 38| 8 | SIGFPE | 浮点异常 | 在发生致命的算术运算错误时发出，不仅包括浮点运算错误，还包括溢出及除数为0等其它所有的算术的错误。 | 39| 11 | SIGSEGV | 无效内存访问 | 试图访问未分配给自己的内存，或试图往没有写权限的内存地址写数据。 | 40| 16 | SIGSTKFLT | 栈溢出 | 堆栈溢出。 | 41| 31 | SIGSYS | 系统调用异常 | 非法的系统调用。 | 42 43## 目录 44 45```txt 46faultloggerd/ 47├── OAT.xml 48├── common # 工具库和公共定义 49├── docs # 文档 50├── example # 样例代码 51├── frameworks # 主动抓栈实现 52├── interfaces 53│ ├── innerkits 54│ │ ├── backtrace # 本地回栈库 55│ │ ├── dump_catcher # 抓取调用栈基础库 56│ │ ├── faultloggerd_client # 崩溃临时日志管理服务客户端接口 57│ │ └── signal_handler # 异常信号处理器 58│ └── rust 59│ ├── panic_handler # Rust Panic 处理器 60│ ├── panic_report # Rust Panic 故障上报库 61│ └── rustc_demangle # Rust demangle 库 62├── services # faultloggerd 常驻服务 63├── test 64│ ├── funchook # hook 工具测试用例 65│ ├── fuzztest # 模糊测试用例 66│ ├── moduletest # 模块测试用例 67│ ├── performancetest # 性能测试用例 68│ ├── systemtest # 系统测试用例 69│ └── unittest # 单元测试用例 70└── tools 71 ├── crasher_c # 崩溃构造器（C） 72 ├── crasher_cpp # 崩溃构造器（C++） 73 ├── dump_catcher # DumpCatcher 命令行工具 74 ├── panic_maker # Rust Panic 故障构造器 75 └── process_dump # 崩溃抓栈实现 76``` 77 78## 使用说明 79 80### 进程崩溃日志生成 81 82目前已默认开启，进程因上述异常信号崩溃将会在设备 `/data/log/faultlog/temp` 目录下生成完整的崩溃日志，可基于该崩溃日志进行问题定位可分析。 83 84> 崩溃日志介绍和和常见问题指南参看：[faultloggerd FAQ](docs/usage.md) 85 86### DumpCatcher 接口 87 88DumpCatcher是提供给第三方模块使用的抓取调用栈基础库，其中包含了打印指定进程（或线程）的栈信息的接口函数。目前支持CPP调用栈和CPP-JS混合栈。 89 90接口类名：`DfxDumpCatcher` 91 92接口定义： 93* 默认：`bool DumpCatch(int pid, int tid, std::string& msg);` 94* 支持混合栈：`bool DumpCatchMix(int pid, int tid, std::string& msg);` 95* 支持输出到指定文件：`bool DumpCatchFd(int pid, int tid, std::string& msg, int fd);` 96* 支持批量抓栈：`bool DumpCatchMultiPid(const std::vector<int> pidV, std::string& msg);` 97 98接口参数说明： 99* 接口返回值： 100 * `true`：回栈成功，回栈信息存储在`msg`字符串对象中； 101 * `false`：回栈失败。 102* 输入参数： 103 * `pid`：希望回栈的进程号，如果需要回栈进程中的所有线程，则`tid`设定为`0`； 104 * `tid`：希望回栈的线程号； 105 * `fd`：指定写入回栈信息的文件句柄； 106* 输出参数： 107 * `msg`：如果回栈成功，则通过`msg`输出回栈后的信息。 108 109> 注意：此接口需要调用者是管理员（system，root）用户，或者只抓取自己用户拥有的进程信息。 110 111样例代码： 112 113* dump_catcher_demo.h 114 115```c++ 116#ifndef DUMP_CATCHER_DEMO_H 117#define DUMP_CATCHER_DEMO_H 118 119#include <inttypes.h> 120 121#define NOINLINE __attribute__((noinline)) 122 123#define GEN_TEST_FUNCTION(FuncNumA, FuncNumB) \ 124 __attribute__((noinline)) int TestFunc##FuncNumA() \ 125 { \ 126 return TestFunc##FuncNumB(); \ 127 } 128 129// test functions for callstack depth test 130int TestFunc0(void); 131int TestFunc1(void); 132int TestFunc2(void); 133int TestFunc3(void); 134int TestFunc4(void); 135int TestFunc5(void); 136int TestFunc6(void); 137int TestFunc7(void); 138int TestFunc8(void); 139int TestFunc9(void); 140int TestFunc10(void); 141 142#endif // DUMP_CATCHER_DEMO_H 143``` 144 145 * dump_catcher_demo.cpp 146 147```c++ 148#include "dump_catcher_demo.h" 149 150#include <iostream> 151#include <string> 152#include <unistd.h> 153#include "dfx_dump_catcher.h" 154using namespace std; 155 156NOINLINE int TestFunc10(void) 157{ 158 OHOS::HiviewDFX::DfxDumpCatcher dumplog; 159 string msg = ""; 160 bool ret = dumplog.DumpCatch(getpid(), gettid(), msg); 161 if (ret) { 162 cout << msg << endl; 163 } 164 return 0; 165} 166 167// auto gen function 168GEN_TEST_FUNCTION(0, 1) 169GEN_TEST_FUNCTION(1, 2) 170GEN_TEST_FUNCTION(2, 3) 171GEN_TEST_FUNCTION(3, 4) 172GEN_TEST_FUNCTION(4, 5) 173GEN_TEST_FUNCTION(5, 6) 174GEN_TEST_FUNCTION(6, 7) 175GEN_TEST_FUNCTION(7, 8) 176GEN_TEST_FUNCTION(8, 9) 177GEN_TEST_FUNCTION(9, 10) 178 179int main(int argc, char *argv[]) 180{ 181 TestFunc0(); 182 return 0; 183} 184``` 185 186* BUILD.gn： 187 188```gn 189import("//base/hiviewdfx/faultloggerd/faultloggerd.gni") 190import("//build/ohos.gni") 191 192config("dumpcatcherdemo_config") { 193 visibility = [ ":*" ] 194 195 include_dirs = [ 196 ".", 197 "//utils/native/base/include", 198 "//base/hiviewdfx/faultloggerd/interfaces/innerkits/dump_catcher/include/", 199 ] 200} 201 202ohos_executable("dumpcatcherdemo") { 203 sources = [ "dump_catcher_demo.cpp" ] 204 205 configs = [ ":dumpcatcherdemo_config" ] 206 207 deps = [ 208 "//base/hiviewdfx/faultloggerd/interfaces/innerkits/dump_catcher:libdfx_dumpcatcher", 209 "//utils/native/base:utils", 210 ] 211 212 external_deps = [ "hilog:libhilog" ] 213 214 install_enable = true 215 part_name = "faultloggerd" 216 subsystem_name = "hiviewdfx" 217} 218``` 219 220* 执行结果： 221 222```txt 223# ./dumpcatcherdemo 224#00 pc 0000000000000981(00000000004a8981) /data/test/dumpcatcherdemo 225#01 pc 0000000000000a6d(00000000004a8a6d) /data/test/dumpcatcherdemo 226#02 pc 0000000000000a63(00000000004a8a63) /data/test/dumpcatcherdemo 227#03 pc 0000000000000a59(00000000004a8a59) /data/test/dumpcatcherdemo 228#04 pc 0000000000000a4f(00000000004a8a4f) /data/test/dumpcatcherdemo 229#05 pc 0000000000000a45(00000000004a8a45) /data/test/dumpcatcherdemo 230#06 pc 0000000000000a3b(00000000004a8a3b) /data/test/dumpcatcherdemo 231#07 pc 0000000000000a31(00000000004a8a31) /data/test/dumpcatcherdemo 232#08 pc 0000000000000a27(00000000004a8a27) /data/test/dumpcatcherdemo 233#09 pc 0000000000000a1d(00000000004a8a1d) /data/test/dumpcatcherdemo 234#10 pc 0000000000000a13(00000000004a8a13) /data/test/dumpcatcherdemo 235#11 pc 0000000000000a77(00000000004a8a77) /data/test/dumpcatcherdemo 236#12 pc 00000000000c2b08(00000000b6fafb08) /system/lib/ld-musl-arm.so.1(__libc_start_main+116) 237#13 pc 0000000000000938(00000000004a8938) /data/test/dumpcatcherdemo 238#14 pc 00000000000008c4(00000000004a88c4) /data/test/dumpcatcherdemo 239``` 240 241### DumpCatcher 命令行工具 242 243DumpCatcher 是指提供给用户的一个抓取调用栈命令行工具，由 DumpCatcher innerkits 接口封装实现，该工具通过 `-p`、`-t` 参数指定进程和线程，以及 `[-c -m -k]` 可选参数指定抓栈的类型，命令执行后在命令行窗口打印指定的进程的线程栈信息。 244 245工具名称：`dumpcatcher` 246 247位置：`/system/bin` 248 249参数说明： 250 251* `-p [pid]`：打印指定进程下面的所有线程栈信息； 252* `-p [pid] -t [tid]`：打印指定进程下面的指定线程信息。 253* `[-c -m -k]`：可选参数, 指定打印 `-c(pp)`C++调用栈、`-m(ix)`C++ JS混合调用栈、`-k(ernel)`调用栈类型。 254 255返回打印说明：如果栈信息解析成功，则将信息显示到标准输出。 256 257> 注意：使用此接口需要调用者是管理员（system，root）用户。 258 259### Rust Panic 故障处理器 260 261> TODO 262 263## 处理流程 264 265### 进程崩溃抓栈处理流程 266 267 268 2691. 进程运行时异常崩溃后会收到来自 `Kernel` 发送的崩溃信号，由进程在启动加载的 `SignalHandler` 模块进行信号处理； 2702. 进程接收到崩溃信号后，保存当前进程上下文，fork 出子进程执行 `ProcessDump` 二进制进行抓栈； 2713. `ProcessDump` 向 `Faultloggerd` 申请文件句柄用于存储收集到的崩溃日志数据； 2724. `ProcesDump` 将完整崩溃日志数据写入到 `/data/log/faultlog/temp` 目录下进行临时存储； 2735. `ProcessDump` 收集完崩溃日志后，上报给 `Hiview` 进行后续处理； 2744. `Hiview` 接收到新增进程崩溃故障数据后，提取简易的崩溃日志存储到 `/data/log/faultlog/faultlogger` 目录下，并生成 `HiSysevent` 故障事件。 275 276### DumpCatcher 接口/命令行工具 主动抓栈处理流程 277 278 279 2801. 进程A调用`DumpCatcher`库提供的系列接口（1B），或通过 `DumpCatcher` 命令行工具(1A)，申请dump指定进程和线程的堆栈信息； 2812. 如果目前进程是当前进程，则直接调用 `BackTrace Local` 提供的能力进行本地回栈输出（2B）；如果不是，则向 `Faultloggerd` 服务发送抓栈请求（2A）； 2823. `Faultloggerd` 接收到抓栈请求，鉴通过权和管道申请等操作后，向目标进程发送 `SIGDUMP(35)` 信号触发主动抓栈（3）； 2834. 目前进程接收到 `SIGDUMP(35)` 抓栈信号后，保存当前进程上下文，fork出子进程执行 `ProcessDump` 二进制进行抓栈，通过 `Faultloggerd` 申请到的管道返回调用栈数据（4）。 284 285### Rust Panic 故障日志收集流程 286 287// TODO 288 289## 相关仓 290 291[DFX子系统](https://gitee.com/openharmony/docs/blob/master/zh-cn/readme/DFX%E5%AD%90%E7%B3%BB%E7%BB%9F.md) 292 293[hiviewdfx\_hiview](https://gitee.com/openharmony/hiviewdfx_hiview/blob/master/README_zh.md) 294 295[hiviewdfx\_hilog](https://gitee.com/openharmony/hiviewdfx_hilog/blob/master/README_zh.md) 296 297[hiviewdfx\_hiappevent](https://gitee.com/openharmony/hiviewdfx_hiappevent/blob/master/README_zh.md) 298 299[hiviewdfx\_hisysevent](https://gitee.com/openharmony/hiviewdfx_hisysevent/blob/master/README_zh.md) 300 301**hiviewdfx\_faultloggerd** 302 303[hiviewdfx\_hilog\_lite](https://gitee.com/openharmony/hiviewdfx_hilog_lite/blob/master/README_zh.md) 304 305[hiviewdfx\_hievent\_lite](https://gitee.com/openharmony/hiviewdfx_hievent_lite/blob/master/README_zh.md) 306 307[hiviewdfx\_hiview\_lite](https://gitee.com/openharmony/hiviewdfx_hiview_lite/blob/master/README_zh.md) 308 309
