Troubleshooting¶

This document provides basic troubleshooting guidelines for HarmonyOS SDK initialization and reporting exceptions.

Initialization and Log Diagnosis¶

Initialization Failure¶

If SDK initialization fails, it is recommended to check the following in order:

1. Whether datakitUrl, datawayUrl, and clientToken are correctly configured according to the deployment method.
2. Whether ft_sdk.har and ft_native.har have been placed in the libs directory, and declared in oh-package.json5 as @guancecloud/ft_sdk and @guancecloud/ft_native respectively, then executed ohpm install.
3. Whether the application has completed the dependency declaration in oh-package.json5 according to the documentation.
4. Whether SDK initialization occurs during the application startup phase.

SDK Initialization Anomaly Verification¶

Check hilog to confirm if there are logs with a Tag prefix of [FT-SDK]. Internal logs for SDK initialization, configuration installation, data synchronization, etc., will be output through this prefix, which can be used to locate issues such as initialization failure, configuration not taking effect, or network synchronization anomalies.

Enable Debug Mode¶

The SDK Debug mode can be enabled through the following configuration. setDebug(true) is the master switch for SDK internal logs; when enabled, SDK debug logs will be output to the console hilog, and you can filter by the [FT-SDK] string to locate SDK internal logs. setSdkLogLevel(...) is used to control the output threshold:

import { FTSDK, FTSDKConfig, SDKLogLevel } from '@guancecloud/ft_sdk/Index';

const sdkConfig = FTSDKConfig.builder(datawayUrl, clientToken)
  .setDebug(true)
  .setSdkLogLevel(SDKLogLevel.D);

FTSDK.install(sdkConfig, this.context);

It is recommended to disable this configuration when releasing the Release version.

SDK Internal Logs Written to Local File¶

To troubleshoot online or occasional issues, SDK internal diagnostic logs can be written to a local file in the application sandbox for later export and analysis. setDebug(true) must be enabled simultaneously; setSdkLogLevel(...) can be used to control the log level to be recorded.

import { FTSDK, FTSDKConfig, SDKLogLevel } from '@guancecloud/ft_sdk/Index';

const sdkConfig = FTSDKConfig.builder(datawayUrl, clientToken)
  .setDebug(true)
  .setSdkLogLevel(SDKLogLevel.D)
  .setEnableInnerLogFile(true, {
    singleFileMaxSize: 5 * 1024 * 1024,
    totalFileMaxSize: 50 * 1024 * 1024,
    flushBatchSize: 20,
    flushIntervalMs: 200
  });

FTSDK.install(sdkConfig, this.context);

FTInnerLogFileConfig¶

setEnableInnerLogFile(true, config) can accept FTInnerLogFileConfig to adjust the internal log file writing strategy:

Log files are written by default to the application sandbox filesDir/ft_sdk_logs/ directory:

• Current log file: ft_inner_current.log
• Historical rotation files: ft_inner_*.log

When the total log size exceeds the configured threshold, the SDK will clean up starting from the earliest historical rotation files, and the current log file will be retained. Internal log files only record SDK diagnostic logs, not business logs written by FTLogger.

To ensure the completeness of internal logs, this configuration must be set before FTSDK.install(...), and setDebug(true) must be enabled simultaneously. Values outside the configured range will be truncated by the SDK to the allowable range and rounded.

Data Reporting and Caching¶

No Data Reported¶

It is recommended to check in the following order:

1. Confirm that the Prerequisites have been completed, especially the DataKit and RUM collector configurations.
2. Confirm that the application device can access datakitUrl or datawayUrl.
3. If setProxy(...), setProxyAuthenticator(...), or setDns(...) are configured, confirm that the proxy, authentication information, DNS server, or DoH address are correct; these configurations only affect the SDK data upload requests.
4. Refer to Enable Debug Mode to view initialization and reporting logs.
5. Confirm that RUM has executed installRUMConfig and at least one collection item that needs verification is enabled.
6. The SDK enables deflate compression for uploaded data by default; if server or network link incompatibility is suspected, you can temporarily set setCompressIntakeRequests(false) for comparative verification.

Caching and Synchronization¶

