Troubleshooting¶

Compilation Troubleshooting¶

If errors occur during the compilation process, first check the compilation environment.

Runnable Compilation Environment¶

✅ Runnable Environment¶

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

Note: As Android Studio versions update, this version compatibility may also change. If you encounter compilation errors even though your environment meets the above conditions, please contact our developers.

⚠️ Compatible Runtime Environment¶

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

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

SDK Cannot Resolve Import¶

The above errors occur because the maven repository is not set correctly. 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)

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 was marked as Deprecated in AGP 7.0 and deprecated in AGP 8.0. ft-plugin:1.2.0 has been adapted accordingly. Please upgrade to the corresponding version to fix this error. For details, see Integration Configuration.

AndroidComponentsExtension ClassNotFoundException¶

AndroidComponentsExtension is a method supported by AGP 7.4.2. Compilation environments below this version will cause this error. You can use the ft-plugin-legacy version to fix this error. For details, 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. Resolve this issue by depending on org.ow2.asm:asm-commons:7.2 or above in the plugin configuration. You can confirm the actual asm-commons version used via ./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 above. Query the build environment via ./gradlew buildEnvironment to confirm. You can fix this by forcing a dependency on version 7.x or above. It is recommended to use version 7.2 or above.

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 Verification¶

Check Logcat to confirm 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¶

ft-sdk Debug Mode¶

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

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

Log Examples¶

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 turn off this configuration when releasing the Release version

ft-plugin Debug Mode¶

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

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

It is recommended to turn off this configuration when releasing the Release version

Convert SDK Internal Logs 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.

Session Replay Compose Playback Missing Pure Container Background Color¶

When using Jetpack Compose Session Replay, if a page contains containers like Row, Column, Box that are only used for layout and background drawing, for example, only Modifier.background(...) is set, but there is no text, click, semantics, or other accessibility information, this container may not appear in the Compose semantic node tree. Session Replay currently maps based on semantic nodes, so during playback, background colors may be missing, and Toolbar or block backgrounds may appear as default white.

If this background is important for playback display, you can add an empty semantic marker to the container to include it in the semantic node tree:

Row(
    modifier = Modifier
        .fillMaxWidth()
        .height(56.dp)
        .semantics { }
        .background(Color(0xFFFF6600))
)

This method does not change the interface display effect and is only used to help Session Replay capture this Compose container node. Subsequent SDK versions will continue to enhance the automatic collection capability for container backgrounds without semantics.

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 correctly. In debug mode, check the logs to determine upload issues.

• Check if datakit is uploading data to the corresponding workspace and if it is offline. This can be confirmed by logging into Guance and viewing "Infrastructure".

  

Compatibility Issue with OKhttp 3.12.+¶

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

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

Data Loss¶

Partial Data Loss¶

• If RUM data for a particular Session or several pieces of data in Log or Trace are missing, first exclude whether sampleRate < 1 is set in FTRUMConfig, FTLoggerConfig, FTTraceConfig.
• Check the network of the device uploading data and 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 writing to automatically set OkHttpClient Interceptor and EventListener, writing FTTraceInterceptor, FTResourceInterceptor, FTResourceEventListener.FTFactory. If Plugin is not used, please refer to here.

Custom WebView Automatic Collection Not Effective¶

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:

1. First, refer to Integration Configuration and enable logs in FTExt:

FTExt {
    showLog = true
    verboseLog = true
}

1. After recompiling, search for [FT-Plugin] and WEBVIEW related output in the Build logs, focusing on whether logs similar to the following appear:

