1# HiLog
2
3
4## 概述
5
6HiLog模块实现日志打印功能。
7
8开发者可以通过使用这些接口实现日志相关功能，输出日志时可以指定日志类型、所属业务领域、日志TAG标识、日志级别等。
9
10**系统能力：** SystemCapability.HiviewDFX.HiLog
11
12**起始版本：** 8
13
14
15## 汇总
16
17
18### 文件
19
20| 名称 | 描述 |
21| -------- | -------- |
22| [log.h](log_8h.md) | HiLog模块日志接口定义，通过这些接口实现日志打印相关功能。<br>**引用文件**：<hilog/log.h> <br>**库**：libhilog_ndk.z.so |
23
24
25### 宏定义
26
27| 名称 | 描述 |
28| -------- | -------- |
29| [LOG_DOMAIN](#log_domain)&nbsp;&nbsp;&nbsp;0 | 日志所对应的业务领域，用于标识业务的子系统、模块。 |
30| [LOG_TAG](#log_tag)&nbsp;&nbsp;&nbsp;NULL | 字符串常量，标识调用所在的类或者业务。 |
31| [OH_LOG_DEBUG](#oh_log_debug)(type, ...)&nbsp;&nbsp;&nbsp;((void)[OH_LOG_Print](#oh_log_print)((type), LOG_DEBUG, [LOG_DOMAIN](#log_domain), [LOG_TAG](#log_tag), \_\_VA_ARGS\_\_)) | DEBUG级别写日志，宏封装接口。 |
32| [OH_LOG_INFO](#oh_log_info)(type, ...)&nbsp;&nbsp;&nbsp;((void)[OH_LOG_Print](#oh_log_print)((type), LOG_INFO, [LOG_DOMAIN](#log_domain), [LOG_TAG](#log_tag), \_\_VA_ARGS\_\_)) | INFO级别写日志，宏封装接口。 |
33| [OH_LOG_WARN](#oh_log_warn)(type, ...)&nbsp;&nbsp;&nbsp;((void)[OH_LOG_Print](#oh_log_print)((type), LOG_WARN, [LOG_DOMAIN](#log_domain), [LOG_TAG](#log_tag), \_\_VA_ARGS\_\_)) | WARN级别写日志，宏封装接口。 |
34| [OH_LOG_ERROR](#oh_log_error)(type, ...)&nbsp;&nbsp;&nbsp;((void)[OH_LOG_Print](#oh_log_print)((type), LOG_ERROR, [LOG_DOMAIN](#log_domain), [LOG_TAG](#log_tag), \_\_VA_ARGS\_\_)) | ERROR级别写日志，宏封装接口。 |
35| [OH_LOG_FATAL](#oh_log_fatal)(type, ...)&nbsp;&nbsp;&nbsp;((void)HiLogPrint((type), LOG_FATAL, [LOG_DOMAIN](#log_domain), [LOG_TAG](#log_tag), \_\_VA_ARGS\_\_)) | FATAL级别写日志，宏封装接口。 |
36
37
38### 类型定义
39
40| 名称 | 描述 |
41| -------- | -------- |
42| typedef void(\* [LogCallback](#logcallback)) (const [LogType](#logtype) type, const [LogLevel](#loglevel) level, const unsigned int domain, const char \*tag, const char \*msg) | 函数指针，开发者自定义回调函数内容，在回调函数中，可自行对hilog日志进行处理。 |
43
44
45### 枚举
46
47| 名称 | 描述 |
48| -------- | -------- |
49| [LogType](#logtype) { LOG_APP = 0 } | 日志类型。 |
50| [LogLevel](#loglevel) {<br/>LOG_DEBUG = 3,<br/>LOG_INFO = 4,<br/>LOG_WARN = 5,<br/>LOG_ERROR = 6,<br/>LOG_FATAL = 7<br/>} | 日志级别。 |
51
52
53### 函数
54
55| 名称 | 描述 |
56| -------- | -------- |
57| int [OH_LOG_Print](#oh_log_print) ([LogType](#logtype) type, [LogLevel](#loglevel) level, unsigned int domain, const char \*tag, const char \*fmt,...) \_\_attribute\_\_((\_\_format\_\_(os_log | 写日志接口。 |
58| int bool [OH_LOG_IsLoggable](#oh_log_isloggable) (unsigned int domain, const char \*tag, [LogLevel](#loglevel) level) | 检查指定业务领域、TAG、级别的日志是否可以打印。 |
59| void [OH_LOG_SetCallback](#oh_log_setcallback) ([LogCallback](#logcallback) callback) | 注册函数。 |
60
61
62## 宏定义说明
63
64
65### LOG_DOMAIN
66
67```
68#define LOG_DOMAIN   0
69```
70
71**描述**
72
73日志所对应的业务领域，用于标识业务的子系统、模块。
74
7516进制整数，有效范围0x0~0xFFFF，超过自动截掉高位。
76
77**起始版本：** 8
78
79
80### LOG_TAG
81
82```
83#define LOG_TAG   NULL
84```
85
86**描述**
87
88字符串常量，标识调用所在的类或者业务。tag最多为31字节，超出后会截断，不建议使用中文字符，可能出现乱码或者对齐问题。
89
90**起始版本：** 8
91
92
93### OH_LOG_DEBUG
94
95```
96#define OH_LOG_DEBUG( type,  ... )   ((void)OH_LOG_Print((type), LOG_DEBUG, LOG_DOMAIN, LOG_TAG, __VA_ARGS__))
97```
98
99**描述**
100
101DEBUG级别写日志，宏封装接口。
102
103使用时需要先定义日志业务领域、日志TAG，一般在源文件起始处统一定义一次。
104
105**起始版本：** 8
106
107**参数:**
108
109| 名称 | 描述 |
110| -------- | -------- |
111| type | 日志类型，三方应用日志类型为LOG_APP。 |
112| fmt | 格式化字符串，基于类printf格式的增强，支持隐私参数标识，即在格式字符串每个参数中符号后类型前增加{public}、{private}标识。 |
113| ... | 与格式字符串里参数类型对应的参数列表，参数数目、参数类型必须与格式字符串中的标识一一对应。 |
114
115**参见：**
116
117[OH_LOG_Print](#oh_log_print)
118
119
120### OH_LOG_ERROR
121
122```
123#define OH_LOG_ERROR( type,  ... )   ((void)OH_LOG_Print((type), LOG_ERROR, LOG_DOMAIN, LOG_TAG, __VA_ARGS__))
124```
125
126**描述**
127
128ERROR级别写日志，宏封装接口。
129
130使用时需要先定义日志业务领域、日志TAG，一般在源文件起始处统一定义一次。
131
132**起始版本：** 8
133
134**参数:**
135
136| 名称 | 描述 |
137| -------- | -------- |
138| type | 日志类型，三方应用日志类型为LOG_APP。 |
139| fmt | 格式化字符串，基于类printf格式的增强，支持隐私参数标识，即在格式字符串每个参数中符号后类型前增加{public}、{private}标识。 |
140| ... | 与格式字符串里参数类型对应的参数列表，参数数目、参数类型必须与格式字符串中的标识一一对应。 |
141
142**参见：**
143
144[OH_LOG_Print](#oh_log_print)
145
146
147### OH_LOG_FATAL
148
149```
150#define OH_LOG_FATAL( type,  ... )   ((void)HiLogPrint((type), LOG_FATAL, LOG_DOMAIN, LOG_TAG, __VA_ARGS__))
151```
152
153**描述**
154
155FATAL级别写日志，宏封装接口。
156
157使用时需要先定义日志业务领域、日志TAG，一般在源文件起始处统一定义一次。
158
159**起始版本：** 8
160
161**参数:**
162
163| 名称 | 描述 |
164| -------- | -------- |
165| type | 日志类型，三方应用日志类型为LOG_APP。 |
166| fmt | 格式化字符串，基于类printf格式的增强，支持隐私参数标识，即在格式字符串每个参数中符号后类型前增加{public}、{private}标识。 |
167| ... | 与格式字符串里参数类型对应的参数列表，参数数目、参数类型必须与格式字符串中的标识一一对应。 |
168
169**参见：**
170
171[OH_LOG_Print](#oh_log_print)
172
173
174### OH_LOG_INFO
175
176```
177#define OH_LOG_INFO( type,  ... )   ((void)OH_LOG_Print((type), LOG_INFO, LOG_DOMAIN, LOG_TAG, __VA_ARGS__))
178```
179
180**描述**
181
182INFO级别写日志，宏封装接口。
183
184使用时需要先定义日志业务领域、日志TAG，一般在源文件起始处统一定义一次。
185
186**起始版本：** 8
187
188**参数:**
189
190| 名称 | 描述 |
191| -------- | -------- |
192| type | 日志类型，三方应用日志类型为LOG_APP。 |
193| fmt | 格式化字符串，基于类printf格式的增强，支持隐私参数标识，即在格式字符串每个参数中符号后类型前增加{public}、{private}标识。 |
194| ... | 与格式字符串里参数类型对应的参数列表，参数数目、参数类型必须与格式字符串中的标识一一对应。 |
195
196**参见：**
197
198[OH_LOG_Print](#oh_log_print)
199
200
201### OH_LOG_WARN
202
203```
204#define OH_LOG_WARN( type,  ... )   ((void)OH_LOG_Print((type), LOG_WARN, LOG_DOMAIN, LOG_TAG, __VA_ARGS__))
205```
206
207**描述**
208
209WARN级别写日志，宏封装接口。
210
211使用时需要先定义日志业务领域、日志TAG，一般在源文件起始处统一定义一次。
212
213**起始版本：** 8
214
215**参数:**
216
217| 名称 | 描述 |
218| -------- | -------- |
219| type | 日志类型，三方应用日志类型为LOG_APP。 |
220| fmt | 格式化字符串，基于类printf格式的增强，支持隐私参数标识，即在格式字符串每个参数中符号后类型前增加{public}、{private}标识。 |
221| ... | 与格式字符串里参数类型对应的参数列表，参数数目、参数类型必须与格式字符串中的标识一一对应。 |
222
223**参见：**
224
225[OH_LOG_Print](#oh_log_print)
226
227
228## 类型定义说明
229
230
231### LogCallback
232
233```
234typedef void(* LogCallback) (const LogType type, const LogLevel level, const unsigned int domain, const char *tag, const char *msg)
235```
236
237**描述**
238
239函数指针，开发者自定义回调函数内容，在回调函数中，可自行对hilog日志进行处理。
240
241**起始版本：** 11
242
243**参数:**
244
245| 名称 | 描述 |
246| -------- | -------- |
247| type | 日志类型，三方应用日志类型为LOG_APP。 |
248| level | 日志级别，日志级别包括LOG_DEBUG、LOG_INFO、LOG_WARN、LOG_ERROR、LOG_FATAL。 |
249| domain | 日志业务领域，16进制整数，范围0x0~0xFFFF。 |
250| tag | 日志TAG，字符串，标识调用所在的类或者业务。tag最多为31字节，超出后会截断，不建议使用中文字符，可能出现乱码或者对齐问题。 |
251| msg | 日志内容，格式化之后的日志字符串。 |
252
253
254## 枚举类型说明
255
256
257### LogLevel
258
259```
260enum LogLevel
261```
262
263**描述**
264
265日志级别。
266
267该枚举类型用于定义日志级别。各级别建议使用方式：
268
269DEBUG：比INFO级别更详细的流程记录，通过该级别的日志可以更详细地分析业务流程和定位分析问题。DEBUG级别的日志在正式发布版本中默认不会被打印，只有在调试版本或打开调试开关的情况下才会打印。
270
271INFO：用来记录业务关键流程节点，可以还原业务的主要运行过程；用来记录非正常情况信息，但这些情况都是可以预期的(如无网络信号、登录失败等)。这些日志都应该由该业务内处于支配地位的模块来记录，避免在多个被调用的模块或低级函数中重复记录。
272
273WARN：发生了较为严重的非预期情况，但是对用户影响不大，程序可以自动恢复或通过简单的操作就可以恢复的问题。
274
275ERROR：程序或功能发生了错误，该错误会影响功能的正常运行或用户的正常使用，可以恢复但恢复代价较高，如重置数据等。
276
277FATAL：重大致命异常，表明程序或功能即将崩溃，故障无法恢复。
278
279**起始版本：** 8
280
281| 枚举值 | 描述 |
282| -------- | -------- |
283| LOG_DEBUG | DEBUG日志级别，使用OH_LOG_DEBUG接口打印 |
284| LOG_INFO | INFO日志级别，使用OH_LOG_INFO接口打印 |
285| LOG_WARN | WARN日志级别，使用OH_LOG_WARN接口打印 |
286| LOG_ERROR | ERROR日志级别，使用OH_LOG_ERROR接口打印 |
287| LOG_FATAL | FATAL日志级别，使用OH_LOG_FATAL接口打印 |
288
289
290### LogType
291
292```
293enum LogType
294```
295
296**描述**
297
298日志类型。
299
300该枚举类型用于定义应用开发者可以使用的日志类型。当前有应用日志LOG_APP。
301
302**起始版本：** 8
303
304| 枚举值 | 描述 |
305| -------- | -------- |
306| LOG_APP | 应用日志 |
307
308
309## 函数说明
310
311
312### OH_LOG_IsLoggable()
313
314```
315int bool OH_LOG_IsLoggable (unsigned int domain, const char * tag, LogLevel level )
316```
317
318**描述**
319
320检查指定业务领域、TAG、级别的日志是否可以打印。
321
322**起始版本：** 8
323
324**参数:**
325
326| 名称 | 描述 |
327| -------- | -------- |
328| domain | 指定日志业务领域。 |
329| tag | 指定日志TAG。 |
330| level | 指定日志level。 |
331
332**返回：**
333
334如果指定domain、tag、level日志可以打印则返回true；否则返回false。
335
336
337### OH_LOG_Print()
338
339```
340int OH_LOG_Print (LogType type, LogLevel level, unsigned int domain, const char * tag, const char * fmt,  ... )
341```
342
343**描述**
344
345写日志接口。
346
347指定日志类型、日志级别、业务领域、TAG，按照类printf格式类型和隐私指示确定需要输出的变参。
348
349**起始版本：** 8
350
351**参数:**
352
353| 名称 | 描述 |
354| -------- | -------- |
355| type | 日志类型，三方应用日志类型为LOG_APP。 |
356| level | 日志级别，日志级别包括LOG_DEBUG、LOG_INFO、LOG_WARN、LOG_ERROR、LOG_FATAL。 |
357| domain | 日志业务领域，16进制整数，范围0x0~0xFFFF。 |
358| tag | 日志TAG，字符串，标识调用所在的类或者业务。 tag最多为31字节，超出后会截断，不建议使用中文字符，可能出现乱码或者对齐问题。|
359| fmt | 格式化字符串，基于类printf格式的增强，支持隐私参数标识，即在格式字符串每个参数中符号后类型前增加{public}、{private}标识。 |
360| ... | 与格式字符串里参数类型对应的参数列表，参数数目、参数类型必须与格式字符串中的标识一一对应。 |
361
362**返回：**
363
364大于等于0表示成功；小于0表示失败。
365
366
367### OH_LOG_SetCallback()
368
369```
370void OH_LOG_SetCallback (LogCallback callback)
371```
372
373**描述**
374
375注册函数。
376
377调用此函数后，用户实现的回调函数可以接收当前进程的所有hilog日志。 请注意，无论是否调用该接口，它都不会更改当前进程的hilog日志的默认行为。
378
379**起始版本：** 11
380
381**参数:**
382
383| 名称 | 描述 |
384| -------- | -------- |
385| callback | 用户实现的回调函数。如果不需要处理hilog日志，可以传输空指针。 |
386