README.md
1# HiLog<a name="EN-US_TOPIC_0000001115694144"></a>
2
3- [Introduction](#section11660541593)
4- [Directory Structure](#section161941989596)
5- [Constraints](#section119744591305)
6- [Usage](#section06487425716)
7 - [Available APIs](#section1551164914237)
8 - [Usage Guidelines](#section129654513264)
9
10- [Repositories Involved](#section177639411669)
11
12## Introduction<a name="section11660541593"></a>
13
14HiLog is the module of OpenHarmony that logs information such as user operations and system running status for the system framework, services, and applications.
15
16**Figure 1** Architecture of the HiLog module<a name="fig4460722185514"></a>
17
18
19
20
21User-space processes write logs to the ring buffer of hilogd through the log API. hilogd sends logs to the console for viewing or writes logs to the flash at the request of the hilog.
22
23The details are as follows:
24
25- **hilogd**: log service in the user space
26
271. hilogd is a resident service and is enabled by default when the system is started.
282. User-space processes call the log APIs to transfer the formatted log content to hilogd and store the content in its ring buffer.
29
30- **hilog**: command line tool for viewing logs
31
321. hilog reads the log content from the ring buffer of hilogd, filters the content if required, and then prints the content to the standard output.
33
34Supported functions:
35
36- Formatting of parameter privacy identifiers \(See the following example for details.\)
37- Flow control on excess log processes
38- Flow control on excess domains \(subsystems or modules\) involved in log printing
39- Log compression and flushing
40
41## Directory Structure<a name="section161941989596"></a>
42
43```
44/base/hiviewdfx/hilog
45├── frameworks # Framework code
46│ └── native # HiLog Native implementation code
47├── interfaces # APIs
48│ └── native # External C/C++ APIs
49│ └── innerkits # Header files opened to internal subsystems
50│ └── kits # Header files opened to applications
51│ └── js # External js APIs
52├── services
53│ └── hilogd # HiLog resident service implementation
54│ └── hilogtool # HiLog tool implementation
55```
56
57## Constraints<a name="section119744591305"></a>
58
59Clang 8.0.0 or later is required.
60
61## Usage<a name="section06487425716"></a>
62
63### Available APIs<a name="section1551164914237"></a>
64
65**Table 1** Major APIs of HiLog
66
67<a name="table5489165165714"></a>
68<table><thead align="left"><tr id="row12490195195718"><th class="cellrowborder" valign="top" width="14.09%" id="mcps1.2.4.1.1"><p id="p862411212488"><a name="p862411212488"></a><a name="p862411212488"></a><strong id="b68190161218"><a name="b68190161218"></a><a name="b68190161218"></a>Class</strong></p>
69</th>
70<th class="cellrowborder" valign="top" width="33.98%" id="mcps1.2.4.1.2"><p id="p10859172921116"><a name="p10859172921116"></a><a name="p10859172921116"></a>Method</p>
71</th>
72<th class="cellrowborder" valign="top" width="51.93%" id="mcps1.2.4.1.3"><p id="p104901150576"><a name="p104901150576"></a><a name="p104901150576"></a>Description</p>
73</th>
74</tr>
75</thead>
76<tbody><tr id="row34901758577"><td class="cellrowborder" valign="top" width="14.09%" headers="mcps1.2.4.1.1 "><p id="p16501115918497"><a name="p16501115918497"></a><a name="p16501115918497"></a>HiLogLabel</p>
77</td>
78<td class="cellrowborder" valign="top" width="33.98%" headers="mcps1.2.4.1.2 "><p id="p1550175974917"><a name="p1550175974917"></a><a name="p1550175974917"></a>HiLogLabel(int type, int domain, String tag)</p>
79</td>
80<td class="cellrowborder" valign="top" width="51.93%" headers="mcps1.2.4.1.3 "><p id="p135021859104915"><a name="p135021859104915"></a><a name="p135021859104915"></a>Constructs a log label, including the log type, domain, and tag.</p>
81</td>
82</tr>
83<tr id="row868117162916"><td class="cellrowborder" valign="top" width="14.09%" headers="mcps1.2.4.1.1 "><p id="p1215914385013"><a name="p1215914385013"></a><a name="p1215914385013"></a>HiLog</p>
84</td>
85<td class="cellrowborder" valign="top" width="33.98%" headers="mcps1.2.4.1.2 "><p id="p1415914345011"><a name="p1415914345011"></a><a name="p1415914345011"></a>Info(const HiLogLabel &label, const char *fmt, ...)</p>
86</td>
87<td class="cellrowborder" valign="top" width="51.93%" headers="mcps1.2.4.1.3 "><p id="p1274814305510"><a name="p1274814305510"></a><a name="p1274814305510"></a>Prints logs of the info level.</p>
88</td>
89</tr>
90</tbody>
91</table>
92
93### Usage Guidelines<a name="section129654513264"></a>
94
951. View logs.
96
97Run the **hilog | grep "MY\_TAG"** command in shell mode.
98
99```
100Output in debug mode:
10101-26 11:01:06.870 1051 1051 W 00201/test: Failed to visit [https://gitee.com/openharmony](https://gitee.com/openharmony), reason:503.
102Output in release mode:
10301-26 11:01:06.870 1051 1051 W 00201/test: Failed to visit <private>, reason:503.
104```
105
106## Repositories Involved<a name="section177639411669"></a>
107
108[DFX subsystem](https://gitee.com/openharmony/docs/blob/master/en/readme/dfx.md)
109
110[hiviewdfx\_hiview](https://gitee.com/openharmony/hiviewdfx_hiview/blob/master/README.md)
111
112**hiviewdfx\_hilog**
113
114[hiviewdfx\_hiappevent](https://gitee.com/openharmony/hiviewdfx_hiappevent/blob/master/README.md)
115
116[hiviewdfx\_hisysevent](https://gitee.com/openharmony/hiviewdfx_hisysevent/blob/master/README.md)
117
118[hiviewdfx\_faultloggerd](https://gitee.com/openharmony/hiviewdfx_faultloggerd/blob/master/README.md)
119
120[hiviewdfx\_hilog\_lite](https://gitee.com/openharmony/hiviewdfx_hilog_lite/blob/master/README.md)
121
122[hiviewdfx\_hievent\_lite](https://gitee.com/openharmony/hiviewdfx_hievent_lite/blob/master/README.md)
123
124[hiviewdfx\_hiview\_lite](https://gitee.com/openharmony/hiviewdfx_hiview_lite/blob/master/README.md)
125
126
README_zh.md
1# HiLog组件<a name="ZH-CN_TOPIC_0000001115694144"></a>
2
3- [HiLog组件<a name="ZH-CN_TOPIC_0000001115694144"></a>](#hilog组件)
4 - [简介<a name="section11660541593"></a>](#简介)
5 - [目录<a name="section161941989596"></a>](#目录)
6 - [约束<a name="section119744591305"></a>](#约束)
7 - [说明<a name="section06487425716"></a>](#说明)
8 - [接口说明<a name="section1551164914237"></a>](#接口说明)
9 - [使用说明<a name="section129654513264"></a>](#使用说明)
10 - [涉及仓<a name="section177639411669"></a>](#涉及仓)
11
12- [涉及仓](#section177639411669)
13
14## 简介<a name="section11660541593"></a>
15
16HiLog是OpenHarmony日志系统，提供给系统框架、服务、以及应用打印日志，记录用户操作、系统运行状态等。
17
18**图 1** HiLog架构图<a name="fig4460722185514"></a>
19
20
21
22
23用户态Process通过日志接口将日志内容写入hilogd buffer中，用户态的hilog工具支持将日志输出到控制台（console）进行查看，同时也支持通过hilog工具给hilogd发送命令将日志落盘。
24
25下述主要任务的详细内容：
26
27- hilogd是流水日志的用户态服务。
28
291. 此功能是常驻服务，在研发版本系统启动时默认启动。
302. 当用户态模块调用日志接口，将格式化好的日志内容传输给该任务，并将其存储在一个环形缓冲区中 。
31
32- hilog日志查看命令行工具
33
341. 从hilogd读取ringbuffer内容，输出到标准输出，可支持日志过滤。
35
36支持特性：
37
38- 支持参数隐私标识格式化（详见下面举例）。
39- 支持对超标日志打印进程流控。
40- 支持对超标日志打印domain\(标识子系统/模块\)流控。
41- 支持流压缩落盘。
42
43## 目录<a name="section161941989596"></a>
44
45```
46/base/hiviewdfx/hilog
47├── frameworks # 框架代码
48│ └── native # HiLog native实现代码
49├── interfaces # 接口
50│ └── native # 对外C/C++接口
51│ └── innerkits # 对内部子系统暴露的头文件
52│ └── kits # 对应用暴露的头文件
53│ └── js # 对外js接口
54├── services
55│ └── hilogd # 日志常驻服务实现
56│ └── hilogtool # 日志工具实现
57```
58
59## 约束<a name="section119744591305"></a>
60
61依赖 Clang 编译器\(**Clang** 8.0.0 \)及以上。
62
63## 说明<a name="section06487425716"></a>
64
65### 1、日志打印及显示<a name="section1551164914237"></a>
66
67js接口: https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis-performance-analysis-kit/js-apis-hilog.md
68
69ndk接口: https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/dfx/hilog-guidelines-ndk.md
70
71日志打印格式：
72```
73日期 时间 进程号 线程号 日志级别 domainID/日志标签: 日志内容
74```
75如下所示，这是一条domainID为0x3200和标签是"testTag"的info级别的日志：
76```
7704-19 17:02:14.735 5394 5394 I A00032/testTag: this is a info level hilog
78```
79说明：
80- 日志级别：I表示Info级别，其余级别参考日志等级首字母。
81- domainID：A003200中A表示应用日志，3200表示domainID为0x3200，domainID具体定义详见接口指导。
82
83### 2、日志配置
84
85#### （1）日志等级
86 **说明**： 日志级别要符合日志内容的实际级别，日志级别说明如下：
87
88**FATAL**：重大致命异常，表明程序或功能即将崩溃，故障无法恢复。
89
90**ERROR**：程序或功能发生了错误，该错误会影响功能的正常运行或用户的正常使用，可以恢复但恢复代价较高，如重置数据等。
91
92**WARN**：发生了较为严重的非预期情况，但是对用户影响不大，程序可以自动恢复或通过简单的操作就可以恢复的问题。
93
94**INFO**：用来记录业务关键流程节点，可以还原业务的主要运行过程；用来记录非正常情况信息，但这些情况都是可以预期的(如无网络信号、登录失败等)。这些日志都应该由该业务内处于支配地位的模块来记录，避免在多个被调用的模块或低级函数中重复记录。
95
96**DEBUG**：比INFO级别更详细的流程记录，通过该级别的日志可以更详细地分析业务流程和定位分析问题。DEBUG级别的日志在正式发布版本中默认不会被打印，只有在调试版本或打开调试开关的情况下才会打印。
97
98**日志等级设置**： 日志级别默认是Info级别，可以通过命令修改日志级别。
99
100读取日志级别命令：
101```
102param get hilog.loggable.global
103```
104
105设置日志级别命令：
106```
107hilog -b W \\设置全局日志级别为Warn级别。
108hilog -b D -T testTag \\设置日志Tag为"testTag"的日志级别为Debug级别。
109hilog -b D -D 0x3200 \\设置日志domainID为0x3200的日志级别为Debug级别。
110```
111注：建议不要将全局的日志级别修改为Debug级别，系统后台D级别日志量过大，会导致日志打印时IPC通信超负荷，从而打印失败，可以通过设置本模块使用的domainID或Tag为debug级别的方式，打印出本模块的Debug日志。
112
113
114
115#### （2）日志超限机制
116
117背景：为了防止日志打印流量过大导致应用性能恶化和打印失败问题，hilog日志打印时增加超限机制，debug应用默认关闭此机制。
118应用进程级别超限机制：应用日志打印时受进程级别超限机制管控，每个进程每秒日志量不超过50K，超过的日志不进行打印，并且有超限提示日志打印，本地调试是可以通过命令关闭应用日志超限机制： hilog -Q pidoff
119```
120应用超限提示日志打印：
12104-19 17:02:34.219 5394 5394 W A00032/LOGLIMIT: ==com.example.myapplication LOGS OVER PROC QUOTA, 3091 DROPPED==
122```
123说明：本条日志标识进程5394在17:02:34时由于日志打印超限，超限日志有3091行未打印。
124
125#### （3）日志隐私机制
126
127背景：为了防止隐私信息泄露，开发者编写代码是需要考虑日志内容是否敏感，对于隐私信息（格式化控制符没有%{public}标识符）的打印，默认打印出来是“private”字符串，debug应用默认关闭此机制。
128```
129日志打印：OH_LOG_ERROR(LOG_APP, "%s failed to visit %{private}s, reason:%{public}d.", name, url, errno);
130日志显示：12-11 12:21:47.579 2695 2695 E A03200/MY_TAG: <private> failed to visit <private>, reason:11.
131name和url参数格式化符没有%{public}开头，则显示为隐私数据，默认显示"<private>"字符串
132```
133
134
135#### （4）日志落盘机制
136
137开发者可以通过命令将buffer中的日志落盘到/data/log/hilog中。
138
139**hilog日志落盘命令**：
140// 不增加扩展参数默认落盘数量为10个文件，每个文件4M。
141```
142hilog -w start
143```
144// 扩展命令 -n 指定落盘数量，最大1000个文件，-l 指定落盘文件大小，大小范围[64.0K, 512.0M]。
145// 启动落盘命令，日志大小8M，落盘100个文件。
146```
147hilog -w start -l 8M -n 100
148```
149日志落盘任务查询命令：
150```
151hilog -w query
152```
153
154停止日志落盘命令：
155```
156hilog -w stop
157```
158
159### 3、日志常用命令<a name="section129654513264"></a>
160
161(1) hilog命令行参数说明
162
163| 短选项 | 长选项 | 参数 | 说明 |
164|----------------------------------------------------------------------------------------------|----------------------|---------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------|
165| -h | --help | | 帮助命令 |
166| 缺省 | 缺省 | | 阻塞读日志，不退出 |
167| -x | --exit | | 非阻塞读日志，读完退出 |
168| -g | | | 查询buffer的大小，配合-t指定某一类型使用，默认app和core |
169| -G | --buffer-size | \<size> | 设置指定\<type>日志类型缓冲区的大小，配合-t指定某一类型使用，默认app和core， 可使用B/K/M/G为单位 |
170| -r | | | 清除buffer日志,配合-t指定某一类型使用，默认app和core |
171| -p | --privacy | <on/off> | 支持系统调试时日志隐私开关控制 |
172| | | on | 打开隐私开关，显示\<private> |
173| | | off | 关闭隐私开关，显示明文 |
174| -k | | <on/off> | Kernel日志读取开关控制 |
175| | | on | 打开读取kernel日志 |
176| | | off | 关闭读取kernel日志 |
177| -s | --statistics | | 查询统计信息，需配合-t或-D使用 |
178| -S | | | 清除统计信息，需配合-t或-D使用 |
179| -Q | | \<control-type> | 流控缺省配额开关控制 |
180| | | pidon | 进程流控开关打开 |
181| | | pidoff | 进程流控开关关闭 |
182| | | domainon | domain流控开关打开 |
183| | | domainoff | domain流控开关关闭 |
184| -L | --level | \<level> | 指定级别的日志，示例：-L D/I/W/E/F |
185| -t | --type | \<type> | 指定类型的日志，示例：-t app core init |
186| -D | --domain | \<domain> | 指定domain |
187| -T | --Tag | \<tag> | 指定tag |
188| -a | --head | \<n> | 只显示前\<n>行日志 |
189| -z | --tail | \<n> | 只显示后\<n>行日志 |
190| -P | --pid | \<pid> | 标识不同的pid |
191| -e | --regex | \<expr> | 只打印日志消息与\<expr>匹配的行，其中\<expr>是一个正则表达式 |
192| -f | --filename | \<filename> | 设置落盘的文件名 |
193| -l | --length | \<length> | 设置落盘的文件大小，需要大于等于64K |
194| -n | --number | \<number> | 设置落盘文件的个数 |
195| -j | --jobid | \<jobid> | 设置落盘任务的ID |
196| -w | --write | \<control> | 落盘任务控制 |
197| | | query | 落盘任务查询 |
198| | | start | 落盘任务开始，命令行参数为文件名、单文件大小、落盘算法、rotate文件数目. |
199| | | stop | 落盘任务停止 |
200| -m | --stream | \<algorithm> | 落盘方式控制 |
201| | | none | 无压缩方式落盘 |
202| | | zlib | zlib压缩算法落盘，落盘文件为.gz |
203| | | zstd | zstd压缩算法落盘，落盘文件为.zst |
204| -v | --format | \<format> | |
205| | | time | 显示本地时间 |
206| | | color | 显示不同级别显示不同颜色，参数缺省级别颜色模式处理（按黑白方式） |
207| | | epoch | 显示相对1970时间 |
208| | | monotonic | 显示相对启动时间 |
209| | | usec | 显示微秒精度时间 |
210| | | nsec | 显示纳秒精度时间 |
211| | | year | 显示将年份添加到显示的时间 |
212| | | zone | 显示将本地时区添加到显示的时间 |
213| -b | --baselevel | \<loglevel> | 设置可打印日志的最低等级：D(DEBUG)/I(INFO)/W(WARN)/E(ERROR)/F(FATAL) |
214
215```
216示例：hilog -G 4M
217解释：设置hilogd buffer大小为4M。
218示例：hilog -g
219解释：查询hilogd buffer大小。
220示例：hilog -w start -n 100
221解释：执行名字为hilog的落盘任务，不指定-n 参数默认落盘10个文件。
222示例：hilog -b I
223解释：将全局日志级别设置为I级别
224type、level、domain、tag支持排除查询，排除查询可以使用以"^"开头的参数和分隔符"，"."来完成
225示例：hilog -t ^core,app 排除core和app类型的日志，可以与其他参数一起使用。
226示例：hilog -t app core 打印core和app类型的日志，可以与其他参数一起使用。
227```
228
229## hilog调试
230
231### 日志未打印问题定位
2321、排查日志级别是否合理。
2332、排查日志domainID是否合理。
2343、排查代码分支是否走到。
2354、排查日志打印时间点附件有无“LOGLIMIT”、“Slow reader”关键字。
236LOGLIMIT: 进程日志量过大触发了超限机制、可以使用hilog -Q pidoff命令关闭超限机制。
237```
23804-24 17:02:50.167 2650 2650 W A01B01/LOGLIMIT: ==com.ohos.sceneboard LOGS OVER PROC QUOTA, 46 DROPPED==
239```
240Slow reader: 整机日志量过大导致hilogd buffer中日志被老化掉，可以使用hilog -G 8M增加hilogd buffer内存大小。
241```
24204-24 17:02:19.315 0 0 I C00000/HiLog: ========Slow reader missed log lines: 209
243```
244
245## 涉及仓<a name="section177639411669"></a>
246
247[DFX子系统](https://gitee.com/openharmony/docs/blob/master/zh-cn/readme/DFX%E5%AD%90%E7%B3%BB%E7%BB%9F.md)
248
249[hiviewdfx\_hiview](https://gitee.com/openharmony/hiviewdfx_hiview/blob/master/README_zh.md)
250
251**hiviewdfx\_hilog**
252
253[hiviewdfx\_hiappevent](https://gitee.com/openharmony/hiviewdfx_hiappevent/blob/master/README_zh.md)
254
255[hiviewdfx\_hisysevent](https://gitee.com/openharmony/hiviewdfx_hisysevent/blob/master/README_zh.md)
256
257[hiviewdfx\_faultloggerd](https://gitee.com/openharmony/hiviewdfx_faultloggerd/blob/master/README_zh.md)
258
259[hiviewdfx\_hilog\_lite](https://gitee.com/openharmony/hiviewdfx_hilog_lite/blob/master/README_zh.md)
260
261[hiviewdfx\_hievent\_lite](https://gitee.com/openharmony/hiviewdfx_hievent_lite/blob/master/README_zh.md)
262
263[hiviewdfx\_hiview\_lite](https://gitee.com/openharmony/hiviewdfx_hiview_lite/blob/master/README_zh.md)
264
265
