Troubleshooting¶

Compilation Troubleshooting¶

If errors occur during the compilation process, the compilation environment should be checked first.

Runnable Compilation Environment¶

✅ Runnable Environment¶

AGP com.android.tools.build:gradle version 3.5.0 or higher
Gradle version 5.4.0 or higher
Java version 8.0 or higher
Android minSdkVersion 21

Note: As Android Studio versions update, the compatibility of these versions may also change. If you encounter compilation errors despite meeting the above environment conditions, please contact our developers.

⚠️ Compatible Runtime Environment¶

AGP com.android.tools.build:gradle version 3.0.1 or higher
Gradle version 4.8.1 or higher
Java version 8.0 or higher
Android minSdkVersion 21

In this environment, ft-plugin cannot be used. The automatic data capture part needs to be integrated manually. For more details on manual integration, refer to Manual Integration.

SDK Import Cannot Be Resolved¶

The above errors occur because the maven repository is not correctly configured. Please refer to the configuration here.

Compilation Errors¶

Desugaring Error¶

>Task :app:transformClassesWithStackFramesFixerForDebug
    Exception in thread "main" java.lang.IllegalStateException: Expected a load for Ljava/lang/String; to set up parameter 0 for com/ft/sdk/FTRUMGlobalManager$$Lambda$11 but got 95
        at com.google.common.base.Preconditions.checkState (Preconditions.java:756)
        at com.google.devtools.build. android.desugar.LambdaDesugaring$InvokedynamicRewriter .attemptAllocationBeforeArgumentLoadsLambdaDesugaring.java:535)
        at com.google.devtools.build.android.desugar.LambdaDesugaring$InvokedynamicRewriter.visitInvokeDynamicInsn
        (LambdaDesugaring.java: 420)
        at org.objectweb.asm.ClassReader.a(Unknown Source)
        at org.objectweb.asm.ClassReader.b(Unknown Source)
        at org.objectweb.asm.ClassReader.accept(Unknown Source)
        at org.objectweb.asm.ClassReader.accept(Unknown Source)
        at com.google.devtools.build. android.desugar. Desugar.desugarClassesInInput (Desugar.java:401) at com.google.devtools.build.android.desugar.Desugar.desugar0neInput(Desugar.java:326) at com.google.devtools.build.android.desugar. Desugar.desugar (Desugar.java:280) at com.google.devtools.build.android.desugar. Desugar.main (Desugar.java:584)

If the above error occurs during compilation, it is caused by a compatibility issue with AGP 3.0.0. This issue explains the problem. It can be resolved by upgrading AGP to version 3.1.0 or higher, or by using a newer version of the SDK. Upgrade the version in app/build.gradle.

dependencies {
    implementation('com.cloudcare.ft.mobile.sdk.tracker.agent:ft-sdk:1.3.10.beta01')//Versions 1.3.10 and above are acceptable.
}

API 'android.registerTransform' is obsolete¶

Transform has been marked as Deprecated in AGP 7.0 and has been removed in AGP 8.0. ft-plugin:1.2.0 has been adapted accordingly. Please upgrade to the corresponding version to fix this error. For specific instructions, see Integration Configuration.

AndroidComponentsExtension ClassNotFoundException¶

AndroidComponentsExtension is a method supported by AGP 7.4.2. If the compilation environment version is lower than this, this error will occur. You can use the ft-plugin-legacy version to fix this error. For specific instructions, see Integration Configuration.

java.lang.IllegalArgumentException:¶

Invalid opcode 169

If this error occurs while using ft_plugin_legacy, it is a bug in the asm-commons:7.0 version. The original issue is here. This problem can be resolved by depending on version org.ow2.asm:asm-commons:7.2 or higher in the plugin configuration. You can verify the actual asm-commons version used by running ./gradlew buildEnvironment.

buildscript {
    dependencies {
        classpath 'com.cloudcare.ft.mobile.sdk.tracker.plugin:ft-plugin-legacy:[version]'
        // Add dependency
        classpath 'org.ow2.asm:asm-commons:7.2'
    }
}

org.ow2.asm:asm version lower than 7.0

