# 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

  1. Whether the logLevel during SDK initialization is set to none;
  2. Whether @finclip/xlog-sdk has been integrated;
  3. Whether FinAppletXLog.init() was called before FinAppClient.init(...);
  4. Whether the log delegate has set writeFile to false;
  5. Whether a custom logDir is configured;
  6. Whether productIdentification is configured. If configured, you need to replace Applet in the default path with the corresponding identifier;
  7. Whether the package name and entry module name are correct;
  8. 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 logLevel as 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.
© FinClip with ❤ , Since 2017