FaultLogger is a maintenance and debugging log framework provided by OpenHarmony. It enables unified detection, log collection, log storage, and log reporting for application, ability, and system service process crashes. It is available for the standard system and the Linux kernel-based small system.
FaultLogger is a maintenance and debugging log framework provided by OpenHarmony. It enables unified detection, log collection, log storage, and log reporting for application, ability, and system service process crashes. It is available for the standard system and the Linux kernel-based small system.
FaultLogger is responsible for fault recording of OpenHarmony. It runs on the following two components based on the service object:
FaultLogger is responsible for fault recording of OpenHarmony. It runs on the following two components based on the service object:
- HiView: serves functional modules at the application layer and native layer. It manages various fault information in the system and provides APIs for modules to query faults.
- Hiview: serves functional modules at the application layer and native layer. It manages various fault information in the system and provides APIs for modules to query faults.
- FaultLoggerd: serves the crash process. It collects information about abnormal daemon processes in C/C++ and obtains the process call stack.
- Faultloggerd: serves the crash process. It collects information about the abnormal daemon process in C/C++ and obtains call stack information of the process.
The following figure shows the process of handling a process crash based on the FaultLogger service.
The following figure shows the process of handling a process crash based on the FaultLogger service.
1. After the signal processor is installed, the **DFX_SignalHandler** function detects and responds to the process crash exception signal.
1. After the signal processor is installed, SignalHandler uses the **DFX_SignalHandler** function to detect and respond to the process crash exception signal thrown by the kernel.
2.**SignalHandler** forks a child process after detecting the exception signal and runs **ProcessDump** to dump the stack information of the crashed process and thread.
2.When detecting a process crash exception signal, SignalHandler forks a child process and runs ProcessDump to dump the stack information of the crashed process and thread.
3.**ProcessDump** then writes a log to the temporary storage directory in FaultLoggerd, generating a full crash log.
3.ProcessDump applies to Faultloggerd for a file handle for storing fault logs. After reading the exception stack information, ProcessDump writes the information to the file to generate a complete crash log.
4.FaultLoggerd reports the fault through the **AddFaultLog()** API provided by HiView. HiView handles the fault, generates a simple crash log, and reports a HiSysEvent.
4.After collecting the complete crash log, ProcessDump reports the log to Hiview by using the **AddFaultLog()** API. Hiview generates a simplified crash log and reports a system event through HiSysEvent.
With this design, a small-system with limited resources can obtain logs for locating crash faults as long as FaultLoggerd is deployed.
With this design, a small-system with limited resources can obtain logs for locating crash faults as long as Faultloggerd is deployed.
### Use Cases
### Use Cases
FaultLoggerd provides a lightweight approach for you to locate crash or suspension problems during development and testing.
Faultloggerd provides a lightweight approach for you to locate crash or suspension problems during development and testing.
It is applicable to the following scenarios:
The following table describes the application scenarios.
**Table 1** Application scenarios of the Faultloggerd module
**Table 1** Application scenarios of the Faultloggerd module
| Scenario| Tool| Usage|
| Scenario| Tool| Usage|
| -------- | -------- | -------- |
| -------- | -------- | -------- |
| To understand the function call sequence| DumpCatcher API | See [Using DumpCatcher to Obtain the Call Stack](#using-dumpcatcher-to-obtain-the-call-stack).|
| Understanding of the function call sequence| DumpCatcher API | See [Using DumpCatcher APIs to Obtain Call Stack Information](#using-dumpcatcher-apis-to-obtain-call-stack-information).|
| Application suspension or high CPU usage| ProcessDump | See [Using ProcessDump to Obtain the Call Stack](#using-processdump-to-obtain-the-call-stack).|
| Application suspension or high CPU usage| DumpCatcher Command Tool | See [Using DumpCatcher Commands to Obtain Call Stack Information](#using-dumpcatcher-commands-to-obtain-call-stack-information).|
| Signal crash not handled by the process| Crash log and addr2line tool| See [Locating Faults Based on Crash Logs](#locating-faults-based-on-crash-logs).|
| Crash fault location| Crash log and addr2line tool| For details, see [Locating Faults Based on the Crash Log](#locating-faults-based-on-the-crash-log).|
## Using DumpCatcher to Obtain the Call Stack
## Using DumpCatcher APIs to Obtain Call Stack Information
### Available APIs
### Available APIs
DumpCatcher can capture the call stack of a specified process (thread) on OpenHarmony.
DumpCatcher can capture the call stack information of the specified process (thread) on OpenHarmony.
Table 2 DumpCatcher APIs
**Table 2** DumpCatcher APIs
| Class| API| Description|
| Class| API| Description|
| -------- | -------- | -------- |
| -------- | -------- | -------- |
| DfxDumpCatcher | bool DumpCatch(const int pid, const int tid, std::string& msg) | Return value:<br>**true**: Back trace is successful. Related information is stored in the **msg** string object.<br>**false**: Back trace failed.<br>Input arguments:<br>**pid**: target process ID.<br>**tid**: target thread ID. If all threads in the process need to be back traced, set **tid** to **0**.<br>Output argument:<br>**msg**: return message. If back trace is successful, the call stack information is returned through **msg**.|
| DfxDumpCatcher | bool DumpCatch(const int pid, const int tid, std::string& msg) | Return value:<br>- **true**: Dumping of stack information is successful. Related information is stored in the msg string object.<br>- **false**: Dumping of stack information has failed.<br> Input arguments:<br>- **pid**: target process ID.<br>- **tid**: target thread ID. If all threads in the process need to be back traced, set **tid** to **0**.<br> Output arguments:<br>- **msg**: If back trace is successful, call stack information is returned through **msg**.|
| DfxDumpCatcher | bool DumpCatchMix(const int pid, const int tid, std::string& msg) | Return value:<br>- **true**: Dumping of stack information is successful. Related information is stored in the msg string object.<br>- **false**: Dumping of stack information has failed.<br> Input arguments:<br>**pid**: target process ID.<br>- **tid**: target thread ID. If all threads in the process need to be back traced, set **tid** to **0**.<br> Output arguments:<br>- **msg**: If back trace is successful, hybrid stack information is returned through **msg**.|
| DfxDumpCatcher | bool DumpCatchFd(const int pid, const int tid, std::string& msg, int fd) | Return value:<br>- **true**: Dumping of stack information is successful. Related information is stored in the msg string object.<br>- **false**: Dumping of stack information has failed.<br> Input arguments:<br>**pid**: target process ID.<br>- **tid**: target thread ID. If all threads in the process need to be back traced, set **tid** to **0**.<br>- **fd**: handle of the file to be written.<br> Output parameters:<br>- **msg**: If back trace is successful, call stack information is returned through **msg**.|
| DfxDumpCatcher | bool DumpCatchMultiPid(const std::vector\<int> pidV, std::string& msg) | Return value:<br>- **true**: Dumping of stack information is successful. Related information is stored in the msg string object.<br>- **false**: Dumping of stack information has failed.<br> Input arguments:<br>- **pidV**: target process ID list.<br> Output arguments:<br>- **msg**: If back trace is successful, call stack information is returned through **msg**.|
> If the PID that calls this API is different from the target PID, the caller must be the **system** or **root** user. To capture the call stack of a process that does not belong to the current user group, ensure that you have permissions to read **/proc/pid/maps** and implement **ptrace** on the peer process.
> If the PID that calls this API is different from the target PID, the caller must be the **system** or **root** user.
### Development Example
### How to Develop
You can use DumpCatcher to obtain the call stack of a specified process (thread) in your applications. The following uses the **dumpcatcherdemo** module as an example to describe how to use the DumpCatcher API to obtain the call stack.
You can use DumpCatcher to obtain call stack information for the specified process (thread) of an application. The following uses the **dumpcatcherdemo** module as an example to describe how to use the DumpCatcher APIs to obtain the call stack information.
1. Add the DumpCatcher dependency to the build file. Take /base/hiviewdfx/faultloggerd/example/BUILD.gn as an example. Add the **dfx_dump_catcher.h** file path to **include_dirs** and add the required **//base/hiviewdfx/faultloggerd/interfaces/innerkits/dump_catcher:lib_dfx_dump_catcher** module to **deps**.
1. Add the DumpCatcher dependency to the build file. Take /base/hiviewdfx/faultloggerd/example/BUILD.gn as an example. Add the **dump_catcher.h** file path to **include_dirs** and add the required **//base/hiviewdfx/faultloggerd/interfaces/innerkits/dump_catcher:lib_dfx_dump_catcher** module to **deps**.
"//base/hiviewdfx/faultloggerd/interfaces/innerkits/dump_catcher:lib_dfx_dump_catcher", # Add the DumpCatcher module dependency.
"//utils/native/base:utils",
]
external_deps = [ "hilog_native:libhilog" ]
install_enable = true
part_name = "faultloggerd"
subsystem_name = "hiviewdfx"
}
}
```
```
...
@@ -138,7 +151,7 @@ You can use DumpCatcher to obtain the call stack of a specified process (thread)
...
@@ -138,7 +151,7 @@ You can use DumpCatcher to obtain the call stack of a specified process (thread)
{
{
OHOS::HiviewDFX::DfxDumpCatcher dumplog;
OHOS::HiviewDFX::DfxDumpCatcher dumplog;
string msg = "";
string msg = "";
bool ret = dumplog.DumpCatch(getpid(), gettid(), msg); // Call the DumpCatch API to obtain the call stack.
bool ret = dumplog.DumpCatch(getpid(), gettid(), msg); // Call the DumpCatch API to obtain the call stack information.
if (ret) {
if (ret) {
cout << msg << endl;
cout << msg << endl;
}
}
...
@@ -165,50 +178,52 @@ You can use DumpCatcher to obtain the call stack of a specified process (thread)
...
@@ -165,50 +178,52 @@ You can use DumpCatcher to obtain the call stack of a specified process (thread)
```
```
## Using ProcessDump to Obtain the Call Stack
## Using DumpCatcher Commands to Obtain Call Stack Information
### Tool Description
### Tool Description
ProcessDump is a command line interface (CLI) based tool for capturing call stacks on OpenHarmony. It uses the **-p** and **-t** parameters to specify the process and thread. After the command is executed, the thread stack information of the specified process is displayed in the CLI window.
DumpCatcher Command Tool is a command line interface (CLI)-based tool for capturing call stack information on OpenHarmony. It uses the **-p** and **-t** parameters to specify the process and thread. After the command is executed, the thread stack information of the specified process is displayed in the CLI window. By specifying the **-m** parameter, you can also capture the JS and Native hybrid stack information of an application process.
**Table 3** Usage of the CLI-based ProcessDump
**Table 3** Usage of the DumpCatcher Command Tool
| Tool| Path| Command| Description|
| Tool| Path| Command| Description|
| -------- | -------- | -------- | -------- |
| -------- | -------- | -------- | -------- |
| processdump | /system/bin | - processdump -p [pid]<br>- processdump -p [pid] -t [tid] | **Arguments:**<br>**- -p [pid]**: prints stack information for all threads of the specified process.<br>**- -p [pid] -t [tid]**: prints information for the specified thread of the specified process.<br>**Return value:**<br>If the stack information is parsed successfully, the information is displayed in the standard output. If the stack information fails to be parsed, error information is displayed.|
| dumpcatcher | /system/bin | - dumpcatcher -p [pid]<br>- dumpcatcher -p [pid] -t [tid]<br>- dumpcatcher -m -p [pid]<br>- dumpcatcher -m -p [pid] -t [tid]<br>| **Description:**<br>- **-p [pid]**: prints all thread stack information of the specified process.<br>- **-p [pid] -t [tid]**: prints stack information for the specified thread of the specified process.<br>- **-m -p [pid]**: prints hybrid stack information for all threads of the specified process.<br>- **-m -p [pid] -t [tid]**: prints hybrid stack information for the specified thread of the specified process.<br>**Return value:**<br>If the stack information is parsed successfully, the information is displayed in the standard output. If the stack information fails to be parsed, error information is displayed.|
> This tool must be used by the **root** user, or the caller must have the permission to ptrace the target process and read the smaps of the target process.
### Development Example
### Example
Print call stack information of the **hiview** process.
Use ProcessDump to print the call stack of the **hiview** process.
#00 pc 0000000000089824(00000000b6f44824) /system/lib/ld-musl-arm.so.1(ioctl+68)
Result: 0 ( no error )
#01 pc 000000000002a709(00000000b6c56709) /system/lib/libipc_core.z.so(_ZN4OHOS15BinderConnector11WriteBinderEmPv+16)
Timestamp:2017-08-05 20:56:43.000
#02 pc 000000000002ba75(00000000b6c57a75) /system/lib/libipc_core.z.so(_ZN4OHOS13BinderInvoker18TransactWithDriverEb+224)
Pid:240
#03 pc 000000000002bb37(00000000b6c57b37) /system/lib/libipc_core.z.so(_ZN4OHOS13BinderInvoker13StartWorkLoopEv+22)
Uid:1201
#04 pc 000000000002c211(00000000b6c58211) /system/lib/libipc_core.z.so(_ZN4OHOS13BinderInvoker10JoinThreadEb+36)
Process name:/system/bin/hiview
#05 pc 0000000000038d07(00000000004bcd07) /system/bin/hiview(_ZNSt3__h6vectorINS_9sub_matchINS_11__wrap_iterIPKcEEEENS_9allocatorIS6_EEE8__appendEj+596)
Tid:240, Name:hiview
#06 pc 0000000000028655(00000000004ac655) /system/bin/hiview
#00 pc 00098f8c /system/lib/ld-musl-arm.so.1(ioctl+68)
#07 pc 00000000000c2b08(00000000b6f7db08) /system/lib/ld-musl-arm.so.1(__libc_start_main+116)
#01 pc 0000e2a1 /system/lib/chipset-pub-sdk/libipc_single.z.so
#08 pc 00000000000285f4(00000000004ac5f4) /system/bin/hiview
#02 pc 0000ed59 /system/lib/chipset-pub-sdk/libipc_single.z.so
#09 pc 0000000000028580(00000000004ac580) /system/bin/hiview
#03 pc 0000ee1f /system/lib/chipset-pub-sdk/libipc_single.z.so
#04 pc 0000f745 /system/lib/chipset-pub-sdk/libipc_single.z.so
#05 pc 00037577 /system/bin/hiview
#06 pc 00025973 /system/bin/hiview
#07 pc 000db210 /system/lib/ld-musl-arm.so.1
#08 pc 000258d8 /system/bin/hiview
#09 pc 0002587c /system/bin/hiview
```
```
## Locating Faults Based on Crash Logs
## Locating Faults Based on the Crash Log
You can locate faults based on the crash stack logs generated by FaultLoggerd. This section describes how to use the addr2line tool to locate a crash fault.
You can locate faults based on the crash stack logs generated by Faultloggerd. This section describes how to use the addr2line tool to locate a crash fault.
1. Find a program crash or construct a crash.
1. Find a program crash or construct a crash.
For example, insert the following code into your code to trigger an invalid memory access fault (SIGSEGV).
For example, insert the following code into your code to trigger an invalid memory access fault (SIGSEGV).
...
@@ -233,35 +248,36 @@ You can locate faults based on the crash stack logs generated by FaultLoggerd. T
...
@@ -233,35 +248,36 @@ You can locate faults based on the crash stack logs generated by FaultLoggerd. T
cppcrash-pid-time
cppcrash-pid-time
```
```
The generated call stack is as follows:
The generated call stack information is as follows:
```
```
Timestamp:2017-08-05 17:35:03.000
Pid:816
Pid:816
Uid:0
Uid:0
Process name:./crasher
Process name:./crasher_c
Reason:Signal:SIGSEGV(SEGV_ACCERR)@0x0042d33d
Reason:Signal:SIGSEGV(SEGV_ACCERR)@0x0042d33d
Fault thread Info:
Fault thread Info:
Tid:816, Name:crasher
Tid:816, Name:crasher
#00 pc 0000332c /data/crasher(TriggerSegmentFaultException+15)(8bc37ceb8d6169e919d178fdc7f5449e)
#01 pc 000035c7 /data/crasher(ParseAndDoCrash+277)(8bc37ceb8d6169e919d178fdc7f5449e)
#02 pc 00003689 /data/crasher(main+39)(8bc37ceb8d6169e919d178fdc7f5449e)
#03 pc 000c3b08 /system/lib/ld-musl-arm.so.1(__libc_start_main+116)
#04 pc 000032f8 /data/crasher(_start_c+112)(8bc37ceb8d6169e919d178fdc7f5449e)
#05 pc 00003284 /data/crasher(_start+32)(8bc37ceb8d6169e919d178fdc7f5449e)
