一、HiLog接口说明

在应用开发过程中，日志输出系统提供了两个 API：HiLog和Console，使用上几乎相同。

HiLog 定义了 DEBUG、INFO、WARN、ERROR、FATAL 五种日志级别，并提供对应方法输出不同级别的日志。

接口名	功能描述
debug(domain, tag, format, ...args)	输出 DEBUG 级别日志，仅用于应用/服务调试。在 DevEco Studio 的 terminal 或 cmd 里，通过 hdc shell hilog -b D 设置可打印等级为 DEBUG
info(domain, tag, format, ...args)	输出 INFO 级别日志，表示普通信息
warn(domain, tag, format, ...args)	输出 WARN 级别日志，表示存在警告
error(domain, tag, format, ...args)	输出 ERROR 级别日志，表示存在错误
fatal(domain, tag, format, ...args)	输出 FATAL 级别日志，表示致命错误、不可恢复错误

其他辅助接口

接口名	功能描述	版本说明
isLoggable(domain, tag, level)	在打印日志前调用，检查指定领域标识、日志标识和级别的日志是否可以打印	—
setMinLogLevel(level)	设置应用日志打印的最低日志级别，用于拦截低级别日志打印	API 15 开始支持
setLogLevel(level, prefer)	设置当前应用程序进程的最低日志级别，可配置不同偏好策略	API 21 开始支持
setOutputType(type)	设置 hilog 的输出类型，可选择不同日志输出方式	API 26.0.0 开始支持
setOutputTypeByDomainID(type, domainIDs, isExclude)	根据 domainIDs 设置 hilog 的输出类型	API 26.0.0 开始支持
getOutputType()	返回当前 hilog 的输出类型	API 26.0.0 开始支持
clean()	删除沙箱中的所有 hilog 日志	API 26.0.0 开始支持
flush()	将缓存中的日志强制落盘	API 26.0.0 开始支持
getLogFile(latestSeconds)	返回指定最近时间段沙箱中的 hilog 日志文件路径列表	API 26.0.0 开始支持
getOutputDir()	返回 hilog 日志在沙箱中的路径	API 26.0.0 开始支持

注意

• 如果设置的日志级别低于全局日志级别，setMinLogLevel() 设置不生效

• debug 版本应用下，setMinLogLevel() 和 setLogLevel() 函数均不生效

二、参数说明

参数	说明
domain	指定输出日志对应的业务领域，取值范围 0x0000-0xFFFF，开发者可自定义
tag	日志标识，可为任意字符串，建议标识调用所在的类或业务行为。 最多 31 字节，超出后会截断。 不建议使用中文字符，可能出现乱码或对齐问题
level	日志级别，取值见 LogLevel
prefer	偏好策略，取值见 PreferStrategy
format	格式字符串，用于日志的格式化输出。格式化参数需按 %{private flag}specifier 的格式打印
type	hilog 的输出类型，取值见 OutputType
domainIDs	设置输出类型的 domain 列表，取值范围 0x0000~0xFFFF
isExclude	决定 domainIDs 是否对设置的输出类型生效： • true：排除 domainIDs 列表，仅对非列表中的 domain 生效 • false：仅对列表中的 domain 生效
latestSeconds	距离现在的时间段，单位秒，取值范围大于 0

隐私标识符（private flag）

标识符	说明
private	日志打印结果不可见，输出结果为 <private>
public	日志打印结果可见，明文显示参数
无	缺省值默认为 private，日志打印结果不可见

格式说明符（specifier）

说明符	支持类型	示例
d / i	number 和 bigint 类型	123
s	string、undefined、boolean、null 类型	"123"
o / O	object、undefined、null 类型（从 API 20 开始支持）	{name: "Jack", age: 22}

关于 args

可以为 0 个或多个参数，是格式字符串中参数类型对应的参数列表。参数的数量、类型必须与格式字符串中的标识一一对应。

关于 isLoggable 的说明

• isLoggable() 和具体日志打印接口使用的 domain 和 tag 应保持一致

• isLoggable() 使用的 level 应和具体日志打印接口级别保持一致