Currently, the plugin version only supports build environments using org.ow2.asm:asm7.x or higher. You can query the build environment via ./gradlew buildEnvironment to confirm. It can be fixed by forcing a dependency on version 7.x or higher. It is recommended to use version 7.2 or higher.

buildscript {
    dependencies {
        classpath 'com.cloudcare.ft.mobile.sdk.tracker.plugin:ft-plugin-legacy:[version]'
         // Add dependency
        classpath 'org.ow2.asm:asm:7.2'
        classpath 'org.ow2.asm:asm-commons:7.2'
    }
}

SDK Initialization Exception Check¶

Check Logcat to see if there are logs with Level as Error and Tag prefixed with [FT-SDK].

[FT-SDK] com.demo E Please install the SDK first (call FTSdk.install(FTSDKConfig ftSdkConfig) when the application starts)

Enable Debug Mode¶

Historical Compatibility Anchor¶

ft-sdk Debug Mode¶

You can enable the SDK's debug function with the following configuration. After enabling, the console LogCat will output SDK debug logs. You can filter for the [FT-SDK] string to locate the TrueWatch SDK logs.

  val config = FTSDKConfig.builder(datakitUrl).setDebug(true)
  FTSdk.install(config)

Log Samples¶

Data Synchronization¶

//Check if the upload address is correctly entered into the SDK configuration.
[FT-SDK]FTHttpConfigManager com.demo D  serverUrl ==>
                                    Datakit Url:http://10.0.0.1:9529
//The following are connection error logs.
[FT-SDK]SyncTaskManager com.demo   E  Network not available Stop poll
[FT-SDK]SyncTaskManager com.demo   E  ↵
            1:Sync Fail-[code:10003,response:failed to connect to 10.0.0.1 (port 9529) from ↵
            10.0.2.16 (port 47968) after 10000ms,Check if the local network connection is normal]

//The following are normal synchronization logs.
[FT-SDK]SyncTaskManager com.demo   D  Sync Success-[code:200,response:]

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

ft-plugin Debug Mode¶

You can enable the Plugin's debug logs with the following configuration. After enabling, you can find the output logs prefixed with [FT-Plugin] in the Build output logs. Use this to view the ASM insertion status of the Plugin.

FTExt {
    //Whether to display Plugin logs, default is false.
    showLog = true
}

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

SDK Internal Logs Converted to Cache Files¶

// >= 1.4.6
// Default path: /data/data/{package_name}/files/LogInner.log
LogUtils.registerInnerLogCacheToFile()

// >= 1.4.5+
val cacheFile = File(filesDir, "LogCache.log")
LogUtils.registerInnerLogCacheToFile(cacheFile)

To ensure the integrity of internal logs, this configuration must be set before SDK initialization.

SDK Runs Normally but No Data¶

Check if Datakit is running normally.
Confirm that the SDK upload address datakitUrl or datawayUrl is configured correctly and initialized properly. In debug mode, check the logs to diagnose upload issues.
Check if datakit is uploading data to the corresponding workspace and if it is offline. This can be confirmed by logging into TrueWatch and viewing the "Infrastructure".

Compatibility Issue with OKhttp 3.12.+¶

In ft-sdk < 1.6.13 versions, if data compression is enabled via FTSDKConfig.setCompressIntakeRequests(true), SDK data collection works normally, but no error prompts or HTTP status code logs will be output during the data synchronization phase.

Solution: Using ft-sdk >= 1.6.13 or okhttp 4.5.0 and above can resolve this issue.

Data Loss¶

Partial Data Loss¶

If data from a specific RUM Session or a few pieces of data from Log or Trace are lost, first check if sampleRate < 1 is set in FTRUMConfig, FTLoggerConfig, or FTTraceConfig.
Check the network of the device uploading data, as well as the network and load of the device where datakit is installed.
Confirm that FTSdk.shutDown is called correctly. This method releases SDK data processing objects, including cached data.

Resource Data Loss¶

Automatic Collection, ft-plugin Not Correctly Integrated¶

Automatic Resource collection relies on Plugin ASM bytecode insertion to automatically configure OkHttpClient Interceptor and EventListener, inserting FTTraceInterceptor, FTResourceInterceptor, and FTResourceEventListener.FTFactory. If Plugin is not used, please refer to here.

