diff --git a/en/application-dev/dfx/apprecovery-guidelines.md b/en/application-dev/dfx/apprecovery-guidelines.md index 4a82385816bd7f51ca0dadf85aff9961f84b94ca..cf31f6ae4c18f0de1e850cad5cb34be2122bc0d0 100644 --- a/en/application-dev/dfx/apprecovery-guidelines.md +++ b/en/application-dev/dfx/apprecovery-guidelines.md @@ -37,18 +37,15 @@ No error will be thrown if the preceding APIs are used in the troubleshooting sc ### Application State Management Since API version 10, application recovery is not limited to automatic restart in the case of an exception. Therefore, you need to understand when the application will load the saved state. - If the last exit of an application is not initiated by a user and a saved state is available for recovery, the startup reason is set to **APP_RECOVERY** when the application is started by the user next time, and the recovery state of the application is cleared. The application recovery status flag is set when **saveAppState** is actively or passively called. The flag is cleared when the application exits normally or the saved state is consumed. (A normal exit is usually triggered by pressing the back key or clearing recent tasks.) ![Application recovery status management](./figures/application_recovery_status_management.png) ### Application State Saving and Restore - API version 10 or later supports saving of the application state when an application is suspended. If a JsError occurs, **onSaveState** is called in the main thread. If an AppFreeze occurs, however, the main thread may be suspended, and therefore **onSaveState** is called in a non-main thread. The following figure shows the main service flow. ![Application recovery from the freezing state](./figures/application_recovery_from_freezing.png) - When the application is suspended, the callback is not executed in the JS thread. Therefore, you are advised not to use the imported dynamic Native library or access the **thread_local** object created by the main thread in the code of the **onSaveState** callback. ### Framework Fault Management @@ -62,13 +59,9 @@ Fault management is an important way for applications to deliver a better user e - Fault query is the process of calling APIs of [faultLogger](../reference/apis/js-apis-faultLogger.md) to obtain the fault information. The figure below does not illustrate the time when [faultLogger](../reference/apis/js-apis-faultLogger.md) is called. You can refer to the [LastExitReason](../reference/apis/js-apis-app-ability-abilityConstant.md#abilityconstantlastexitreason) passed during application initialization to determine whether to call [faultLogger](../reference/apis/js-apis-faultLogger.md) to query information about the previous fault. - ![Fault rectification process](./figures/fault_rectification.png) - It is recommended that you call [errorManager](../reference/apis/js-apis-app-ability-errorManager.md) to handle the exception. After the processing is complete, you can call the **saveAppState** API and restart the application. - If you do not register [ErrorObserver](../reference/apis/js-apis-inner-application-errorObserver.md) or enable application recovery, the application process will exit according to the default processing logic of the system. Users can restart the application from the home screen. - If you have enabled application recovery, the recovery framework first checks whether application state saving is supported and whether the application state saving is enabled. If so, the recovery framework invokes [onSaveState](../reference/apis/js-apis-app-ability-uiAbility.md#uiabilityonsavestate) of the [Ability](../reference/apis/js-apis-app-ability-uiAbility.md). Finally, the application is restarted. ### Supported Application Recovery Scenarios diff --git a/en/application-dev/dfx/figures/fault_rectification.png b/en/application-dev/dfx/figures/fault_rectification.png index e5831ac2b5aefc33a955ad98cd76f41ad28a7f70..a178b2691616d406d2668806ffcd4f89c8ca82a3 100644 Binary files a/en/application-dev/dfx/figures/fault_rectification.png and b/en/application-dev/dfx/figures/fault_rectification.png differ diff --git a/en/device-dev/subsystems/figures/process_crash_handling_flowchart.png b/en/device-dev/subsystems/figures/process_crash_handling_flowchart.png new file mode 100644 index 0000000000000000000000000000000000000000..65774b41cd4b6bc3c4f03c271fd0cefb9aec6d8d Binary files /dev/null and b/en/device-dev/subsystems/figures/process_crash_handling_flowchart.png differ diff --git a/en/device-dev/subsystems/subsys-dfx-faultlogger.md b/en/device-dev/subsystems/subsys-dfx-faultlogger.md index 209734174320846cc68004b82dfff89447df453b..f93b4ba889ade3d50331f759c1a99fabbbe0f7d7 100644 --- a/en/device-dev/subsystems/subsys-dfx-faultlogger.md +++ b/en/device-dev/subsystems/subsys-dfx-faultlogger.md @@ -4,108 +4,121 @@ ## Overview -### Function +### Function Introduction 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: -- 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. **Figure 1** Process crash handling flowchart -![process_crash_handling](figures/process_crash_handling.png) +![Process crash handling flowchart](figures/process_crash_handling_flowchart.png) -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 -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 -| 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).| -| Application suspension or high CPU usage| ProcessDump | See [Using ProcessDump to Obtain the Call Stack](#using-processdump-to-obtain-the-call-stack).| -| 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).| +| 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| DumpCatcher Command Tool | See [Using DumpCatcher Commands to Obtain Call Stack Information](#using-dumpcatcher-commands-to-obtain-call-stack-information).| +| 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 the Call Stack Information ### 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:
**true**: Back trace is successful. Related information is stored in the **msg** string object.
**false**: Back trace failed.
Input arguments:
**pid**: target process ID.
**tid**: target thread ID. If all threads in the process need to be back traced, set **tid** to **0**.
Output argument:
**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:
- **true**: Dumping of stack information is successful. Related information is stored in the msg string object.
- **false**: Dumping of stack information has failed.
Input arguments:
- **pid**: target process ID.
- **tid**: target thread ID. If all threads in the process need to be back traced, set **tid** to **0**.
Output arguments:
- **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:
- **true**: Dumping of stack information is successful. Related information is stored in the msg string object.
- **false**: Dumping of stack information has failed.
Input arguments:
**pid**: target process ID.
- **tid**: target thread ID. If all threads in the process need to be back traced, set **tid** to **0**.
Output arguments:
- **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:
- **true**: Dumping of stack information is successful. Related information is stored in the msg string object.
- **false**: Dumping of stack information has failed.
Input arguments:
**pid**: target process ID.
- **tid**: target thread ID. If all threads in the process need to be back traced, set **tid** to **0**.
- **fd**: handle of the file to be written.
Output parameters:
- **msg**: If back trace is successful, call stack information is returned through **msg**.| +| DfxDumpCatcher | bool DumpCatchMultiPid(const std::vector\ pidV, std::string& msg) | Return value:
- **true**: Dumping of stack information is successful. Related information is stored in the msg string object.
- **false**: Dumping of stack information has failed.
Input arguments:
- **pidV**: target process ID list.
Output arguments:
- **msg**: If back trace is successful, call stack information is returned through **msg**.| -> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**
-> 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. +> **NOTE** +> 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 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. -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. +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**. -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**. - ``` import("//base/hiviewdfx/faultloggerd/faultloggerd.gni") import("//build/ohos.gni") - + config("dumpcatcherdemo_config") { visibility = [ ":*" ] - + include_dirs = [ ".", "//utils/native/base/include", "//base/hiviewdfx/faultloggerd/interfaces/innerkits/dump_catcher/include/", # Add the path of the dump_catcher header file. ] } - - ohos_executable("dumpcatcherdemo") { sources = [ "dump_catcher_demo.cpp" ] configs = [ ":dumpcatcherdemo_config" ] 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" + + ohos_executable("dumpcatcherdemo") { + sources = [ "dump_catcher_demo.cpp" ] + configs = [ ":dumpcatcherdemo_config" ] + 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" } ``` 2. Define the header file. Take **/base/hiviewdfx/faultloggerd/example/dump_catcher_demo.h** as an example. In the sample code, the function of the stack depth test is called to construct a call stack with a specified depth. - + ``` #ifndef DUMP_CATCHER_DEMO_H #define DUMP_CATCHER_DEMO_H - + #include - + #define NOINLINE __attribute__((noinline)) - + // Define the macro function to automatically generate a function call chain. #define GEN_TEST_FUNCTION(FuncNumA, FuncNumB) \ __attribute__((noinline)) int TestFunc##FuncNumA() \ { \ return TestFunc##FuncNumB(); \ } - + // Call the function of the stack depth test. int TestFunc0(void); int TestFunc1(void); @@ -118,33 +131,33 @@ You can use DumpCatcher to obtain the call stack of a specified process (thread) int TestFunc8(void); int TestFunc9(void); int TestFunc10(void); - + #endif // DUMP_CATCHER_DEMO_H ``` 3. Call the **DumpCatch** API in the source file. Take **/base/hiviewdfx/faultloggerd/example/dump_catcher_demo.cpp** as an example. Include the **dfx_dump_catcher.h** file, declare the **DfxDumpCatcher** object, use the macro function to construct a function call chain, call the **DumpCatch** method, and pass the required process ID and thread ID of the call stack into this method. - + ``` #include "dump_catcher_demo.h" - + #include #include #include // Include the dfx_dump_catcher.h file. #include "dfx_dump_catcher.h" using namespace std; - + NOINLINE int TestFunc10(void) { OHOS::HiviewDFX::DfxDumpCatcher dumplog; 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) { cout << msg << endl; } return 0; } - + // Use the macro function to automatically generate a function call chain. GEN_TEST_FUNCTION(0, 1) GEN_TEST_FUNCTION(1, 2) @@ -156,7 +169,7 @@ You can use DumpCatcher to obtain the call stack of a specified process (thread) GEN_TEST_FUNCTION(7, 8) GEN_TEST_FUNCTION(8, 9) GEN_TEST_FUNCTION(9, 10) - + int main(int argc, char *argv[]) { TestFunc0(); @@ -165,55 +178,57 @@ 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 -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]
- processdump -p [pid] -t [tid] | **Arguments:**
**- -p [pid]**: prints stack information for all threads of the specified process.
**- -p [pid] -t [tid]**: prints information for the specified thread of the specified process.
**Return value:**
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]
- dumpcatcher -p [pid] -t [tid]
- dumpcatcher -m -p [pid]
- dumpcatcher -m -p [pid] -t [tid]
| **Description:**
- **-p [pid]**: prints all thread stack information of the specified process.
- **-p [pid] -t [tid]**: prints stack information for the specified thread of the specified process.
- **-m -p [pid]**: prints hybrid stack information for all threads of the specified process.
- **-m -p [pid] -t [tid]**: prints hybrid stack information for the specified thread of the specified process.
**Return value:**
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.| -> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**
-> 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. - ``` -# ps -A | grep hiview - 114 ? 00:00:00 hiview -# processdump -p 114 -t 114 -Tid:114, Name:hiview -#00 pc 0000000000089824(00000000b6f44824) /system/lib/ld-musl-arm.so.1(ioctl+68) -#01 pc 000000000002a709(00000000b6c56709) /system/lib/libipc_core.z.so(_ZN4OHOS15BinderConnector11WriteBinderEmPv+16) -#02 pc 000000000002ba75(00000000b6c57a75) /system/lib/libipc_core.z.so(_ZN4OHOS13BinderInvoker18TransactWithDriverEb+224) -#03 pc 000000000002bb37(00000000b6c57b37) /system/lib/libipc_core.z.so(_ZN4OHOS13BinderInvoker13StartWorkLoopEv+22) -#04 pc 000000000002c211(00000000b6c58211) /system/lib/libipc_core.z.so(_ZN4OHOS13BinderInvoker10JoinThreadEb+36) -#05 pc 0000000000038d07(00000000004bcd07) /system/bin/hiview(_ZNSt3__h6vectorINS_9sub_matchINS_11__wrap_iterIPKcEEEENS_9allocatorIS6_EEE8__appendEj+596) -#06 pc 0000000000028655(00000000004ac655) /system/bin/hiview -#07 pc 00000000000c2b08(00000000b6f7db08) /system/lib/ld-musl-arm.so.1(__libc_start_main+116) -#08 pc 00000000000285f4(00000000004ac5f4) /system/bin/hiview -#09 pc 0000000000028580(00000000004ac580) /system/bin/hiview +# ps -ef |grep hiview +hiview 240 1 0 17:01:49 ? 00:00:14 hiview +root 1822 1560 7 20:56:36 pts/0 00:00:00 grep hiview +# dumpcatcher -p 240 -t 240 +Result: 0 ( no error ) +Timestamp:2017-08-05 20:56:43.000 +Pid:240 +Uid:1201 +Process name:/system/bin/hiview +Tid:240, Name:hiview +#00 pc 00098f8c /system/lib/ld-musl-arm.so.1(ioctl+68) +#01 pc 0000e2a1 /system/lib/chipset-pub-sdk/libipc_single.z.so +#02 pc 0000ed59 /system/lib/chipset-pub-sdk/libipc_single.z.so +#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. For example, insert the following code into your code to trigger an invalid memory access fault (SIGSEGV). - + ``` NOINLINE int TriggerSegmentFaultException() { @@ -228,40 +243,41 @@ You can locate faults based on the crash stack logs generated by FaultLoggerd. T 2. Obtain the crash function call stack log. The process generates a temporary log file in the** /data/log/faultlog/temp** directory due to an exception that is not handled. The naming rule of the temporary log file is as follows: - + ``` 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 Uid:0 - Process name:./crasher + Process name:./crasher_c Reason:Signal:SIGSEGV(SEGV_ACCERR)@0x0042d33d Fault thread Info: 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) + Registers: r0:0042d33d r1:0000000b r2:1725d4c4 r3:b6f9fa84 r4:bec97e69 r5:b6fc0268 r6:0042d661 r7:bec97d60 r8:00000000 r9:00000000 r10:00000000 fp:bec97d20 ip:00000020 sp:bec97cd0 lr:b6f9fae4 pc:0042d32c - - #00 pc 000000000000332c(000000000042d32c) /data/crasher(TriggerSegmentFaultException+15) - #01 pc 00000000000035c7(000000000042d5c7) /data/crasher(ParseAndDoCrash+277) - #02 pc 0000000000003689(000000000042d689) /data/crasher(main+39) - #03 pc 00000000000c3b08(00000000b6fbbb08) /system/lib/ld-musl-arm.so.1(__libc_start_main+116) - #04 pc 00000000000032f8(000000000042d2f8) /data/crasher(_start_c+112) - #05 pc 0000000000003284(000000000042d284) /data/crasher(_start+32) ``` -3. Use the addr2line tool to analyze the call stack. +3. Use the addr2line tool to analyze the call stack information. Then, parse the line number based on the offset address. - + ``` - root:~/OpenHarmony/out/hi3516dv300/exe.unstripped/hiviewdfx/faultloggerd$ addr2line -e crasher 000332c + root:~/OpenHarmony/out/hi3516dv300/exe.unstripped/hiviewdfx/faultloggerd$ addr2line -e crasher 0000332c base/hiviewdfx/faultloggerd/tools/crasher/dfx_crasher.c:57 ``` diff --git a/en/device-dev/subsystems/subsys-dfx-hisysevent-logging-config.md b/en/device-dev/subsystems/subsys-dfx-hisysevent-logging-config.md index e6c0316c22cf0f0988f032218e92543c9f7b3acc..940b8188945ffdc01c6b35a44a27019339a69768 100644 --- a/en/device-dev/subsystems/subsys-dfx-hisysevent-logging-config.md +++ b/en/device-dev/subsystems/subsys-dfx-hisysevent-logging-config.md @@ -28,8 +28,7 @@ Constraints on the event domain, event name, and parameter - Zero or more event names can be defined for one event domain. The event names in the same event domain must be unique. -- Multiple parameters can be defined for one event name. The parameters in the same event name must be unique. There must be only one parameter named **__BASE** in each event name. See Table 1 for the fields of this parameter and Table 2 for the fields of other custom parameters. - +- Multiple parameters can be defined for one event name. The parameters in the same event name must be unique. There must be only one parameter named **\__BASE** in each event name. See Table 1 for the fields of this parameter and Table 2 for the fields of other custom parameters. **Table 1** Fields in the \__BASE parameter | Field| Description| @@ -47,8 +46,10 @@ Constraints on the event domain, event name, and parameter | arrsize | Length of the parameter of the array type. This field is optional.
Value:
1-100| | desc | Parameter description. This field is mandatory.
Rule:
The description contains 3 to 128 characters, including a to z, A to Z, 0 to 9, and underscores (_).| + ## How to Develop + ### Writing a YAML File diff --git a/en/device-dev/subsystems/subsys-dfx-hisysevent-overview.md b/en/device-dev/subsystems/subsys-dfx-hisysevent-overview.md index efd5de904fcdeed3d2467eb3c1b2f215e1ef4521..e1c5a61544b9413e3c36d46b86f5a789bad2e178 100644 --- a/en/device-dev/subsystems/subsys-dfx-hisysevent-overview.md +++ b/en/device-dev/subsystems/subsys-dfx-hisysevent-overview.md @@ -1,4 +1,4 @@ -# HiSysEvent Overview +# HiSysEvent ## Introduction diff --git a/en/device-dev/subsystems/subsys-dfx-hitracechain.md b/en/device-dev/subsystems/subsys-dfx-hitracechain.md index 9b9b85b66a457a0653b12f7d450f13f7aaef2a4f..f8a7c70451cf0b7b357492d7fd01ba9aca287e36 100644 --- a/en/device-dev/subsystems/subsys-dfx-hitracechain.md +++ b/en/device-dev/subsystems/subsys-dfx-hitracechain.md @@ -2,530 +2,235 @@ ## Overview -HiTraceChain tracks the call chain with the same **traceid** throughout the inter-device, inter-process, and inter-thread service processes. It associates and displays the call relationship and various output information during the entire process, helping you analyze and locate faults and optimize the system. +HiTraceChain tracks the call chain with the same **traceid** throughout the inter-device, inter-process, and inter-thread service processes. It associates and displays the call relationship and various output information during the entire process, helping you analyze and locate faults and optimize the system. -## Use Cases + +## When to Use HiTraceChain can be used for the following purposes: -- Associates and reports service process information \(such as logs and events\) on the device. +- Associates and reports service process information (such as logs and events) on the device. - Displays and analyzes reported information on the cloud to facilitate fault location. -- Works with the IDE to debug the detailed service process and time consumption distribution for system optimization. +- Works with the IDE to debug the detailed service process and time consumption distribution for system optimization. - **Figure 1** Use cases of HiTraceChain - + **Figure 1** Use cases of HiTraceChain ![](figures/use-cases-of-hitrace.png "use-cases-of-hitrace") ### Usage Example -**Figure 2** Service calling process \(inter-device and inter-process synchronous call\) + **Figure 2** Service calling process \(inter-device and inter-process synchronous call\) -![](figures/service-calling-process-(inter-device-and-inter-process-synchronous-call).png "service-calling-process-(inter-device-and-inter-process-synchronous-call)") + ![](figures/service-calling-process-(inter-device-and-inter-process-synchronous-call).png "service-calling-process-(inter-device-and-inter-process-synchronous-call)") 1. Display the call relationship in the service process, analyze key paths and function dependency, and determine the time consumption and call frequency at each call point to detect performance bottlenecks. - **Figure 3** Service calling process + **Figure 3** Service calling process + ![](figures/service-calling-process.png "service-calling-process") - ![](figures/service-calling-process.png "service-calling-process") - **Figure 4** Time delay in the service calling process + **Figure 4** Time delay in the service calling process + ![](figures/time-delay-in-the-service-calling-process.png "time-delay-in-the-service-calling-process") - ![](figures/time-delay-in-the-service-calling-process.png "time-delay-in-the-service-calling-process") +2. Add **traceid** to logs and events automatically to facilitate comprehensive analysis and quick fault location. -2. Add **traceid** to logs and events automatically to facilitate comprehensive analysis and quick fault location. ## Available APIs -HiTraceChain provides C++ and C APIs. The upper-layer services mainly use HiTraceChain to start and stop call chain tracing. +HiTraceChain provides C++ and C APIs. The upper-layer services mainly use HiTraceChain to start and stop call chain trace. + +HiTraceChain is implemented at layer C. It works by transferring **traceid** throughout the service calling process. Before service processing, HiTrace sets **traceid** in the thread local storage (TLS) of the calling thread. During service processing, HiTrace obtains **traceid** from the contextual TLS of the calling thread and automatically adds it to the log and event information. After service processing is complete, HiTrace clears **traceid** from the TLS of the calling thread. -HiTraceChain is implemented at layer C. It works by transferring **traceid** throughout the service calling process. Before service processing, HiTraceChain sets **traceid** in the thread local storage \(TLS\) of the calling thread. During service processing, HiTraceChain obtains **traceid** from the contextual TLS of the calling thread and automatically adds it to the log and event information. After service processing is complete, HiTraceChain clears **traceid** from the TLS of the calling thread. ### Java, C++, and C APIs -**Table 1** Description of C++ and C APIs - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  