• 返回值：如果指定的 domain、tag、level 日志可以打印则返回 true，否则返回 false

debug 应用 vs release 应用

应用类型	日志级别管控
debug 应用	不做日志级别管控，所有级别日志都能正常打印
release 应用	按全局日志级别管控，日志级别不低于全局日志级别时才能正常打印

备注：日志最多打印 4096 字节，超出限制文本将被截断。

三、代码示例

import { hilog } from '@kit.PerformanceAnalysisKit';

@Entry
@Component
struct Index {
  build() {
    Row() {
      Column() {
        // 添加 hilog 按钮
        Button($r('app.string.HiLogArkTS_Button'))
          .type(ButtonType.Capsule)
          .margin({ top: 20 })
          .width('40%')
          .height('5%')
          .onClick(() => {
            // isLoggable 用来判断 domainID 和 tag 是否满足目前的日志级别打印，建议对返回值进行判断
            let ret = hilog.isLoggable(0xFF00, 'testTag', hilog.LogLevel.INFO);
            if (ret) {
              hilog.info(0xFF00, 'testTag', 'A log with a domainID of 0xFF00 and a label of testTag can print logs at the Info level or higher.');
            }
            hilog.info(0xFF00, 'testTag', '%{public}s World %{public}d', 'hello', 3);

            class Person {
              constructor(name: string, age: number) {
                this.name = name;
                this.age = age;
              }
              public name: string;
              public age: number;
            }
            let peter: Person = new Person('peter', 15);
            hilog.info(0xFF00, 'testTag', 'peter is %{public}o', peter);

            // 设置应用日志最低打印级别，低于 Warn 级别的日志将无法打印
            hilog.setMinLogLevel(hilog.LogLevel.WARN);
            hilog.info(0xFF00, 'testTag', 'this is an info level log');
            hilog.error(0xFF00, 'testTag', 'this is an error level log');

            // 设置 PREFER_OPEN_LOG 策略的最低打印级别，不低于 INFO 级别的日志都可打印
            hilog.setLogLevel(hilog.LogLevel.INFO, hilog.PreferStrategy.PREFER_OPEN_LOG);
            hilog.info(0xFF00, 'testTag', 'this is an another info level log');
            hilog.error(0xFF00, 'testTag', 'this is an another error level log');
          })

        // 添加沙箱日志按钮
        Button($r('app.string.SandboxLogArkTS_Button'))
          .type(ButtonType.Capsule)
          .margin({ top: 30 })
          .width('40%')
          .height('5%')
          .onClick(() => {
            // 设置日志输出类型 SHARE_SANDBOX_WITH_CONSOLE，同时输出公有沙箱和控制台
            hilog.setOutputType(hilog.OutputType.SHARE_SANDBOX_WITH_CONSOLE);
            let lastType = hilog.getOutputType();
            hilog.info(0xFF00, 'testTag', 'current log type:%{public}d', lastType);

            let dir = hilog.getOutputDir();
            hilog.info(0xFF00, 'testTag', 'current log dir:%{public}s', dir);

            hilog.info(0xFF00, 'testTag', 'hilog_info_test');
            hilog.debug(0xFF00, 'testTag', 'hilog_debug_test');
            hilog.warn(0xFF00, 'testTag', 'hilog_warn_test');
            hilog.fatal(0xFF00, 'testTag', 'hilog_fatal_test');
            hilog.error(0xFF00, 'testTag', 'hilog_error_test');

            // 获取沙箱目录中 2 分钟之内写入过的日志文件
            let logs = hilog.getLogFile(120);
            hilog.info(0xFF00, 'testTag', 'current log files:%{public}s', logs.toString());

            // 将沙箱日志刷入磁盘
            hilog.flush();
          })
      }
      .width('100%')
    }
    .height('100%')
  }
}

格式字符串示例

格式字符串	说明
'%{public}s World %{public}d'	%{public}s 为公共字符串，%{public}d 为公共整型数
'peter is %{public}o'	%{public}o 为公共对象

输出日志示例