Custom WebView Automatic Collection Not Taking Effect¶

If native WebView page collection works normally, but custom WebView pages do not trigger the expected automatic collection, it is recommended to first use Plugin logs to determine if it is a WebView identification issue.

Troubleshooting Steps:

First, refer to the Integration Configuration to enable logs in FTExt:

FTExt {
    showLog = true
    verboseLog = true
}

After recompiling, search the Build logs for [FT-Plugin] and WEBVIEW related outputs. Pay special attention to logs similar to the following:

[FT-Plugin]:TARGET_CUSTOM_WEBVIEW_METHOD-> owner:com/example/CustomWebView, class:com/example/WebViewActivity$2, super:java/lang/Object, method:loadUrl(Ljava/lang/String;)V | onItemSelected(Landroid/widget/AdapterView;Landroid/view/View;IJ)V

If such TARGET_CUSTOM_WEBVIEW_METHOD logs appear, it indicates that the Plugin has identified the current owner as a custom WebView and has processed the corresponding calls.

If such logs never appear, but the actual calls are from a business custom WebView, you usually need to check if that class has been added to knownWebViewClasses. This not only affects automatic collection identification but also determines whether the Plugin will treat the custom WebView's internal methods as ordinary methods for further ASM insertion. If not correctly identified, runtime issues like infinite loops in loadUrl methods may occur, ultimately manifesting as a white screen in the WebView. You can also monitor logs like the following during troubleshooting:

knownWebviews.contains(owner) = false
owner: com/example/CustomWebView

This usually indicates that the current class has not been recognized as a WebView by the Plugin.

Solution:

Add knownWebViewClasses in FTExt to include the actual custom WebView classes used. It is recommended to add the base WebView class in your business first. If the inheritance hierarchy is deep, you can add both the base class and the currently used class. This ensures the Plugin correctly identifies WebView calls and avoids duplicate ASM insertion for the custom WebView's internal methods.

FTExt {
    showLog = true
    verboseLog = true
    knownWebViewClasses = [
        'com.example.web.BaseWebView',
        'com.example.web.CustomWebView'
    ]
}

The purpose of knownWebViewClasses is to add business custom WebViews to the Plugin's known WebView list in advance. This solves the identification issue for custom WebViews and also helps the Plugin skip duplicate insertion for WebView internal methods, preventing runtime infinite loops and white screens.

OkHttpClient.build() Setup Issue¶

Plugin ASM automatically injects network collection functionality when the application calls OkHttpClient.Builder().build(). The following two situations may cause network collection to fail:

Timing Issue - SDK Initialization Not Complete. If OkHttpClient.Builder().build() is called before SDK initialization is complete, it will load an empty configuration, resulting in the loss of Resource-related data. Check the debug logs to confirm the initialization order is correct.
Creation Method Issue. The OkHttpClient object is not created using the standard OkHttpClient.Builder().build() method, e.g., directly instantiating OkHttpClient or using other construction methods.

//SDK initialization logs
[FT-SDK]FTSdk   com.ft  D  initFTConfig complete
[FT-SDK]FTSdk   com.ft  D  initLogWithConfig complete
[FT-SDK]FTSdk   com.ft  D  initRUMWithConfig complete
[FT-SDK]FTSdk   com.ft  D  initTraceWithConfig complete

//Log printed when SDK OkHttpClient.Builder.build() is called
//(Needs to be called after SDK initialization)
[FT-SDK]AutoTrack   com.ft  D  trackOkHttpBuilder

If the initialization call order cannot be adjusted, you can choose the manual method for integration.

Secondary Processing of Data Using Interceptor or EventListener¶

After Plugin ASM insertion, addInterceptor is added to OkHttpClient.Builder() in the original project code, inserting FTTraceInterceptor and FTResourceInterceptor. These use the http request's body contentLength to calculate a unique id. Data from various stages of Resource is contextually linked through this id. Therefore, if the integrator also uses addInterceptor with Okhttp and performs secondary processing on the data, changing its size, it can lead to inconsistent id calculations across stages, resulting in data loss.

Solution:

ft-sdk < 1.4.1

