Troubleshooting¶

Compilation Troubleshooting¶

Errors occur during the compilation process, and you need to first check the compilation environment.

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 the Android Studio version updates, the compatibility of these versions may change as well. If you encounter a compilation error despite meeting the above conditions, please contact our developers.

⚠️ Compatible Running 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

This environment cannot use ft-plugin, and manual integration is required for automatic data capture parts. For more details on manual integration, refer to here.

SDK Unable to Resolve Imports¶

The above errors occur because the maven repository has not been set up 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')// Any version above 1.3.10 works
}

API 'android.registerTransform' is obsolete¶

In AGP 7.0, Transform has been marked as Deprecated and was removed in AGP 8.0. ft-plugin:1.2.0 has completed the adaptation. Please upgrade to the corresponding version to fix this error. For more details, see Integration Configuration

AndroidComponentsExtension ClassNotFoundException¶

AndroidComponentsExtension is a method supported by AGP 7.4.2. Compilation environments below this version will produce this error. You can use the ft-plugin-legacy version to fix this error. For more 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. This can be resolved by depending on org.ow2.asm:asm-commons:7.2 or higher 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 with org.ow2.asm:asm7.x or higher. You can query the build environment via ./gradlew buildEnvironment to confirm this issue. This issue can be fixed by forcibly depending on a version 7.x or higher, preferably 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 Verification¶

Check Logcat to confirm if there are any 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 debug functionality of the SDK through the following configuration. After enabling, the console LogCat will output SDK debugging 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 Example¶

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
// Below 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 local network connection is normal]

// Below 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 Plugin debug logs through the following configuration. After enabling, you can find [FT-Plugin] output logs in the Build output logs. Use this to view the Plugin ASM writing situation.

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

It is recommended to disable 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 should be set before initializing the SDK

SDK Runs Normally But No Data¶

• Troubleshoot Datakit to ensure it runs normally

• Confirm that the SDK upload address datakitUrl or datawayUrl is configured correctly and initialized properly. In debug mode, check logs to diagnose upload issues.

• Ensure that datakit uploads data to the corresponding workspace and is not in offline mode. This can be confirmed by logging into Guance and checking "Infrastructure".

  

Data Loss¶

Partial Data Loss¶

• If RUM Session data or some Log or Trace data is lost, first check if sampleRate < 1 is set in FTRUMConfig, FTLoggerConfig, FTTraceConfig.
• Investigate network and load issues with devices uploading data and those running datakit.
• Confirm correct invocation of FTSdk.shutDown, which releases SDK data processing objects, including cached data.

Resource Data Loss¶

Automatic Collection, Not Correctly Integrated with ft-plugin¶

Automatic Resource collection requires Plugin ASM bytecode injection to automatically configure OkHttpClient Interceptor and EventListener, injecting FTTraceInterceptor, FTResourceInterceptor, FTResourceEventListener.FTFactory. If not using Plugin, refer to here.

OkHttpClient.build() ASM Injection Issues¶

Plugin ASM automatically injects network collection capabilities when OkHttpClient.Builder().build() is called. The following two scenarios may cause network collection failures: 1. Timing issues - SDK initialization incomplete. If OkHttpClient.Builder().build() is called before SDK initialization completes, it may lead to loading empty configurations and losing Resource-related data. Check debug logs to confirm initialization order. 2. Creation method issues. OkHttpClient objects are not created using standard OkHttpClient.Builder().build() methods, such as 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 `OkHttpClient.Builder.build()` is called
//(must be called after SDK initialization)
[FT-SDK]AutoTrack   com.ft  D  trackOkHttpBuilder    

If adjusting initialization call order is not possible, choose manual integration

Data Processed Twice Using Interceptor or EventListener¶

After Plugin ASM inserts, addInterceptor is added to OkHttpClient.Builder() to include FTTraceInterceptor and FTResourceInterceptor. These interceptors use body contentLength from HTTP requests to calculate unique IDs, linking Resource data across different stages using this ID. If integration involves adding addInterceptor and modifying data size, this could result in inconsistent ID calculations across stages, causing data loss.

Resolution:

• ft-sdk < 1.4.1

  Adjust the custom addInterceptor position order so the SDK calculates the ID first. To avoid duplicate settings, disable FTRUMConfig's enableTraceUserResource and FTTraceConfig's enableAutoTrace configurations.

• ft-sdk >= 1.4.1

  The SDK adapts to this issue automatically unless manual settings are applied. Ensure the observed Interceptor is placed earlier.

Error Data Loss Crash Type Data¶

• Confirm whether other third-party SDKs with Crash capturing functionality are being used simultaneously. If so, place the observation SDK initialization method after other SDKs.

Missing Field Information in Data¶

User Data Fields¶

• Confirm correct invocation of user data binding methods. In debug mode, logs can be used to trace this issue.

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

Lost Custom Parameters or Incorrect Values¶

• Confirm invocation in the correct scenario for FTRUMConfig.addGlobalContext, FTLoggerConfig.addGlobalContext, suitable for scenarios where data does not change within an application lifecycle, such as app distributors or different Flavor properties. For dynamic scenarios requiring real-time response, manually invoke RUM and Log interfaces.
• In debug mode, check [FT-SDK]SyncTaskManager logs to validate the correctness of custom field parameters.

Log Enablement Causes Lag with enableConsoleLog¶

Possible reasons for lag could be excessive log data collection. FTLoggerConfig.enableConsoleLog captures compiled android.util.Log, Java and Kotlin println. Adjust FTLoggerConfig settings for sampleRate, logPrefix, logLevelFilters parameters to eliminate or alleviate this issue.

Okhttp EventListener Integration Becomes Ineffective After SDK Integration¶

After Plugin AOP ASM insertion, eventListenerFactory is added to OkHttpClient.Builder(), overriding the original eventListener or eventListenerFactory.

Resolution:

• ft-sdk < 1.4.1

  Disable automatic Plugin AOP auto-settings by setting FTRUMConfig setEnableTraceUserResource(false), then customize a CustomEventListenerFactory inheriting from FTResourceEventListener.FTFactory, and integrate via custom methods.

• ft-sdk >= 1.4.1

  Customize a CustomEventListenerFactory inheriting from FTResourceEventListener.FTFactory, and set FTRUMConfig.setOkHttpEventListenerHandler to customize the eventListenerFactory written by ASM.

• ft-sdk >= 1.6.7

  The SDK adapts automatically unless manual settings are applied.

TraceID Lost or Does Not Match Trace Propagation Header¶

When collecting full request data, information is typically obtained from both Interceptor and EventListener. To effectively associate 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 across the same requests, leading to potential data corruption or loss in high-concurrency scenarios. Starting from version 1.6.10, calling FTSDKConfig.setEnableOkhttpRequestTag(true) or explicitly adding a ResourceID to each Request can distinguish unique identifiers for each request, avoiding interference between identical requests. Refer to here for configuration details.