Troubleshooting¶

Compilation Troubleshooting¶

If an error occurs 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 higher
• Gradle version 5.4.0 or higher
• Java version 8.0 or higher
• Android minSdkVersion 21

Note: As Android Studio updates its versions, compatibility with these versions may change. If your compilation environment meets the above conditions but you still encounter compilation errors, please contact our developers.

⚠️ Compatible 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; data auto-capturing needs to be manually integrated. For more information on manual integration, refer here.

SDK Import Cannot Be Resolved¶

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')//any version above 1.3.10 works
}

API 'android.registerTransform' is obsolete¶

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

AndroidComponentsExtension ClassNotFoundException¶

AndroidComponentsExtension is supported starting from AGP 7.4.2. Environments below this version will result in this error. Using the ft-plugin-legacy version can 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 due to a bug in asm-commons:7.0. The original issue can be found here. Resolve this by adding a dependency on org.ow2.asm:asm-commons version 7.2 or higher in the plugin configuration. Use ./gradlew buildEnvironment to confirm the actual asm-commons version being used.

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:asm version 7.x or higher. Use ./gradlew buildEnvironment to query the build environment and confirm this issue. This issue 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 Verification¶

Check Logcat to confirm whether there are logs with level Error and tag [FT-SDK] prefix.

[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 feature of the SDK by the following configuration. After enabling, the console LogCat will output SDK debugging logs. You can filter the logs by the character [FT-SDK] to locate the Guance SDK logs.

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

Log Example¶

Data Sync¶

// 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 sync 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 debug log of the Plugin through the following configuration. After enabling, you can find the [FT-Plugin] output logs in the Build output logs. This helps 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 needs to be set before initializing the SDK

SDK Runs Normally But No Data Is Shown¶

• Troubleshoot Datakit to ensure it is running normally

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

• Ensure that datakit is uploading data to the correct workspace and is not in offline status. This can be confirmed by logging into Guance and checking the 「Infrastructure」 section.

  

Data Loss¶

Partial Data Loss¶

• If a Session data loss occurs in RUM or some data in Log, Trace is missing, first exclude whether sampleRate < 1 has been set in FTRUMConfig, FTLoggerConfig, FTTraceConfig.
• Investigate network and load problems between the device uploading data and the device where datakit is installed.
• Confirm correct invocation of FTSdk.shutDown, which releases SDK data processing objects, including cached data.

Resource Data Loss¶

Automatic collection without proper integration of ft-plugin¶

Resource automatic collection requires the help of Plugin ASM bytecode injection, automatically setting up FTTraceInterceptor, FTResourceInterceptor, FTResourceEventListener.FTFactory for OkHttpClient Interceptor and EventListener. If the Plugin is not used, refer to here.

OkHttpClient.build() ASM Injection Issues¶

The Plugin ASM automatically injects network collection functionality when the app calls OkHttpClient.Builder().build(). The following two situations may cause network collection failure: 1. Timing issue - SDK initialization is not complete. If OkHttpClient.Builder().build() is called before the SDK initialization is complete, it will load empty configurations, causing Resource-related data loss. Check the debug logs to confirm the correct initialization order. 2. Creation method issue. Standard OkHttpClient.Builder().build() method was not used to create the OkHttpClient object, e.g., directly instantiating OkHttpClient or using other creation 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

// SDK OkHttpClient.Builder.build() call logs
// (should be invoked after SDK initialization)
[FT-SDK]AutoTrack   com.ft  D  trackOkHttpBuilder    

If adjusting the initialization call sequence is not possible, choose to integrate via manual method

Secondary Processing of Data Through Interceptor or EventListener¶

After Plugin ASM insertion, addInterceptor will be added to the original project code within OkHttpClient.Builder(), inserting FTTraceInterceptor and FTResourceInterceptor. These interceptors use the http request body contentLength to participate in unique ID calculation. Resource data stages are linked via this ID. Therefore, if the integrating party uses Okhttp and adds addInterceptor while performing secondary processing on the data, changing its size, it may cause inconsistency in ID calculations across stages, leading to data loss.

Solutions:

• ft-sdk < 1.4.1

  Customize the position order of addInterceptor as shown here, allowing the SDK to compute the ID first. To avoid duplicate setup, customize by disabling FTRUMConfig's enableTraceUserResource and FTTraceConfig's enableAutoTrace.

• ft-sdk >= 1.4.1

  The SDK self-adapts to resolve this issue in non-manual setup scenarios. If manual setup is already done, ensure Interceptor is positioned early enough.

Error Data Loss Crash Type Data¶

• Confirm whether other third-party SDKs with crash capture functionality are also being used. If so, place the 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 operations <-----
  
  [FT-SDK]FTRUMConfigManager com.demo D unbindUserData
  

Missing Custom Parameters or Incorrect Values¶

• Confirm correct invocation scenario for FTRUMConfig.addGlobalContext, FTLoggerConfig.addGlobalContext. These are suitable for scenarios where data does not change within an application cycle, such as application distributors, different Flavor attributes of the app. If dynamic scenarios requiring real-time response are needed, manually invoke RUM and Log interfaces.
• In debug mode, check [FT-SDK]SyncTaskManager logs. These logs can verify the correctness of custom field parameters.

Logging enableConsoleLog Causing Lag Issues¶

Potential reasons could be excessive data collection. FTLoggerConfig.enableConsoleLog captures compiled android.util.Log, Java, and Kotlin println. It is recommended to adjust FTLoggerConfig configuration parameters like sampleRate, logPrefix, and logLevelFilters as needed to eliminate or alleviate this issue.

Okhttp EventListener Integration SDK Becomes Ineffective¶

After Plugin AOP ASM insertion, eventListenerFactory will be added to OkHttpClient.Builder() in the original project code, overriding any existing eventListener or eventListenerFactory.

Solutions:

• ft-sdk < 1.4.1

  Disable automatic Plugin AOP setup FTRUMConfig setEnableTraceUserResource(false) and create a custom CustomEventListenerFactory that extends FTResourceEventListener.FTFactory, integrating via custom method.

• ft-sdk >= 1.4.1

  Create a custom CustomEventListenerFactory extending FTResourceEventListener.FTFactory and customize the ASM-injected eventListenerFactory by setting FTRUMConfig.setOkHttpEventListenerHandler.

• ft-sdk >= 1.6.7

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

TraceID Lost or Does Not Match Trace Propagation Header¶

During complete request data collection, information typically needs to be obtained from both Interceptor and EventListener. To associate these two parts of data effectively, the SDK relies on a unique ID to link the same network request. However, prior to version 1.6.10, this ID was identical for the same request, potentially causing data disorder or loss in high concurrency scenarios. Starting from version 1.6.10, calling FTSDKConfig.setEnableOkhttpRequestTag(true) or explicitly adding a ResourceID to the Request allows distinguishing each request with a unique identifier, thus avoiding interference between identical requests. Refer to this link for setup instructions.