C++

-

C

-

Class

-

API

-

API

-

HiTraceChain

-

-

-

-

-

-

-

-

HiTraceId Begin(const std::string& name, int flags)

-

HiTraceIdStruct HiTraceChainBegin(const char* name, int flags)

-

void End(const HiTraceId& id)

-

void HiTraceChainEnd(const HiTraceIdStruct* pId)

-

HiTraceId GetId();

-

HiTraceIdStruct HiTraceChainGetId()

-

void SetId(const HiTraceId& id)

-

void HiTraceChainSetId(const HiTraceIdStruct* pId)

-

void ClearId()

-

void HiTraceChainClearId()

-

HiTraceId CreateSpan()

-

HiTraceIdStruct HiTraceChainCreateSpan()

-

void Tracepoint(HiTraceTracepointType type, const HiTraceId& id, const char* fmt, ...)

-

void HiTraceChainTracepoint(HiTraceTracepointType type, const HiTraceIdStruct* pId, const char* fmt, ...)

-

void Tracepoint(HiTraceCommunicationMode mode, HiTraceTracepointType type, const HiTraceId& id, const char* fmt, ...)

-

void HiTraceChainTracepointEx(HiTraceCommunicationMode mode, HiTraceTracepointType type, const HiTraceIdStruct* pId, const char* fmt, ...)

