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) - 若日志量较大,可通过采样率和级别过滤控制上报量