[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 means Plugin has identified the current owner as a custom WebView and processed the corresponding calls.

If such logs never appear, but the actual calls are from business custom WebViews, it usually requires checking if the class has been added to knownWebViewClasses. This not only affects automatic collection identification but also whether Plugin treats internal methods of custom WebViews as ordinary methods for further ASM writing; if not correctly identified, runtime issues like loadUrl method loop calls may occur, ultimately manifesting as WebView white screen. During troubleshooting, you can also watch for logs like:

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

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

Solution:

Add knownWebViewClasses in FTExt to include the actual custom WebView classes used. It is recommended to add the base WebView class in the business first; if the inheritance hierarchy is deep, you can add both the base class and the currently used class. This allows Plugin to correctly identify WebView calls and avoid repeated ASM writing on internal methods of custom WebViews.

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 Plugin's known WebView list in advance. This solves the identification issue for custom WebViews and also allows Plugin to skip repeated writing of internal WebView methods, avoiding runtime loop calls and white screens.

OkHttpClient.build() Setting 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:

1. Timing Issue - SDK Initialization Not Completed. If OkHttpClient.Builder().build() is called before SDK initialization is complete, it will lead to loading empty configuration and loss of Resource related data. Check debug logs to confirm if the initialization order is correct.
2. Creation Method Issue. Not using the standard OkHttpClient.Builder().build() method to create OkHttpClient objects, for example, 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

//Logs 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.

Using Interceptor or EventListener for Secondary Data Processing¶

After Plugin ASM insertion, on top of the original project code, addInterceptor is added to OkHttpClient.Builder(), including FTTraceInterceptor and FTResourceInterceptor. Among these, the http request's body contentLength is used to calculate a unique id. Data from various stages of Resource is concatenated through this id for context. Therefore, if the integrator also uses addInterceptor when using Okhttp and performs secondary processing on the data, causing its size to change, it may lead to inconsistent id calculation across stages, resulting in data loss.

Solution:

ft-sdk < 1.4.1

By customizing the order of addInterceptor, let the SDK method calculate the id first to solve this problem. To avoid duplicate settings, the custom method needs to disable the enableTraceUserResource configuration in FTRUMConfig and the enableAutoTrace configuration in FTTraceConfig.

ft-sdk >= 1.4.1

In non-manual configuration scenarios, the SDK adapts to this issue automatically. If manual configuration has already been performed, ensure Interceptor is placed in a forward 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 failure to collect the current Resource data.

Solution:

ft-sdk < 1.6.13

1. Without changing the Okhttp version, perform manual configuration to solve this problem.

   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();
   

2. Upgrading Okhttp to version 4.5.0 or above can also solve this problem.

ft-sdk >= 1.6.13

In non-manual configuration scenarios, the SDK adapts to this issue automatically.

Error Data Loss Crash Type Data¶

• Confirm if other third-party SDKs with Crash capture functionality are used simultaneously. If so, 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 through logs.

  [FT-SDK]FTRUMConfigManager com.demo D  bindUserData xxxx
  
  ///---> Your data operations <-----
  
  [FT-SDK]FTRUMConfigManager com.demo D unbindUserData
  

Missing Custom Parameters or Incorrect Values¶

• Confirm that it is called in the correct scenario. FTRUMConfig.addGlobalContext and FTLoggerConfig.addGlobalContext are suitable for data that does not change within an application lifecycle, such as application channel, different Flavor attributes, etc. If dynamic scenarios require real-time response, 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 Issue When Enabling enableConsoleLog for Logs¶

If lag occurs, it might be due to excessively large log collection data. The principle of FTLoggerConfig.enableConsoleLog is to capture android.util.Log compilation, Java and Kotlin println. It is recommended to adjust the configuration parameters sampleRate, logPrefix, logLevelFilters in FTLoggerConfig as needed to eliminate or alleviate this issue.

Okhttp EventListener Integration SDK Becomes Ineffective¶

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

Solution:

ft-sdk < 1.4.1

Disable automatic Plugin AOP automatic setting FTRUMConfig setEnableTraceUserResource(false), and simultaneously customize a CustomEventListenerFactory that inherits FTResourceEventListener.FTFactory, using the custom method for integration.

ft-sdk >= 1.4.1

Customize a CustomEventListenerFactory that inherits FTResourceEventListener.FTFactory, and customize the ASM-written eventListenerFactory by setting FTRUMConfig.setOkHttpEventListenerHandler.

ft-sdk >= 1.6.7

In non-manual configuration scenarios, the SDK adapts to this issue automatically.

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 associate these two parts of data, the SDK needs to rely on a unique ID to concatenate the same network request. However, before 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 on the Request to distinguish unique identifiers for each request, thereby avoiding interference issues between identical requests. For setup instructions, refer to here.