-

HiTraceId

-

-

-

-

-

-

-

-

-

-

-

-

-

-

HiTraceId();

-

void HiTraceChainInitId(HiTraceIdStruct* pId)

-

HiTraceId(const uint8_t* pIdArray, int len)

-

HiTraceIdStruct HiTraceChainBytesToId(const uint8_t* pIdArray, int len)

-

bool IsValid()

-

int HiTraceChainIsValid(const HiTraceIdStruct* pId)

-

bool IsFlagEnabled(HiTraceFlag flag)

-

int HiTraceChainIsFlagEnabled(const HiTraceIdStruct* pId, HiTraceFlag flag)

-

void EnableFlag(HiTraceFlag flag)

-

void HiTraceChainEnableFlag(HiTraceIdStruct* pId, HiTraceFlag flag)

-

int GetFlags()

-

int HiTraceChainGetFlags(const HiTraceIdStruct* pId)

-

void SetFlags(int flags)

-

void HiTraceChainSetFlags(HiTraceIdStruct* pId, int flags)

-

uint64_t GetChainId()

-

uint64_t HiTraceChainGetChainId(const HiTraceIdStruct* pId)

-

void SetChainId(uint64_t chainId)

-

void HiTraceChainSetChainId(HiTraceIdStruct* pId, uint64_t chainId)

