# Log Management
SDK logs mainly consist of two parts: console output and locally persisted logs. Console logs are suitable for use during development and issue reproduction; if you need to retain log files after the application is running, you need to additionally integrate the XLog Extension SDK.
Important
The output of console logs and local log files requires that a valid logLevel is configured during SDK initialization.
The default value of logLevel is none. If the log level is not enabled during SDK initialization, even if the log delegate has configured properties such as isConsoleLog and writeFile, the corresponding console logs or local log files will not be generated.
# 1. Log Initialization Configuration
# 1.1 Configure the SDK Log Level
During SDK initialization, the log level is configured via IFinAppConfig.logLevel. It supports none, info, debug, warn, and error, with a default of none.
For the specific configuration of the log delegate (including console output, file writing, log directory, log retention time, and log callback), please refer to LogHandler.
The log delegate needs to be configured before FinAppClient.init(...). If the delegate configuration is modified after SDK initialization, it may not affect the already-created log instance.
# 1.2 Integrate the XLog Extension SDK
Starting from version 1.4.3, the core SDK no longer includes the capability to persist logs locally.
If you need to persist logs, please integrate the XLog Extension SDK and call the following before core SDK initialization:
import { FinAppletXLog } from '@finclip/xlog-sdk'
// Must be called before FinAppClient.init(...)
FinAppletXLog.init()
After completing XLog initialization, configure LogHandler as needed, and finally call FinAppClient.init(...). Only after integrating XLog will the writeFile configuration in the log delegate be used for local file persistence.
# 2. Export Log Files
After integrating XLog and enabling file writing, you can use the hdc file transfer tool (opens new window) to export log files.
The default log directory is:
${context.filesDir}/${productIdentification || 'Applet'}/logs/
Under the default entry module entry, the common path is as follows. Please replace the package name, entry module name, and local path with actual values:
hdc file recv /data/app/el2/100/base/包名/haps/入口模块名/files/Applet/logs /local/path/on/pc
If a custom logDir is configured, please replace the log directory in the command with the custom path.
XLog writes logs asynchronously. Newly generated logs may temporarily remain in the buffer and not immediately appear in the file; the SDK destroy lifecycle will flush and close the logs. XLog files are in a binary compressed format and cannot be viewed directly with a text editor. They need to be parsed using a matching XLog/Mars decoding tool.
# 3. Troubleshooting When Log Files Do Not Exist
- Whether the
logLevelduring SDK initialization is set tonone; - Whether
@finclip/xlog-sdkhas been integrated; - Whether
FinAppletXLog.init()was called beforeFinAppClient.init(...); - Whether the log delegate has set
writeFiletofalse; - Whether a custom
logDiris configured; - Whether
productIdentificationis configured. If configured, you need to replaceAppletin the default path with the corresponding identifier; - Whether the package name and entry module name are correct;
- Whether the log was just generated and is still being asynchronously written to the buffer.
# 4. Production Environment Usage Recommendations
- When log persistence is not needed, do not integrate XLog solely for the purpose of enabling console logs;
- In production environments, set
logLevelas needed and disable unnecessary console output; - The SDK does not automatically upload logs. Log export, desensitization, and upload are handled by the Host-App itself;
- The minimum effective value for log retention time is 1 day. Please configure it according to actual needs.