1# Using HiLog (C/C++)
2
3During 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.
4
5HiLog is a subsystem that provides logging for the system framework, services, and applications to record information on user operations and system running status.
6
7## Available APIs
8
9HiLog 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/_hi_log.md)).
10
11| API/Macro| Description|
12| -------- | -------- |
13| 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.|
14| 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>This API returns the total number of bytes if log printing is successful and returns **-1** otherwise.|
15| \#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.|
16| \#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.|
17| \#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.|
18| \#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.|
19| \#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.|
20| void OH_LOG_SetCallback(LogCallback callback) | Registers a callback function to return all logs for the process.|
21
22### Parameters
23
24> **NOTE**
25>
26> The domains, tags, and levels specified in **OH_LOG_IsLoggable()** and **OH_LOG_Print()** must be the same.
27
28- **domain**: service domain of logs. The value range is 0x0000 to 0xFFFF. You can define the value as required.
29
30- **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 contains more than 31 bytes, it will be truncated. Chinese characters are not recommended because garbled characters or alignment problems may occur.
31
32- **level**: log level. For details about the value, see [LogLevel](../reference/apis-performance-analysis-kit/_hi_log.md#loglevel).
33
34- **fmt**: format of the log to output. The value is a string in the "%{private flag}specifier" format.
35  | Private Flag| Description|
36  | -------- | -------- |
37  | private | The output is **\<private>**, which indicates that the log information is invisible.|
38  | public | The log information is displayed.|
39  | Not specified| The default value **\<private>** is used.|
40
41  | Specifier| Description| Example|
42  | -------- | -------- | -------- |
43  | d/i | Prints logs of the **number**, **bool**, and **bigint** types.| 123 |
44  | s | Prints logs of the **string**, **undefined**, and **null** types.| "123" |
45
46  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**. <!--Del-->
47
48  To display the log masked by {**private**} in debugging, run the **hilog -p off** command.
49<!--DelEnd-->
50
51- **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**.
52
53## Constraints
54
55The maximum size of a log file is 4096 bytes. Excess content will be discarded.
56
57## How to Develop
58
591. Add the link of **libhilog_ndk.z.so** to **CMakeLists.txt**.
60
61   ```
62   target_link_libraries(entry PUBLIC libhilog_ndk.z.so)
63   ```
64
652. Include the **hilog** header file in the source file, and define the **domain** and **tag** macros.
66
67   ```c++
68   #include "hilog/log.h"
69   ```
70
71   ```c++
72   #undef LOG_DOMAIN
73   #undef LOG_TAG
74   #define LOG_DOMAIN 0x3200 // Global domain, which identifies the service domain.
75   #define LOG_TAG "MY_TAG" // Global tag, which identifies the module log tag.
76   ```
77
783. Print logs, for example, print ERROR logs.
79
80   ```c++
81   OH_LOG_ERROR(LOG_APP, "Failed to visit %{private}s, reason:%{public}d.", url, errno);
82   ```
83
844. The output is as follows:
85
86   ```
87   12-11 12:21:47.579  2695 2695 E A03200/MY_TAG: Failed to visit <private>, reason:11.
88   ```
89
90### Registering a Log Callback
91
92> **Note**
93>
94> The hilog APIs cannot be called in the callback to print logs. Otherwise, an infinite loop occurs.
95
96```c++
97#include "hilog/log.h"
98static constexpr OHOS::HiviewDFX::HiLogLabel LABEL = {LOG_CORE, 0xD003200, "MY_TAG"};
99
100// Customize a callback for processing logs.
101void MyHiLog(const LogType type, const LogLevel level, const unsigned int domain, const char *tag, const char *msg)
102{
103    // Define how to handle your logs, such as redirect/filter.
104    // Note: Do not call the hilog APIs in the callback to print logs. Otherwise, an infinite loop occurs.
105}
106
107static void Test(void)
108{
109   // 1. Register a callback.
110    OH_LOG_SetCallback(MyHiLog);
111
112   // 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.
113   HiLog::Info(LABEL, "hello world");
114}
115```
116