By customizing the order of addInterceptor, allowing the SDK method to calculate the id first, can resolve this issue. To avoid duplicate settings, the custom method requires disabling the enableTraceUserResource configuration in FTRUMConfig and the enableAutoTrace configuration in FTTraceConfig.

ft-sdk >= 1.4.1

The SDK automatically adapts to this issue in non-manual setup scenarios. If manual setup has already been performed, ensure the Interceptor is placed in a leading position.

Compatibility Issue with OKhttp 3.12.+¶

ft-sdk < 1.6.13 If the Interceptor used reads the response body content for reading, it may cause the current Resource data to not be collected.

Solution:

ft-sdk < 1.6.13

Without changing the Okhttp version, perform manual setup to resolve this issue.

OkHttpClient.Builder builder = new OkHttpClient.Builder()
    .addInterceptor(new CustomReadReponseInterceptor())//Reads response body
    .addInterceptor(new FTTraceInterceptor())
    .addInterceptor(new FTResourceInterceptor())
    .addInterceptor(new CustomRequestBodyFixInterceptor())//Has encryption or modifies body
    .eventListenerFactory(new FTResourceEventListener.FTFactory());

OkHttpClient client = builder.build();

Upgrading Okhttp to version 4.5.0 or above can also resolve this issue.

ft-sdk >= 1.6.13

The SDK automatically adapts to this issue in non-manual setup scenarios.

Error Data Loss Crash Type Data¶

Confirm if other third-party SDKs with Crash capture functionality are being used simultaneously. If yes, the SDK initialization method needs to be placed after other SDKs.

Missing Specific Field Information in Data¶

User Data Fields¶

Confirm that the user data binding method is called correctly. In debug mode, you can track this issue via logs.

[FT-SDK]FTRUMConfigManager com.demo D  bindUserData xxxx

///---> Your data operation <-----

[FT-SDK]FTRUMConfigManager com.demo D unbindUserData

Missing Custom Parameters or Incorrect Values¶

Confirm that calls are made in the correct context. FTRUMConfig.addGlobalContext and FTLoggerConfig.addGlobalContext are suitable for data that does not change during an application lifecycle, such as application channel, different Flavor attributes, etc. If dynamic, real-time responses based on scenarios are needed, use the manual RUM and Log interfaces.
In debug mode, check the [FT-SDK]SyncTaskManager logs. You can use these logs to verify the correctness of custom field parameters.

Lag Issues When Enabling enableConsoleLog for Logs¶

If lag occurs, the possible reason is that the data collected by log capture is too large. The principle of FTLoggerConfig.enableConsoleLog is to capture android.util.Log, Java, and Kotlin println. It is recommended to adjust the sampleRate, logPrefix, and logLevelFilters parameters in FTLoggerConfig configuration as needed to eliminate or alleviate this issue.

Okhttp EventListener Fails After SDK Integration¶

After Plugin AOP ASM insertion, eventListenerFactory is added to OkHttpClient.Builder() in the original project code, which will overwrite the original eventListener or eventListenerFactory.

Solution:

ft-sdk < 1.4.1

Disable automatic Plugin AOP setup by setting FTRUMConfig setEnableTraceUserResource(false). Then, create a custom CustomEventListenerFactory that inherits FTResourceEventListener.FTFactory, and use the custom method for integration.

ft-sdk >= 1.4.1

Create a custom CustomEventListenerFactory that inherits FTResourceEventListener.FTFactory. Customize the ASM-inserted eventListenerFactory by setting FTRUMConfig.setOkHttpEventListenerHandler.

ft-sdk >= 1.6.7

The SDK automatically adapts to this issue in non-manual setup scenarios.

TraceID Missing or Not Corresponding with Trace Propagation Header¶

When performing complete request data collection, information typically needs to be obtained from both Interceptor and EventListener. To effectively correlate these two parts of data, the SDK relies on a unique ID to link the same network request. However, prior to version 1.6.10, this ID was the same for identical requests, which could lead to data confusion or loss in high-concurrency scenarios. Starting from version 1.6.10, you can call FTSDKConfig.setEnableOkhttpRequestTag(true) or explicitly add a ResourceID to the Request to distinguish a unique identifier for each request, thereby avoiding interference between identical requests. For setup instructions, please refer to here.