Log Configuration¶

This document 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)
  .setLogLevelFilters([
    Status.ERROR,
    Status.WARN,
    Status.INFO,
    Status.DEBUG
  ])
  .setEnableLinkRumData(true)
  .addGlobalContext('log_source', 'business')
  .setLogCacheLimitCount(10000);

FTSDK.installLogConfig(logConfig);

Method	Type	Required	Description
`setSamplingRate`	`number`	No	Log sampling rate, range `[0.0, 1.0]`, default `1.0`
`setEnableCustomLog`	`boolean`	No	Whether to enable custom logs, default `false`
`setEnableLinkRumData`	`boolean`	No	Whether to link RUM data, default `false`
`setLogLevelFilters`	`Array<Status \\| string \\| { name: string }>`	No	Log level filter. Acceptable values: `ERROR`, `WARN`, `INFO`, `DEBUG`
`addGlobalContext`	`Dictionary`	No	Add global context to Log, supports `key,value`. Refer to here for addition rules
`addGlobalContext`	`key: string, value: object`	No	Add global context to Log. Refer to here for addition rules
`setLogCacheLimitCount`	`number`	No	Limit on the number of cached log entries, default `5000`, minimum `1000`
`setLogCacheDiscardStrategy`	`LogCacheDiscard`	No	Discard strategy when the cache limit is reached. Default is `LogCacheDiscard.DISCARD`, `DISCARD` discards newly appended data, `DISCARD_OLDEST` discards the oldest data

Logger Logging¶

Before using FTLogger to report custom logs, you must enable setEnableCustomLog(true). Each log entry content is up to 30 KB; excess content will be truncated.

Usage¶

/**
 * Reports a single custom log entry.
 *
 * @param content Log content.
 * @param status Log level, can be `Status` or a level string.
 * @param property Additional attributes (optional).
 * @param isSilence Whether to handle 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';

// Upload a single log entry.
FTLogger.logBackground('Login successful', Status.INFO);

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

Log Levels¶

Method Name	Meaning
Status.TRACE	Trace
Status.DEBUG	Debug
Status.INFO	Info
Status.WARN	Warn
Status.ERROR	Error
Status.FATAL	Fatal

Usage Recommendations¶

setLogLevelFilters(...) controls the reporting level of FTLogger business logs, independent of setSdkLogLevel(...) for SDK internal diagnostic logs.
During debugging, you can combine setEnableCustomLog(true), setDebug(true), and SDK debug logs to verify the collection pipeline.
If you want to correlate logs with user actions, pages, and resource data, it is recommended to also enable setEnableLinkRumData(true).
If the log volume is large, you can control the reporting volume through sampling rate and level filtering.