-

uint64_t GetSpanId()

-

uint64_t HiTraceChainGetSpanId(const HiTraceIdStruct* pId)

-

void SetSpanId(uint64_t spanId)

-

void HiTraceChainSetSpanId(HiTraceIdStruct* pId, uint64_t spanId)

-

uint64_t GetParentSpanId()

-

uint64_t HiTraceChainGetParentSpanId(const HiTraceIdStruct* pId)

-

void SetParentSpanId(uint64_t parentSpanId)

-

void HiTraceChainSetParentSpanId(HiTraceIdStruct* pId, uint64_t parentSpanId)

-

int ToBytes(uint8_t* pIdArray, int len)

-

int HiTraceChainIdToBytes(const HiTraceIdStruct* pId, uint8_t* pIdArray, int len)

-
+ **Table 1** Description of C++ and C APIs + +| | **C++** | **C** | +| -------- | -------- | -------- | +| **Class**| **Function**| **Function**| +| HiTraceChain | HiTraceId Begin(const std::string& name, int flags) | HiTraceIdStruct HiTraceChainBegin(const char* name, int flags) | +| | void End(const HiTraceId& id) | void HiTraceChainEnd(const HiTraceIdStruct* pId) | +| | HiTraceId GetId(); | HiTraceIdStruct HiTraceChainGetId() | +| | void SetId(const HiTraceId& id) | void HiTraceChainSetId(const HiTraceIdStruct* pId) | +| | void ClearId() | void HiTraceChainClearId() | +| | HiTraceId CreateSpan() | HiTraceIdStruct HiTraceChainCreateSpan() | +| | void Tracepoint(HiTraceTracepointType type, const HiTraceId& id, const char* fmt, ...) | void HiTraceChainTracepoint(HiTraceTracepointType type, const HiTraceIdStruct* pId, const char* fmt, ...) | +| | void Tracepoint(HiTraceCommunicationMode mode, HiTraceTracepointType type, const HiTraceId& id, const char* fmt, ...) | void HiTraceChainTracepointEx(HiTraceCommunicationMode mode, HiTraceTracepointType type, const HiTraceIdStruct* pId, const char* fmt, ...) | +| HiTraceId | HiTraceId(); | void HiTraceChainInitId(HiTraceIdStruct* pId) | +| | HiTraceId(const uint8_t* pIdArray, int len) | HiTraceIdStruct HiTraceChainBytesToId(const uint8_t* pIdArray, int len) | +| | bool IsValid() | int HiTraceChainIsValid(const HiTraceIdStruct* pId) | +| | bool IsFlagEnabled(HiTraceFlag flag) | int HiTraceChainIsFlagEnabled(const HiTraceIdStruct* pId, HiTraceFlag flag) | +| | void EnableFlag(HiTraceFlag flag) | void HiTraceChainEnableFlag(HiTraceIdStruct* pId, HiTraceFlag flag) | +| | int GetFlags() | int HiTraceChainGetFlags(const HiTraceIdStruct* pId) | +| | void SetFlags(int flags) | void HiTraceChainSetFlags(HiTraceIdStruct* pId, int flags) | +| | uint64_t GetChainId() | uint64_t HiTraceChainGetChainId(const HiTraceIdStruct* pId) | +| | void SetChainId(uint64_t chainId) | void HiTraceChainSetChainId(HiTraceIdStruct* pId, uint64_t chainId) | +| | uint64_t GetSpanId() | uint64_t HiTraceChainGetSpanId(const HiTraceIdStruct* pId) | +| | void SetSpanId(uint64_t spanId) | void HiTraceChainSetSpanId(HiTraceIdStruct* pId, uint64_t spanId) | +| | uint64_t GetParentSpanId() | uint64_t HiTraceChainGetParentSpanId(const HiTraceIdStruct* pId) | +| | void SetParentSpanId(uint64_t parentSpanId) | void HiTraceChainSetParentSpanId(HiTraceIdStruct* pId, uint64_t parentSpanId) | +| | int ToBytes(uint8_t* pIdArray, int len) | int HiTraceChainIdToBytes(const HiTraceIdStruct_ pId, uint8_t* pIdArray, int len) | + ### Parameters of C++ APIs -**Table 2** Parameters of C++ APIs - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Class

-

API

-

Description

-

HiTraceChain

-

-

-

-

-

-

-

-

HiTraceId Begin(const std::string& name, int flags)

-

Starts HiTraceChain, generates a HiTraceId object, and sets it in the TLS of the calling thread.

-

Input arguments:

-
  • name: Indicates the name of the service process.
  • flags: Indicates tracing flags, which can be used in combination.
    • HITRACE_FLAG_INCLUDE_ASYNC: Traces both synchronous and asynchronous calls. By default, only synchronous calls are traced.
    • HITRACE_FLAG_DONOT_CREATE_SPAN: Do not create a span. By default, a span is created.
    • HITRACE_FLAG_TP_INFO: Outputs the tracepoint information. By default, the information is not output.
    • HITRACE_FLAG_NO_BE_INFO: Do not output the start and end information. By default, the information is output.
    • HITRACE_FLAG_DONOT_ENABLE_LOG: Do not associate logs for output. By default, logs are associated for output.
    • HITRACE_FLAG_FAULT_TRIGGER: Triggers tracing by fault. By default, tracing is triggered normally.
    • HITRACE_FLAG_D2D_TP_INFO: Outputs the device-to-device tracepoint information. By default, the information is not output.
    • HITRCE_FLAG_DEFAULT: Indicates the default flag.
    -
  • Output arguments: none
  • Return value: Returns a valid HiTraceId object if call chain tracing is triggered successfully; returns an invalid object otherwise.
