Log Configuration¶

This article describes the HarmonyOS Log initialization configuration.

Initialization Configuration¶

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);

Console Log Filtering¶

The second parameter of setEnableConsoleLog(true, prefix) is used to filter automatically collected console.* and hilog.* logs:

• When a normal string is passed, the compatible behavior is retained: only logs whose message starts with the string are collected. If not passed, no filtering is performed.
• When a string whose first non-whitespace character is { is passed, it is treated as an allow rule according to the DataKit rule syntax. Logs matching the rule enter the SDK queue; unmatched logs are discarded before enqueueing. Multiple rule blocks are ORed together.

The rule can use message and log_source (console or hilog); hilog can also use tag and domain. Log levels remain independently controlled by setLogLevelFilters(...).

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

Logger Logging¶

Before using FTLogger to report custom logs, you need to enable setEnableCustomLog(true). A single log entry can be up to 30 KB; anything beyond that is truncated.

Usage¶

/**
 * Reports a single custom log.
 *
 * @param content Log content.
 * @param status Log level. Accepts `Status` or a level string.
 * @param property Additional attributes (optional).
 * @param isSilence Whether to process silently (optional).
 */
FTLogger.logBackground(
  content: string,
  status: Status | string,
  property?: Map<string, object>,
  isSilence?: boolean
): void

Code Example¶

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

// Report a single log.
FTLogger.logBackground('登录成功', Status.INFO);

// Pass additional attributes.
const property = new Map<string, object>();
property.set('user_id', new String('user-001'));
FTLogger.logBackground('支付完成', Status.INFO, property);

Log Levels¶

Recommendations¶

• setLogLevelFilters(...) controls the reporting level of FTLogger business logs. It is independent of setSdkLogLevel(...), which controls SDK internal diagnostic logs.
• setEnableConsoleLog(...) and setEnableCustomLog(...) are independent of each other: the former is used to automatically collect console.* and hilog.* logs and requires installing and configuring the Hvigor Plugin; the latter is used to manually report custom logs via FTLogger and does not require installing the plugin.
• During debugging, you can use setEnableCustomLog(true), setDebug(true), and the SDK Debug Logs together to verify the collection pipeline.
• If you want to analyze logs together with user behavior, page, and resource data, it is recommended to also enable setEnableLinkRumData(true).
• If the log volume is large, you can control the reporting volume through the sampling rate and level filtering.