08-05 06:32:35.928 10753-10753 A0FF00/com.sam...hilog/testTag com.samples.hilog I hello World 3
08-05 06:32:35.928 10753-10753 A0FF00/com.sam...hilog/testTag com.samples.hilog I peter is ["name":"peter","age":15]
08-05 06:32:35.928 10753-10753 A0FF00/com.sam...hilog/testTag com.samples.hilog E this is an error level log
08-05 06:32:35.928 10753-10753 A0FF00/com.sam...hilog/testTag com.samples.hilog I this is an another info level log
08-05 06:32:35.928 10753-10753 A0FF00/com.sam...hilog/testTag com.samples.hilog E this is an another error level log

沙箱日志查看

搜索 "testTag"，控制台 current log dir 打印的即为当前沙箱路径。

沙箱日志内容示例：

08-05 06:32:35.928 10753 10753 I A0ff00/testTag: current log type:4
08-05 06:32:35.928 10753 10753 I A0ff00/testTag: current log dir:/data/storage/el2/log/hiapplog
08-05 06:32:35.929 10753 10753 I A0ff00/testTag: hilog_info_test
08-05 06:32:35.929 10753 10753 D A0ff00/testTag: hilog_debug_test
08-05 06:32:35.929 10753 10753 W A0ff00/testTag: hilog_warn_test
08-05 06:32:35.929 10753 10753 F A0ff00/testTag: hilog_fatal_test
08-05 06:32:35.929 10753 10753 E A0ff00/testTag: hilog_error_test
08-05 06:32:35.930 10753 10753 I A0ff00/testTag: current log files:hiapplog.10753.001.20170805-063235.log

说明：

1. 五个日志级别，按严重程度递增：DEBUG < INFO < WARN < ERROR < FATAL，日常开发最常用 INFO，排查问题用 WARN/ERROR，FATAL 用于不可恢复错误。

2. isLoggable 建议先判断再打印：用 isLoggable 判断能否打印，domain、tag、level 要和实际打印接口保持一致，避免无效调用。

3. 隐私标识符：不写 %{public} 默认是 private，日志会显示为 <private>，看不到实际值。要明文显示必须加 %{public}。

4. 格式说明符要匹配类型：

   • d / i → number、bigint

   • s → string、undefined、boolean、null

   • o / O → object（API 20 起支持）

5. 参数数量要一一对应：格式字符串里的占位符有几个，args 就要传几个，类型也要对上，否则日志会打印异常。

6. tag 有 31 字节限制：超出会截断，且不建议用中文，可能乱码或对齐错位。

7. 日志最大 4096 字节：超出会被截断，打长日志（比如完整 JSON）要注意。

8. setMinLogLevel 和 setLogLevel 有版本要求：

   • setMinLogLevel：API 15 起支持

   • setLogLevel：API 21 起支持

   • 低版本用不了。

9. debug 应用不生效：debug 版本应用下，两个设置函数均不生效，调试时看不到效果别奇怪。

10. debug 应用无隐私管控：debug 应用下，不管写不写 private/public，参数都明文显示；release 应用才按标识符处理。

11. 沙箱日志：API 26.0.0 起支持 setOutputType、getLogFile、flush 等，可以把日志落到沙箱文件，适合离线分析或用户反馈时提取日志。

12. flush() 要记得调：日志先写缓存，flush() 强制落盘，不调可能丢日志，尤其是应用即将退出时。

13. 日志的过滤：Log 窗口里选当前设备 + 进程，级别选 Debug，搜索 tag，能快速定位自己的日志，避免被系统日志淹没。

14. release 包默认打不出 debug 日志：发布版调试时别用 debug 级别。

建议：

• 统一 domain 和 tag：团队约定好 domain 范围，tag 用类名或业务名，方便过滤

• 关键路径用 INFO：正常流程打 INFO，异常分支打 WARN/ERROR

• 敏感信息别用 public：用户 ID、手机号等敏感数据，用默认 private 或不打印

• release 包注意级别：发布版默认可能只打 INFO 及以上，debug 日志打不出来

• 沙箱日志用于问题回溯：用户反馈问题时，用 getLogFile 提取日志文件分析