-

Note: In nested tracing mode, an invalid object will be returned if tracing is started at the nested layer.

-

void End(const HiTraceId& id)

-

Stops HiTraceChain based on the HiTraceId object returned by the Begin API, and clears the HiTraceId object in the TLS of the calling thread.

-

Input arguments:

-
  • id: Indicates the HiTraceId object.
-

Output arguments: none

-

Return value: none

-

HiTraceId GetId();

-

Obtains the HiTraceId object from the TLS of the calling thread.

-

Input arguments: none

-

Output arguments: none

-

Return value: Returns the HiTraceId object in the contextual TLS of the calling thread.

-

void SetId(const HiTraceId& id)

-

Purpose: Sets the HiTraceId object in the TLS of the calling thread.

-

Input arguments:

-
  • id: Indicates the HiTraceId object.
-

Output arguments: none

-

Return value: none

-

void ClearId()

-

Clears the HiTraceId object in the TLS of the current thread.

-

Input arguments: none

-

Output arguments: none

-

Return value: none

-

HiTraceId CreateSpan()

-

Obtains the span ID from the current HiTraceId object.

-

Input arguments: none

-

Output arguments: none

-

Return value: Returns the current span ID.

-

void Tracepoint(HiTraceTracepointType type, const HiTraceId& id, const char* fmt, ...)

-

Outputs HiTraceChain call chain information based on the information type. The information includes the timestamp and HiTraceId object information of the span.

-

Input arguments:

-
  • type: Indicates the information type. The options are as follows:
    • HITRACE_TP_CS: Client Send, which indicates the messages sent by the synchronous/asynchronous communication client.
    • HITRACE_TP_SR: Server Receive, which indicates the messages received by the server in synchronous/asynchronous communication.
    • HITRACE_TP_SS: Server Send, which indicates the response messages sent by the server in synchronous communication.
    • HITRACE_TP_CR: Client Receive, which indicates the response messages received by the synchronous communication client.
    • HITRACE_TP_GENERAL: Indicates the common output information.
    -
  • id: Indicates the ID of the current span.
  • fmt: Indicates the string describing the format variable parameter.
  • args: Indicates the variable parameter.
-

Output arguments: none

-

Return value: none

-

void Tracepoint(HiTraceCommunicationMode mode, HiTraceTracepointType type, const HiTraceId& id, const char* fmt, ...)

-

Outputs HiTraceChain call chain information based on the communication mode and information type. The information includes the timestamp and HiTraceId object information of the span.

-

Input arguments:

-
  • mode: Indicates the communication mode. The options are as follows:
    • HITRACE_CM_DEFAULT: default communication mode used when no communication mode is specified
    • HITRACE_CM_THREAD: inter-thread communication
    • HITRACE_CM_PROCESS: inter-process communication
    • HITRACE_CM_DEVICE: inter-device communication
    -
  • type: Indicates the information type. The options are as follows:
    • HITRACE_TP_CS: Client Send, which indicates the messages sent by the synchronous/asynchronous communication client.
    • HITRACE_TP_SR: Server Receive, which indicates the messages received by the server in synchronous/asynchronous communication.
    • HITRACE_TP_SS: Server Send, which indicates the response messages sent by the server in synchronous communication.
    • HITRACE_TP_CR: Client Receive, which indicates the response messages received by the synchronous communication client.
    • HITRACE_TP_GENERAL: Indicates the common output information.
    -
  • id: Indicates the ID of the current span.
  • fmt: Indicates the string describing the format variable parameter.
  • args: Indicates the variable parameter.
-

Output arguments: none

-

Return value: none

-

HiTraceId

-

-

-

-

-

-

-

-

-

-

-

-

-

-

HiTraceId();

-

Represents the default constructor used to generate an invalid HiTraceId object.

-

Input arguments: none

-

Output arguments: none

-

Return value: none

-

HiTraceId(const uint8_t* pIdArray, int len)

-

Represents the constructor used to create a HiTraceId object based on the specified byte array.

-
Input arguments:
  • pIdArray: Indicates the pointer to a byte array.
  • len: Indicates the length of the byte array.
-
-

Output arguments: none

-

Return value: none

-

bool IsValid()

-

Checks whether the HiTraceId object is valid.

-

Input arguments: none

-

Output arguments: none

-

Return value: Returns true if the HiTraceId object is valid; returns false otherwise.

-

bool IsFlagEnabled(HiTraceFlag flag)

-

Checks whether the tracing flag of the HiTraceId object is enabled.

-

Input arguments:

-
  • flag: Indicates the tracing flag. For details, see the description in the Begin function.
-

Output arguments: none

-

Return value: Returns true if the tracing flag is enabled; returns false otherwise.

-

void EnableFlag(HiTraceFlag flag)

-

Enables the tracing flag of the HiTraceId object.

-

Input arguments:

-
  • flag: Indicates the tracing flag. For details, see the description in the Begin function.
-

Output arguments: none

-

Return value: none

-

int GetFlags()

-

Obtains the tracing flag set in the HiTraceId object.

-

Input arguments: none

-

Output arguments: none

-

Return value: Returns the combination of tracing flags. For details, see the description in the Begin function.

-

void SetFlags(int flags)

-

Sets a tracing flag in the HiTraceId object.

-

Input arguments:

-
  • flags: Indicates the combination of tracing flags. For details, see the description in the Begin function.
-

Output arguments: none

-

Return value: none

-

uint64_t GetChainId()

-

Obtains the call chain ID.

-

Input arguments: none

-

Output arguments: none

-

Return value: Returns the call chain ID.

-

void SetChainId(uint64_t chainId)

-

Sets the call chain ID in the HiTraceId object.

-

Input arguments:

-
  • chainId: Indicates the call chain ID.
-

Output arguments: none

-

Return value: none

-

uint64_t GetSpanId()

-

Obtains the span ID from the current HiTraceId object.

-

Input arguments: none

-

Output arguments: none

-

Return value: Returns the current span ID.

-

void SetSpanId(uint64_t spanId)

-

Sets the span ID in the HiTraceId object.

-

Input arguments:

-
  • spanId: Indicates the span ID.
-

Output arguments: none

-

Return value: none

-

uint64_t GetParentSpanId()

-

Obtains the parent span ID from the current HiTraceId object.

-

Input arguments: none

-

Output arguments: none

-

Return value: Returns the parent span ID.

-

void SetParentSpanId(uint64_t parentSpanId)

-

Sets the parent span ID in the HiTraceId object.

-

Input arguments:

-
  • parentSpanId: Indicates the parent span ID.
-

Output arguments: none

-

Return value: none

-

int ToBytes(uint8_t* pIdArray, int len)

-

Converts the HiTraceId object into a byte array to facilitate caching or communication transfer.

-

Input arguments:

-
  • pIdArray: Indicates the pointer to a byte array. The minimum length of the byte array is HITRACE_ID_LEN.
  • len: Indicates the length of the byte array.
-

Output arguments

-
  • pIdArray: Indicates the pointer to a byte array. If the object is valid, the object data after conversion is stored.
-

