HiLog组件

• HiLog组件

  • 简介
  • 目录
  • 约束
  • 说明
    • 接口说明
    • 使用说明
  • 相关仓库

• 相关仓库

简介

HiLog是OpenHarmony的日志系统，为系统框架、服务及应用提供日志记录功能，用于追踪用户操作和系统运行状态。

图 1 HiLog架构图

用户态进程通过日志接口将日志内容写入hilogd的缓冲区，hilog命令行工具支持将日志输出到控制台查看，同时可通过指令将日志持久化存储。

核心功能模块说明：

• hilogd作为常驻用户态日志服务

1. 在研发版本系统中默认随开机启动。
2. 接收用户态模块通过日志接口发送的格式化日志，并将其存储于环形缓冲区中。

• hilog命令行工具

1. 从hilogd的环形缓冲区读取日志内容，输出至标准输出，支持日志过滤功能。

主要特性：

• 支持参数隐私标识格式化（参见示例说明）。
• 提供针对超标日志打印的进程级流量控制。
• 实现基于domain（子系统/模块标识）的日志流量控制。
• 支持日志流压缩存储。

目录

/base/hiviewdfx/hilog
├── frameworks           # 框架代码
│   └── native           # HiLog native实现代码
├── interfaces           # 接口
│   └── native           # 对外C/C++接口
│       └── innerkits    # 对内部子系统暴露的头文件
│       └── kits         # 对应用暴露的头文件
│   └── js               # 对外js接口
├── services
│   └── hilogd           # 日志常驻服务实现
│   └── hilogtool        # 日志工具实现

Constraints

Requires Clang compiler (Clang 8.0.0) or higher.

Description

1. Log Printing and Display

JS API: https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis-performance-analysis-kit/js-apis-hilog.md

NDK API: https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/dfx/hilog-guidelines-ndk.md

Log printing format:

日期 时间 进程号 线程号 日志级别 domainID/日志标签: 日志内容

如下所示，这是一条 domainID 为 0x3200 且标签为 "testTag" 的 info 级别日志：

04-19 17:02:14.735  5394  5394 I A00032/testTag: this is a info level hilog

Explanation:

• Log Level: I stands for Info level; other levels correspond to the first letter of the log level.
• domainID: In A003200, A indicates application logs, and 3200 means the domainID is 0x3200. For specific definitions of domainID, refer to the interface guide.

2. Log Configuration

(1) Log Levels

Note: The log level should match the actual severity of the log content. The log levels are defined as follows:

FATAL: Critical and fatal exceptions, indicating that the program or functionality is about to crash, and the failure is unrecoverable.

ERROR: Errors occurred in the program or functionality that affect normal operation or user experience. These errors are recoverable but at a high cost, such as data reset.

WARN: Unexpected but less severe situations that have minimal impact on users. The program can recover automatically or through simple operations.

INFO: Used to record key business process nodes, enabling the reconstruction of the main workflow. It also logs non-normal but expected scenarios (e.g., no network signal, login failure). Such logs should be recorded by the dominant module within the business to avoid duplication in multiple called modules or low-level functions.

DEBUG: Provides more detailed process records than INFO, aiding in in-depth analysis of business flows and issue troubleshooting. DEBUG logs are not printed in official releases by default and only appear in debug builds or when debugging is enabled.

Log Level Setting: The default log level is Info, which can be modified via commands.

Command to read the log level:

param get hilog.loggable.global

Log Level Configuration Command:

hilog -b W \\设置全局日志级别为Warn级别。
hilog -b D -T testTag \\设置日志Tag为"testTag"的日志级别为Debug级别。
hilog -b D -D 0x3200 \\设置日志domainID为0x3200的日志级别为Debug级别。

Note: It is not recommended to set the global log level to Debug. The system generates an excessive volume of D-level logs in the background, which can overload IPC communication during log printing and cause failures. Instead, you can enable Debug logs for specific modules by setting their domainID or Tag to debug level.

(2) Log Throttling Mechanism

Background: To prevent performance degradation and printing failures caused by excessive log traffic, the hilog system implements a throttling mechanism. By default, this mechanism is disabled for debug applications.

Process-Level Throttling: Log printing at the application process level is governed by this mechanism, limiting each process to no more than 50K of logs per second. Exceeding logs are discarded, and a throttling notification is printed. For local debugging, the throttling can be disabled using the command:

hilog -Q pidoff  

应用超限提示日志打印：
04-19 17:02:34.219  5394  5394 W A00032/LOGLIMIT: ==com.example.myapplication LOGS OVER PROC QUOTA, 3091 DROPPED==

Note: This log entry indicates that process 5394 exceeded the log printing limit at 17:02:34, with 3091 lines of logs not printed.

(3) Log Privacy Mechanism

Background: To prevent privacy information leakage, developers must consider whether log content is sensitive when writing code. For privacy information (format control specifiers without the %{public} identifier), the default output is the string "private". This mechanism is disabled by default for debug applications.

日志打印：OH_LOG_ERROR(LOG_APP, "%s failed to visit %{private}s, reason:%{public}d.", name, url, errno);
日志显示：12-11 12:21:47.579 2695 2695 E A03200/MY_TAG: <private> failed to visit <private>, reason:11.
name和url参数格式化符没有%{public}开头，则显示为隐私数据，默认显示"<private>"字符串

(4) Log Persistence Mechanism

Developers can use commands to flush logs from the buffer to /data/log/hilog.

hilog Log Persistence Command:
// Without additional parameters, the default persistence setting creates 10 files, each 4MB in size.

hilog -w start

