1# Using HiLog (C/C++) 2 3<!--Kit: Performance Analysis Kit--> 4<!--Subsystem: HiviewDFX--> 5<!--Owner: @liuyifeifei;@buzhenwang--> 6<!--Designer: @shenchenkai--> 7<!--Tester: @liyang2235--> 8<!--Adviser: @foryourself--> 9 10During application development, you can log from your application's key code. Through logs, you can find out how the application is running. For example, the logs can tell you whether the application is running properly, and whether the code execution sequence and logic branch are correct. 11 12HiLog is a subsystem that provides logging for the system framework, services, and applications to record information on user operations and system running status. 13 14## Available APIs 15 16HiLog defines five log levels (DEBUG, INFO, WARN, ERROR, and FATAL) and provides APIs to output logs of different levels. For details about the APIs, see [HiLog](../reference/apis-performance-analysis-kit/capi-log-h.md). 17 18| API/Macro| Description| 19| -------- | -------- | 20| bool OH_LOG_IsLoggable(unsigned int domain, const char \*tag, LogLevel level) | Checks whether logs of the specified service domain, tag, and level can be printed.<br>This API returns **true** if the specified logs can be printed and returns **false** otherwise.| 21| int OH_LOG_Print(LogType type, LogLevel level, unsigned int domain, const char \*tag, const char \*fmt, ...) | Outputs logs of the specified domain, tag, and log level, with the variable parameters in the **printf** format.<br>If the return value is greater than or equal to 0, the operation is successful. Otherwise, the operation fails.| 22| int OH_LOG_PrintMsg(LogType type, LogLevel level, unsigned int domain, const char \*tag, const char \*message) | Outputs log strings of the specified domain, tag, and log level.<br>If the return value is greater than or equal to 0, the operation is successful. Otherwise, the operation fails.<br>Note: This API is supported since API version 18.| 23| int OH_LOG_PrintMsgByLen(LogType type, LogLevel level, unsigned int domain, const char \*tag, size_t tagLen, const char \*message, size_t messageLen) | Outputs the log string of the specified domain, tag, and log level, with the tag and string length specified.<br>If the return value is greater than or equal to 0, the operation is successful. Otherwise, the operation fails.<br>Note: This API is supported since API version 18.| 24| int OH_LOG_VPrint(LogType type, LogLevel level, unsigned int domain, const char \*tag, const char \*fmt, va_list ap) | Used in the same way as **OH_LOG_Print**, but the parameter list is **va_list**.<br>Note: This API is supported since API version 18.| 25| \#define OH_LOG_DEBUG(type, ...) ((void)OH_LOG_Print((type), LOG_DEBUG, LOG_DOMAIN, LOG_TAG, **VA_ARGS**)) | Outputs DEBUG logs. This is a function-like macro.| 26| \#define OH_LOG_INFO(type, ...) ((void)OH_LOG_Print((type), LOG_INFO, LOG_DOMAIN, LOG_TAG, **VA_ARGS**)) | Outputs INFO logs. This is a function-like macro.| 27| \#define OH_LOG_WARN(type, ...) ((void)OH_LOG_Print((type), LOG_WARN, LOG_DOMAIN, LOG_TAG, **VA_ARGS**)) | Outputs WARN logs. This is a function-like macro.| 28| \#define OH_LOG_ERROR(type, ...) ((void)OH_LOG_Print((type), LOG_ERROR, LOG_DOMAIN, LOG_TAG, **VA_ARGS**)) | Outputs ERROR logs. This is a function-like macro.| 29| \#define OH_LOG_FATAL(type, ...) ((void)OH_LOG_Print((type), LOG_FATAL, LOG_DOMAIN, LOG_TAG, **VA_ARGS**)) | Outputs FATAL logs. This is a function-like macro.| 30| void OH_LOG_SetCallback(LogCallback callback) | Registers a callback function to return all logs for the process.| 31| void OH_LOG_SetMinLogLevel(LogLevel level) | Sets the minimum log level.<br>Note: This API is supported since API version 15.<br>Note: If the set log level is lower than the [global log level](hilog.md#displaying-and-setting-log-levels), the setting does not take effect.| 32 33### Parameters 34 35- **domain**: service domain of logs. The value range is 0x0000 to 0xFFFF. You can define the value as required. 36 37- **tag**: log identifier. It can be any string. You are advised to use this parameter to identify the class or service behavior of a method call. A tag can contain a maximum of 31 bytes. If a tag exceeds this limit, it will be truncated. Chinese characters are not recommended because garbled characters or alignment problems may occur. 38 39- **level**: log level. For details, see [LogLevel](../reference/apis-performance-analysis-kit/capi-log-h.md#loglevel). 40 41- **fmt**: format of the log to output. The value is a string in the "%{private flag}specifier" format. 42 43 | Private Flag| Description| 44 | -------- | -------- | 45 | private | The output is **\<private>**, which indicates that the log information is invisible.| 46 | public | The log information is displayed.| 47 | Not specified| The default value **\<private>** is used.| 48 49 | Specifier| Description| Example| 50 | -------- | -------- | -------- | 51 | d/i | The **number** and **bool** types can be printed.| 123 | 52 | s | The char\* type can be printed.| "123" | 53 54 You can set multiple parameters in the **format** string, for example, **%s World**, where **%s** is a variable of the string type and its value is defined by **args**. 55 56- **args**: parameters of the types specified by **specifier** in **format**. This parameter can be left blank. The number and type of parameters must match **specifier**. 57 58> **NOTE** 59> 60> - The domains, tags, and levels specified in **OH_LOG_IsLoggable()** and **OH_LOG_Print()** must be the same. 61> 62> - **OH_LOG_IsLoggable()** returns **true** if the specified logs can be printed; returns **false** otherwise. 63> For debug applications, all log levels can be printed. 64> 65> For release applications, logs are printed only if the log level is not lower than the global log level. 66> 67> During debugging, you can change the log level. For details, see [Displaying and Setting Log Levels](hilog.md#displaying-and-setting-log-levels). 68 69## Constraints 70 71The maximum size of a log file is 4096 bytes. Excess content will be discarded. 72 73## How to Develop 74 751. Add the link of **libhilog_ndk.z.so** to **CMakeLists.txt**. 76 77 ```txt 78 target_link_libraries(entry PUBLIC libhilog_ndk.z.so) 79 ``` 80 812. Include the **hilog** header file in the source file, and define the **domain** and **tag** macros. 82 83 ```c++ 84 #include "hilog/log.h" 85 ``` 86 87 ```c++ 88 #undef LOG_DOMAIN 89 #undef LOG_TAG 90 #define LOG_DOMAIN 0x3200 // Global domain, which identifies the service domain. 91 #define LOG_TAG "MY_TAG" // Global tag, which identifies the module log tag. 92 ``` 93 943. Print logs. 95 96 ```c++ 97 OH_LOG_INFO(LOG_APP, "Failed to visit %{private}s, reason:%{public}d.", url, errno); 98 // Set the minimum log level to Warn. 99 OH_LOG_SetMinLogLevel(LOG_WARN); 100 OH_LOG_INFO(LOG_APP, "this is an info level log"); 101 OH_LOG_ERROR(LOG_APP, "this is an error level log"); 102 ``` 103 1044. The output is as follows: 105 106<!--RP2--> 107 ```txt 108 01-02 08:39:38.915 9012-9012 A03200/MY_TAG com.example.hilogDemo I Failed to visit <private>, reason:11. 109 01-02 08:39:38.915 9012-9012 A03200/MY_TAG com.example.hilogDemo E this is an error level log 110 ``` 111<!--RP2End--> 112 113### Registering a Log Callback 114 115> **NOTE** 116> 117> Do not call the HiLog API recursively in the callback function. Otherwise, a cyclic call issue occurs. 118 119```c++ 120#include "hilog/log.h" 121 122// Customize a callback for processing logs. 123void MyHiLog(const LogType type, const LogLevel level, const unsigned int domain, const char *tag, const char *msg) 124{ 125 // Define how to handle your logs, such as redirect/filter. 126 // Note: Do not call the HiLog API recursively in the callback function. Otherwise, a cyclic call issue occurs. 127} 128 129static void Test(void) 130{ 131 // 1. Register a callback. 132 OH_LOG_SetCallback(MyHiLog); 133 134 // 2. Call the hilog API to print logs. Logs are output to HiLog and returned to MyHiLog() through the registered callback. Then, MyHiLog() is called to process the logs. 135 OH_LOG_INFO(LOG_APP, "hello world"); 136} 137``` 138