Return value: Returns a value greater than 0 (indicating a valid array of object data) if the conversion is successful; returns 0 otherwise.

-
- -## Call Chain Processing - -Inter-device, inter-process, and inter-thread calls are implemented through the communication mechanism. **HiTraceChain** requires transfer of **traceid** in the communication mechanism. - -Some built-in communication mechanisms \(such as ZIDL\) of OpenHarmony already support the transfer of **traceid**. - -The following figure shows the process of transferring **traceid** in synchronous call. The process of transferring **traceid** in asynchronous call is similar. - -Extended communication mechanisms can also follow this implementation. - -**Figure 5** Call chain tracing in synchronous communication - -![](figures/call-chain-tracing-in-synchronous-communication.png "call-chain-tracing-in-synchronous-communication") + **Table 2** Trace flag combination types + +| **Name**| **Value**| **Description**| +| -------- | -------- | -------- | +| HITRACE_FLAG_DEFAULT | 0 | Default flag. | +| HITRACE_FLAG_INCLUDE_ASYNC | 1 | Asynchronous call flag. By default, only synchronous calls are traced. If this flag is set, both synchronous and asynchronous calls will be traced. | +| HITRACE_FLAG_DONOT_CREATE_SPAN | 1 << 1 | No span flag. By default, spans are created within a trace of synchronous and asynchronous service calls. If this flag is set, no spans are created. | +| HITRACE_FLAG_TP_INFO | 1 << 2 | Trace point flag. By default, no trace point is added when trace is enabled. This flag is used for debugging. If this flag is set, trace points will be automatically added on the TX and RX sides of synchronous and asynchronous calls to output trace point and timestamp information. Trace points are classified into four types: client send (CS), server receive (SR), server send (SS), and client receive (CR). For a synchronous call, the output trace points are CS, SR, SS, and CR; for an asynchronous call, the output trace points are CS, SR, and SS. | +| HITRACE_FLAG_NO_BE_INFO | 1 << 3 | No begin/end flag. By default, information about the start and end of the trace task is printed. If this flag is set, information about the start and end of the trace task will not be printed.| +| HITRACE_FLAG_DONOT_ENABLE_LOG | 1 << 4 | Log association flag. If this flag is set, information about the trace task will not be printed. | +| HITRACE_FLAG_FAULT_TRIGGER | 1 << 5 | Failure trigger flag. This flag is reserved for future use. | +| HITRACE_FLAG_D2D_TP_INFO | 1 << 6 | Device-to-device trace point flag. It is a subset of **TP_INFO**. If this flag is set, trace points are added only for call chain trace between devices.| + + **Table 3** Trace point types + +| **Name**| **Value**| **Description**| +| -------- | -------- | -------- | +| HITRACE_TP_CS | 0 | CS trace point. | +| HITRACE_TP_CR | 1 | CR trace point. | +| HITRACE_TP_SS | 2 | SS trace point. | +| HITRACE_TP_SR | 3 | SR trace point. | +| HITRACE_TP_GENERAL | 4 | General trace points except CS, CR, SS, and SR.| + + **Table 4** Communication modes + +| **Name**| **Value**| **Description**| +| -------- | -------- | -------- | +| HITRACE_CM_DEFAULT | 0 | Default communication mode. | +| HITRACE_CM_THREAD | 1 | Inter-thread communication. | +| HITRACE_CM_PROCESS | 2 | Inter-process communication. | +| HITRACE_CM_DEVICE | 3 | Inter-device communication. | + + **Table 5** Description of C++ APIs + +| **Class**| **API**| **Description**| +| -------- | -------- | -------- | +| HiTraceChain | HiTraceId Begin(const std::string& name, int flags) | Starts HiTraceChain, generates a **HiTraceId** object, and sets it in the TLS of the calling thread.
Input arguments:
- **name**: name of the service process.
- **flags**: trace flags, which can be used in combination. For details, see Table 2.
Output arguments: none
Return value: a valid **HiTraceId** object if call chain trace is triggered successfully; returns an invalid object otherwise.
Note: In nested trace mode, an invalid object will be returned if trace is started at the nested layer.| +| | void End(const HiTraceId& id) | Stops HiTraceChain based on the **HiTraceId** object returned by the **Begin** API, and clears the **HiTraceId** object in the TLS of the calling thread.
Input arguments:
- **id**: **HiTraceId** object.
Output arguments: none
Return value: none| +| | HiTraceId GetId(); | Obtains the **HiTraceId** object from the TLS of the calling thread.
Input arguments: none
Output arguments: none
Return value: **HiTraceId** object in the contextual TLS of the calling thread.| +| | void SetId(const HiTraceId& id) | Purpose: Sets the **HiTraceId** object in the TLS of the calling thread.
Input arguments:
- **id**: **HiTraceId** object.
Output arguments: none
Return value: none| +| | void ClearId() | Clears the **HiTraceId** object in the TLS of the calling thread.
Input arguments: none
Output arguments: none
Return value: none| +| | HiTraceId CreateSpan() | Obtains the span ID from the current **HiTraceId** object.
Input arguments: none
Output arguments: none
Return value: current span ID.| +| | void Tracepoint(HiTraceTracepointType type, const HiTraceId& id, const char* fmt, ...) | Outputs HiTraceChain trace point information based on the information type. The information includes the timestamp and **HiTraceId** object of the span.
Input arguments:
- **type**: trace point type. For details, see Table 3.
- **id**: ID of the current span.
- **fmt**: string describing the format variable parameter.
- **args**: variable parameter.
Output arguments: none
Return value: none| +| | void Tracepoint(HiTraceCommunicationMode mode, HiTraceTracepointType type, const HiTraceId& id, const char* fmt, ...) | Outputs HiTraceChain trace point information based on the communication mode and information type. The information includes the timestamp and **HiTraceId** object of the span.
Input arguments:
- **mode**: communication mode. For details, see Table 4.
- **type**: trace point type. For details, see Table 3.
- **id**: ID of the current span.
- **fmt**: string describing the format variable parameter.
- **args**: variable parameter.
Output arguments: none
Return value: none| +| HiTraceId | HiTraceId(); | Represents the default constructor used to generate an invalid **HiTraceId** object.
Input arguments: none
Output arguments: none
Return value: none| +| | HiTraceId(const uint8_t* pIdArray, int len) | Represents the constructor used to create a **HiTraceId** object based on the specified byte array.
Input arguments:
- **pIdArray**: pointer to a byte array.
- **len**: length of the byte array.
Output arguments: none
Return value: none| +| | bool IsValid() | Checks whether the **HiTraceId** object is valid.
Input arguments: none
Output arguments: none
Return value: **true** if the **HiTraceId** object is valid; **false** otherwise.| +| | bool IsFlagEnabled(HiTraceFlag flag) | Checks whether the trace flag of the **HiTraceId** object is enabled.
Input arguments:
- **flag**: trace flag. For details, see the description in the **Begin** function.
Output arguments: none
Return value: **true** if the trace flag is enabled; **false** otherwise.| +| | void EnableFlag(HiTraceFlag flag) | Enables the trace flag of the **HiTraceId** object.
Input arguments:
- **flag**: trace flag. For details, see the description in the **Begin** function.
Output arguments: none
Return value: none| +| | int GetFlags() | Obtains the trace flag set in the **HiTraceId** object.
Input arguments: none
Output arguments: none
Return value: Returns the combination of trace flags. For details, see the description in the **Begin** function.| +| | void SetFlags(int flags) | Sets a trace flag in the **HiTraceId** object.
Input arguments:
- **flags**: combination of trace flags. For details, see the description in the **Begin** function.
Output arguments: none
Return value: none| +| | uint64_t GetChainId() | Obtains the call chain ID.
Input arguments: none
Output arguments: none
Return value: call chain ID.| +| | void SetChainId(uint64_t chainId) | Sets the call chain ID in the **HiTraceId** object.
Input arguments:
- **chainId**: call chain ID.
Output arguments: none
Return value: none| +| | uint64_t GetSpanId() | Obtains the span ID from the current **HiTraceId** object.
Input arguments: none
Output arguments: none
Return value: current span ID.| +| | void SetSpanId(uint64_t spanId) | Sets the span ID in the **HiTraceId** object.
Input arguments:
- **spanId**: span ID.
Output arguments: none
Return value: none| +| | uint64_t GetParentSpanId() | Obtains the parent span ID from the current **HiTraceId** object.
Input arguments: none
Output arguments: none
Return value: parent span ID.| +| | void SetParentSpanId(uint64_t parentSpanId) | Sets the parent span ID in the **HiTraceId** object.
Input arguments:
- **parentSpanId**: parent span ID.
Output arguments: none
Return value: none| +| | int ToBytes(uint8_t* pIdArray, int len) | Converts the **HiTraceId** object into a byte array to facilitate caching or communication transfer.
Input arguments:
- **pIdArray**: pointer to a byte array. The minimum length of the byte array is **HITRACE_ID_LEN**.
- **len**: length of the byte array.
Output parameters:
- **pIdArray**: pointer to a byte array. If the object is valid, the object data after conversion is stored.
Return value: a value greater than **0** (indicating a valid array of object data) if the conversion is successful; **0** otherwise.| + + +### Call Chain Processing + +Inter-device, inter-process, and inter-thread calls are implemented through the communication mechanism. HiTraceChain requires transfer of **traceid** in the communication mechanism. + +Some built-in communication mechanisms (such as ZIDL) of OpenHarmony already support the transfer of **traceid**. + +The following figure shows the process of transferring **traceid** in synchronous call. The process of transferring **traceid** in asynchronous call is similar. + + Extended communication mechanisms can also follow this implementation. + **Figure 5** Call chain trace in synchronous communication + ![](figures/call-chain-trace-in-synchronous-communication.png "call-chain-trace-in-synchronous-communication") The process is as follows: -1. The service module on the client calls the **begin\(\)** function to start call chain tracing. -2. The service module on the client synchronously calls the **transact** function to the communication component on the client. -3. The communication component on the client performs the following: - 1. Obtains **traceid** from the TLS of the calling thread. - 2. Generates child **traceid**. - 3. Writes child **traceid** into the transaction data \(synchronous communication data\). - 4. Performs Client Send \(CS\) tracing. - 5. Sends communication data to the communication component on the server. - -4. On receiving the communication data, the communication component on the server performs the following: - 1. Obtains **traceid** from the data message package. - 2. Sets **traceid** in the TLS of the calling thread. - 3. Performs Server Receive \(SR\) tracing. - 4. Synchronously call the **onTransact** callback to the service module on the server. - -5. The service module on the server processes the service and sends the transact reply message carrying the processing result to the communication component. -6. The communication component on the server performs the following: - 1. Performs Server Send \(SS\) tracing. - 2. Sends communication data to the communication component on the client. - 3. Clears **traceid** from the TLS of the calling thread. - -7. On receiving the communication data, the communication component on the client performs the following: - 1. Performs Client Receive \(CR\) tracing. - 2. Sends a transact reply response to the service module on the client. - -8. The service module on the client processes the transact reply response. -9. When the process ends, the service module on the client calls the **end\(\)** function to stop call chain tracing. - -## How to Develop - -### C++ - -1. Develop the source code. +1. The service module on the client calls the **begin()** function to start call chain trace. - Include the **hitracechain** header file in the class definition header file or class implementation source file. For example: +2. The service module on the client synchronously calls the **transact** function to the communication component on the client. - ``` - #include "hitrace/tracechain.h" - ``` +3. The communication component on the client performs the following: + 1. Obtains **traceid** from the TLS of the calling thread. + 2. Generates child **traceid**. + 3. Writes child **traceid** into the transaction data (synchronous communication data). + 4. Performs CS trace. + 5. Sends communication data to the communication component on the server. - Add the code to start and stop call chain tracing in the class implementation source file. +4. On receiving the communication data, the communication component on the server performs the following: + 1. Obtains **traceid** from the data message package. + 2. Sets **traceid** in the TLS of the calling thread. + 3. Performs SR trace. + 4. Synchronously calls the **onTransact** callback to the service module on the server. - ``` - using namespace OHOS::HiviewDFX; - auto traceId = HiTraceChain::Begin("MyServiceFlow", HITRACE_FLAG_DEFAULT); - ... - HiTraceChain::End(traceId); - ``` +5. The service module on the server processes the service and sends the transact reply message carrying the processing result to the communication component. -2. Configure compilation information. Specifically, add the subsystem SDK dependency to **BUILD.gn**. +6. The communication component on the server performs the following: + 1. Performs SS trace. + 2. Sends communication data to the communication component on the client. + 3. Clears **traceid** from the TLS of the calling thread. - ``` - external_deps = [ "hiviewdfx:libhitracechain" ] - ``` +7. On receiving the communication data, the communication component on the client performs the following: + 1. Performs CR trace. + 2. Sends a transact reply response to the service module on the client. +8. The service module on the client processes the transact reply response. -### C +9. When the process ends, the service module on the client calls the **end()** function to stop call chain trace. -1. Develop the source code. - Include the **hitracechain** header file in the source file. - - ``` - #include "hitrace/tracechain.h" - ``` - - Add the code to start and stop call chain tracing in the class implementation source file. - - ``` - HiTraceIdStruct traceId = HiTraceChainBegin("MyServiceFlow", HITRACE_FLAG_DEFAULT); - ... - HiTraceChainEnd(traceId); - ``` - -2. Configure compilation information. Specifically, add the subsystem SDK dependency to **BUILD.gn**. - - ``` - external_deps = [ "hiviewdfx:libhitracechain" ] - ``` +## How to Develop +### **C++** + +1. Develop the source code. + Include the **hitracechain** header file in the class definition header file or class implementation source file. For example: + + ``` + #include "hitrace/tracechain.h" + ``` + + Add the code to start and stop call chain trace in the class implementation source file. + + ``` + using namespace OHOS::HiviewDFX; + auto traceId = HiTraceChain::Begin("MyServiceFlow", HITRACE_FLAG_DEFAULT); + ...... + HiTraceChain::End(traceId); + ``` + +2. Configure compilation information. Specifically, add the subsystem SDK dependency to **BUILD.gn**. + + ``` + external_deps = [ "hiviewdfx:libhitracechain" ] + ``` + + +### **C** + +1. Develop the source code. + Include the **hitracechain** header file in the source file. + + ``` + #include "hitrace/tracechain.h" + ``` + + Add the code to start and stop call chain trace in the class implementation source file. + + ``` + HiTraceIdStruct traceId = HiTraceChainBegin("MyServiceFlow", HITRACE_FLAG_DEFAULT); + ...... + HiTraceChainEnd(traceId); + ``` + +2. Configure compilation information. Specifically, add the subsystem SDK dependency to **BUILD.gn**. + + ``` + external_deps = [ "hiviewdfx:libhitracechain" ] + ``` diff --git a/en/device-dev/subsystems/subsys-dfx-hitracemeter.md b/en/device-dev/subsystems/subsys-dfx-hitracemeter.md index e80731582852658e6a65c6fc8f8d7cb66ca746a0..bb609b7369d03ae82b7782421c3ec96344bcc840 100644 --- a/en/device-dev/subsystems/subsys-dfx-hitracemeter.md +++ b/en/device-dev/subsystems/subsys-dfx-hitracemeter.md @@ -2,7 +2,7 @@ ## Introduction -HiTraceMeter is the OpenHarmony subsystem that provides APIs to implement call chain trace throughout a service process. With HiTraceMeter, you can quickly obtain the run log specific to the call chain of a service process and locate faults in inter-device, inter-process, or inter-thread communications. HiTraceMeter supports event logging in user mode and can collect trace data in user mode and kernel mode for performance tracing and analysis. +HiTraceMeter is the OpenHarmony subsystem that provides APIs to implement call chain trace throughout a service process. With HiTraceMeter, you can quickly obtain the run log specific to the call chain of a service process and locate faults in inter-device, inter-process, or inter-thread communications. HiTraceMeter supports event logging in user mode and can collect trace data in user mode and kernel mode for performance trace and analysis. ## Basic Concepts @@ -12,7 +12,7 @@ The HiTraceMeter subsystem consists of three parts: - hitrace CLI tool for data collection - smartperf tool for graphical data analysis -Wherein, HiTraceMeter APIs and the hitrace CLI tool run on the device side, and the smartperf tool runs on the PC side. HiTraceMeter APIs are provided in C++ and JS for event logging, which aims to generate the trace data necessary for performance tracing and analysis during the development process. +Wherein, HiTraceMeter APIs and the hitrace CLI tool run on the device side, and the smartperf tool runs on the PC side. HiTraceMeter APIs are provided in C++ and JS for event logging, which aims to generate the trace data necessary for performance trace and analysis during the development process. The hitrace CLI tool is used to collect trace data. It captures trace data flows and saves the data as a text file. @@ -348,4 +348,4 @@ You can set **-t** to **60** and **-b** to **204800** to increase the trace time # Reference -For details about HiTraceMeter, see [hiviewdfx_hitrace: Lightweight Distributed Tracing](https://gitee.com/openharmony/hiviewdfx_hitrace). +For details about HiTraceMeter, see [hiviewdfx_hitrace: Lightweight Distributed Trace](https://gitee.com/openharmony/hiviewdfx_hitrace). diff --git a/en/device-dev/subsystems/subsys-dfx-overview.md b/en/device-dev/subsystems/subsys-dfx-overview.md index b7487c10632d95533a94b29c78a340fbb808d17c..623ed60d365a662b8e11bb6b8489128481eabe2f 100644 --- a/en/device-dev/subsystems/subsys-dfx-overview.md +++ b/en/device-dev/subsystems/subsys-dfx-overview.md @@ -1,36 +1,47 @@ -# DFX Overview +# DFX Overview -[Design for X](https://en.wikipedia.org/wiki/Design_for_X) \(DFX\) refers to the software design that aims to improve the quality attributes in OpenHarmony. It mainly consists of two parts: design for reliability \(DFR\) and design for testability \(DFT\). + +## Introduction + +[Design for X](https://en.wikipedia.org/wiki/Design_for_X) \(DFX\) refers to the software design that aims to improve the quality attributes in OpenHarmony. It mainly consists of two parts: design for reliability \(DFR\) and design for testability \(DFT\). The DFX subsystem provides the following functions: -- HiLog: implements the logging function. It is applicable to mini-system devices \(reference memory ≥ 128 KiB\), small-system devices \(reference memory ≥ 1 MiB\), and standard-system devices \(reference memory ≥ 128 MB\). -- HiTraceChain: implements distributed call chain tracing. It is applicable to standard-system devices \(reference memory ≥ 128 MiB\). +- HiLog: implements the logging function. It is applicable to mini-system devices \(reference memory ≥ 128 KiB\), small-system devices \(reference memory ≥ 1 MiB\), and standard-system devices \(reference memory ≥ 128 MiB\). + +- HiTraceChain: implements distributed call chain trace. It is applicable to standard-system devices \(reference memory ≥ 128 MiB\). + - HiTraceMeter: implements performance trace. It is applicable to standard-system devices \(reference memory ≥ 128 MiB\). + - HiCollie: implements thread suspension detection. It is applicable to standard-system devices \(reference memory ≥ 128 MiB\). + - HiSysEvent: implements system event logging. It is applicable to standard-system devices \(reference memory ≥ 128 MiB\). + - HiDumper: exports system information. It is applicable to standard-system devices \(reference memory ≥ 128 MiB\). -- FaultLogger: implements crash detection. It is applicable to standard-system devices \(reference memory ≥ 128 MiB\). + +- Faultlogger: implements crash detection. It is applicable to standard-system devices \(reference memory ≥ 128 MiB\). + - Hiview: implements device maintenance across different platforms. It is applicable to standard-system devices \(reference memory ≥ 128 MiB\). -- HiAppEvent and HiChecker are only hap developer oriented。 + +- HiAppEvent and HiChecker are applicable only for HAP developers. ![dfx features overview](figure/dfx-overview.png) -## Basic Concepts +## Basic Concepts **Logging** Logging means to record the log information generated during system running so you can understand the running process and status of the system or applications. -**Distributed call chain tracing** +**Distributed call chain trace** -In a distributed system, the initiation of a service may involve multiple software modules, with control commands and data transmitted over intra-process, inter-process, and inter-device communication interfaces. To help you understand such complex communication processes and locate service faults efficiently, the DFX subsystem provides a distributed call chain tracing framework. +In a distributed system, the initiation of a service may involve multiple software modules, with control commands and data transmitted over intra-process, inter-process, and inter-device communication interfaces. To help you understand such complex communication processes and locate service faults efficiently, the DFX subsystem provides a distributed call chain trace framework. **Thread suspension detection** -If a thread is trapped in an infinite loop or the kernel state \(for example, Uninterruptable Sleep, Traced, Zombie, or synchronous wait\) when it is running, the thread cannot respond to normal service requests and cannot detect and recover from faults by itself. To detect and locate this type of faults, the DFX subsystem provides a simple watchdog mechanism by inserting detection probes to the process nodes that are prone to suspension. This ensures that suspension faults can be detected and logs can be collected. +If a thread is trapped in an infinite loop or the kernel state (for example, Uninterruptable Sleep, Traced, Zombie, or synchronous wait) when it is running, the thread cannot respond to normal service requests and cannot detect and recover from faults by itself. To detect and locate this type of faults, the DFX subsystem provides a simple watchdog mechanism by inserting detection probes to the process nodes that are prone to suspension. This ensures that suspension faults can be detected and logs can be collected. -**Event logging** +**Logging** Event logging means to collect and log events reported during system running. The log information will help you better analyze the product usage.