跳转至

Log 配置

本文用于承载 HarmonyOS Log 初始化配置。

初始化配置

import { FTSDK, FTLoggerConfig, Status } from '@guancecloud/ft_sdk/Index';

const logConfig = new FTLoggerConfig()
  .setSamplingRate(1.0)
  .setEnableCustomLog(true)
  .setEnableConsoleLog(true, '[business]')
  .setLogLevelFilters([
    Status.ERROR,
    Status.WARN,
    Status.INFO,
    Status.DEBUG
  ])
  .setEnableLinkRumData(true)
  .addGlobalContext('log_source', 'business')
  .setLogCacheLimitCount(10000);

FTSDK.installLogConfig(logConfig);
方法 类型 必须 说明
setSamplingRate number 否 日志采样率,范围 [0.0, 1.0],默认 1.0
setEnableCustomLog boolean 否 是否启用自定义日志,默认 false
setEnableConsoleLog enable: boolean, prefix?: string 否 是否上报控制台日志,该配置依赖 Hvigor Plugin,默认 false。支持 console.log、debug、info、warn、error、trace,以及从 @ohos.hilog 或 @kit.PerformanceAnalysisKit 导入的 hilog.debug、info、warn、error、fatal。日志等级对应关系为:log、info -> info,debug、trace -> debug,warn -> warn,error -> error,fatal -> fatal。prefix 可传普通消息前缀,或以 { 开头的 DataKit 采集规则,详见控制台日志过滤。该能力要求 ft-sdk 0.1.17 及以上版本与 @cloudcare/hvigor-ohos-plugin 0.1.1 及以上版本
setEnableLinkRumData boolean 否 是否关联 RUM 数据,默认 false
setLogLevelFilters Array<Status | string | { name: string }> 否 日志级别过滤,可选值:ERROR、WARN、INFO、DEBUG
addGlobalContext Dictionary 否 添加 Log 全局属性,支持 key,value;添加规则请查阅此处
addGlobalContext key: string, value: object 否 添加 Log 全局属性,添加规则请查阅此处
setLogCacheLimitCount number 否 日志数据缓存数量限制,默认 5000,最小值 1000
setLogCacheDiscardStrategy LogCacheDiscard 否 设置日志达到限制上限以后的日志丢弃规则,默认为 LogCacheDiscard.DISCARD,DISCARD 为丢弃追加数据,DISCARD_OLDEST 丢弃老数据

控制台日志过滤

setEnableConsoleLog(true, prefix) 的第二个参数用于过滤自动采集的 console.* 和 hilog.* 日志:

  • 传入普通字符串时,沿用兼容行为,仅采集消息以该字符串开头的日志;不传时不做过滤。
  • 传入首个非空白字符为 { 的字符串时,按 DataKit 规则语法作为允许规则处理。命中规则的日志会进入 SDK 队列,未命中的日志会在入队前丢弃。多个规则块之间为“或”关系。

规则可使用 message、log_source(console 或 hilog);hilog 还可使用 tag 和 domain。日志等级仍由 setLogLevelFilters(...) 独立控制。

const logConfig = new FTLoggerConfig().setEnableConsoleLog(true,
  "{ log_source = 'hilog' and tag = 'Network' and message match ['^HTTP'] }");

Logger 日志打印

使用 FTLogger 上报自定义日志前,需开启 setEnableCustomLog(true)。单条日志内容最大为 30 KB,超出部分会被截断。

使用方法

/**
 * 上报单条自定义日志。
 *
 * @param content 日志内容。
 * @param status 日志等级,可传 `Status` 或等级字符串。
 * @param property 附加属性(可选)。
 * @param isSilence 是否静默处理(可选)。
 */
FTLogger.logBackground(
  content: string,
  status: Status | string,
  property?: Map<string, object>,
  isSilence?: boolean
): void

代码示例

import { FTLogger, Status } from '@guancecloud/ft_sdk/Index';

// 上传单个日志。
FTLogger.logBackground('登录成功', Status.INFO);

// 传递附加属性。
const property = new Map<string, object>();
property.set('user_id', new String('user-001'));
FTLogger.logBackground('支付完成', Status.INFO, property);

日志等级

方法名 含义
Status.TRACE 跟踪
Status.DEBUG 调试
Status.INFO 提示
Status.WARN 警告
Status.ERROR 错误
Status.FATAL 严重

使用建议

  • setLogLevelFilters(...) 控制 FTLogger 业务 Log 的上报级别,与 SDK 内部诊断日志的 setSdkLogLevel(...) 相互独立
  • setEnableConsoleLog(...) 与 setEnableCustomLog(...) 相互独立:前者用于自动采集 console.* 和 hilog.* 日志,需安装并配置 Hvigor Plugin;后者用于 FTLogger 手动上报自定义日志,无需安装插件
  • 调试阶段可结合 setEnableCustomLog(true)、setDebug(true) 和 SDK 调试日志 一起验证采集链路
  • 若希望日志与用户行为、页面和资源数据串联分析,建议同时开启 setEnableLinkRumData(true)
  • 若日志量较大,可通过采样率和级别过滤控制上报量

文档评价

文档内容是否对您有帮助?