• The SDK automatic synchronization uses a 10-second aggregation window, so it is normal for data not to be uploaded immediately after collection.
• If automatic synchronization is disabled via FTSDKConfig.setAutoSync(false) or FTSDK.setAutoSync(false), you need to manually call FTSDK.flushSyncData() in SDK Initialization.
• After SDK initialization, automatic synchronization can be re-enabled via FTSDK.setAutoSync(true).
• FTSDK.flushSyncData() does not wait for the 10-second aggregation window; it will schedule upload as soon as possible after flushing the pending RUM and Log worker queues.
• If local cache is abnormal, you can use FTSDK.clearAllData() to clear unreported data and then re-verify.

Automatic Network Request Collection¶

HttpInterceptorChain Not Working¶

If the automatic collection using HttpInterceptorChain from @kit.NetworkKit is not working, it is recommended to check the following in order:

1. Whether the current device or compilation target is HarmonyOS API 22 or above; this capability is not supported below API 22.
2. Whether the project has installed ft_sdk.har and ft_sdk_ext.har, and declared them in oh-package.json5 as @guancecloud/ft_sdk and @guancecloud/ft_sdk_ext, then completed ohpm install.
3. Whether setEnableTraceUserResource(true) is enabled; to automatically inject Trace Headers, you also need to enable setEnableAutoTrace(true) in the Trace configuration.
4. It is known that in concurrent request scenarios of @kit.NetworkKit, even if a separate HttpRequest and HttpInterceptorChain are created for each request, an exception may still be triggered: {"code":2300003,"message":"Invalid URL format or missing URL"}
5. If the above error occurs, it is recommended to downgrade to serial verification first; in concurrent scenarios, you can switch to RCP or Axios compatibility mode, or temporarily avoid using HttpInterceptorChain in high-concurrency links.

Resource Collection Not Working¶

If an HTTP request has been created and attached with an automatic collection interceptor, but SDK initialization and RUM configuration are executed later, it is possible that the request succeeds but no Resource data is generated.

It is recommended to check the following in order:

1. Whether the HttpRequest was created first, createFTHttpInterceptorChain() or applyFTHttpTrack() was called, and only later FTSDK.installRUMConfig() was executed.
2. Whether setEnableTraceUserResource(true) is enabled in the RUM configuration.

Reason explanation:

• When HttpInterceptorChain is created, it immediately reads the current RUM configuration to determine whether to enable Resource automatic collection.
• If this step occurs before FTSDK.installRUMConfig(), the SDK reads the default value of false.
• Even if SDK initialization is completed later, the already created automatic collection interceptor instance will not automatically refresh to the enabled state, so no Resource will be generated.

Suggested handling approaches:

1. First complete FTSDK.install(), FTSDK.installRUMConfig(), then create the HttpRequest and attach the HttpInterceptorChain.
2. If the request object or interceptor chain has been created in advance, you need to re-create and re-attach them after SDK initialization is complete.
3. If it is truly necessary to create the automatic collection object before SDK initialization, you can explicitly pass switches when creating it to avoid relying on default configuration values.

Optional writing example:

applyFTAxiosTrack(client, {
  enableTraceInterceptor: true,
  enableResourceInterceptor: true
});

sdk.init();

Note:

• Explicitly passing enableTraceInterceptor and enableResourceInterceptor only ensures that the automatic collection mechanism itself is enabled.
• Requests that have already been sent before SDK initialization is complete may still fail to generate or complete Resource data because the RUM context has not been fully initialized.
• Therefore, the recommended approach is still to complete SDK initialization first, then create and use the automatic collection object.

Similar handling approaches also apply to RCP and HttpInterceptorChain:

• Axios: applyFTAxiosTrack(client, { enableTraceInterceptor: true, enableResourceInterceptor: true })
• RCP: createFTRCPInterceptors(true, true) or createFTRCPTrackConfig({ enableTraceInterceptor: true, enableResourceInterceptor: true })
• HTTP: createFTHttpInterceptorChain({ enableTraceInterceptor: true, enableResourceInterceptor: true }) or applyFTHttpTrack(request, { enableTraceInterceptor: true, enableResourceInterceptor: true })

Related Documents¶

• Installation and Entry Page: See Application Access
• Initialization Parameters: See SDK Initialization
• RUM Network Collection: See RUM Configuration
• Trace Tracking: See Trace Configuration