// Extension command -n specifies the number of files to be written, with a maximum of 1000 files. -l sets the size of each file, ranging from [64.0K, 512.0M].
// Command to initiate file writing, with a log size of 8M and 100 files to be written.

hilog -w start -l 8M -n 100

Log File Flush Task Query Command:

hilog -w query

停止日志落盘命令：

hilog -w stop

Disk Log File Naming Format

落盘日志文件名：
hilog.000.20170805-170154.gz
hilog_kmsg.000.20170805-170430.gz

Description: "hilog" indicates the log type, where "hilog" represents the hilog logs and "hilog_kmsg" represents the kmsg logs; "000" denotes the log file index, ranging from [0, 999]. If the index exceeds 999, it wraps around to 0, with a maximum of 1000 log files saved; "20170805-170154" indicates the timestamp when the log started being written to disk.

(5) Log Truncation Mechanism

A single hilog entry has a maximum length of approximately 3500 bytes. Logs exceeding this length will be truncated upon output. For printing overly long logs, they can be split into multiple segments.

3. Common Log Commands

(1) hilog Command Line Parameter Descriptions

Short Option	Long Option	Parameter	Description
-h	--help		Help command
Default	Default		Blocking read logs, does not exit
-x	--exit		Non-blocking read logs, exits after reading
-g			Query buffer size, used with -t to specify a type, defaulting to app and core
-G	--buffer-size	<size>	Set the buffer size for the specified <type> log type, used with -t, defaulting to app and core. Units: B/K/M/G
-r			Clear buffer logs, used with -t to specify a type, defaulting to app and core
-p	--privacy	<on/off>	Control privacy switch for system debug logs
		on	Enable privacy switch, displays <private>
		off	Disable privacy switch, displays plaintext
-k		<on/off>	Kernel log read control
		on	Enable reading kernel logs
		off	Disable reading kernel logs
-s	--statistics		Query statistics, requires -t or -D
-S			Clear statistics, requires -t or -D
-Q		<control-type>	Default quota control for flow control
		pidon	Enable process flow control
		pidoff	Disable process flow control
		domainon	Enable domain flow control
		domainoff	Disable domain flow control
-L	--level	<level>	Specify log level, e.g., -L D/I/W/E/F
-t	--type	<type>	Specify log type, e.g., -t app core init
-D	--domain	<domain>	Specify domain
-T	--Tag	<tag>	Specify tag
-a	--head	<n>	Display only the first <n> log lines
-z	--tail	<n>	Display only the last <n> log lines
-P	--pid	<pid>	Identify different pids
-e	--regex	<expr>	Only print log lines matching the regular expression <expr>
-f	--filename	<filename>	Set the filename for disk storage
-l	--length	<length>	Set the file size for disk storage, must be greater than or equal to 64K
-n	--number	<number>	Set the number of files for disk storage
-j	--jobid	<jobid>	Set the ID for the disk storage task
-w	--write	<control>	Control disk storage tasks
		query	Query disk storage tasks
		start	Start a disk storage task, with command-line parameters: filename, single file size, storage algorithm, and number of rotate files.
		stop	Stop a disk storage task
-m	--stream	<algorithm>	Control the storage method
		none	Store without compression
		zlib	Store using zlib compression algorithm, resulting in .gz files
		zstd	Store using zstd compression algorithm, resulting in .zst files
-v	--format	<format>
		time	Display local time
		color	Display different levels in different colors; defaults to monochrome if level color mode is unspecified
		epoch	Display time relative to 1970
		monotonic	Display time relative to startup
		usec	Display time with microsecond precision
		nsec	Display time with nanosecond precision
		year	Add year to the displayed time
		zone	Add local timezone to the displayed time
-b	--baselevel	<loglevel>	Set the minimum log level to print: D(DEBUG)/I(INFO)/W(WARN)/E(ERROR)/F(FATAL)

示例：hilog -G 4M                                                                
解释：设置hilogd buffer大小为4M。                                                                                          
示例：hilog -g                                                                   
解释：查询hilogd buffer大小。                                                                                             
示例：hilog -w start -n 100                                  
解释：执行名字为hilog的落盘任务，不指定-n 参数默认落盘10个文件。
示例：hilog -b I
解释：将全局日志级别设置为I级别                                  
type、level、domain、tag支持排除查询，排除查询可以使用以"^"开头的参数和分隔符"，"."来完成   
示例：hilog -t ^core,app 排除core和app类型的日志，可以与其他参数一起使用。
示例：hilog -t app core 打印core和app类型的日志，可以与其他参数一起使用。                                         

HiLog Debugging

Troubleshooting Missing Logs

1. Check if the log level is appropriate.
2. Verify whether the log domainID is correctly set.
3. Confirm if the code execution reaches the intended branch.
4. Inspect the log output for keywords like LOGLIMIT or Slow reader around the expected print time.
   • LOGLIMIT: Indicates the process exceeded log volume limits. Use the command hilog -Q pidoff to disable the limit mechanism.

04-24 17:02:50.167  2650  2650 W A01B01/LOGLIMIT: ==com.ohos.sceneboard LOGS OVER PROC QUOTA, 46 DROPPED==

慢速读取问题：整机日志量过大导致hilogd缓冲区中的日志被老化清除，可通过执行hilog -G 8M命令增大hilogd缓冲区的内存容量。

04-24 17:02:19.315     0     0 I C00000/HiLog: ========Slow reader missed log lines: 209

Related Repositories

DFX Subsystem

hiviewdfx_hiview

hiviewdfx_hilog

hiviewdfx_hiappevent

hiviewdfx_hisysevent

hiviewdfx_faultloggerd

hiviewdfx_hilog_lite

hiviewdfx_hievent_lite

hiviewdfx_hiview_lite