Troubleshooting¶

Compilation Troubleshooting¶

If an error occurs 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 above
• gradle version 5.4.0 or above
• java version 8.0 or above
• Android minSdkVersion 21

Note: As the Android Studio version updates, the version compatibility here will also change. If you encounter compilation errors even though your compilation 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

The ft-plugin cannot be used in this environment. The automatic data capture part requires manual integration. For more information on manual integration, please refer to here.

SDK Cannot Resolve Import¶

The above error occurs 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')//1.3.10 or above versions are acceptable
}

API 'android.registerTransform' is obsolete¶

Transform was marked as Deprecated in AGP 7.0 and has been 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 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. Resolve this issue by depending on a version of org.ow2.asm:asm-commons above 7.2 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

The current plugin version only supports build environments using org.ow2.asm:asm7.x or above. Use ./gradlew buildEnvironment to query the build environment and confirm this issue. This issue can be fixed by forcibly depending 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 Check¶

Check Logcat to confirm if there are logs with Level 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 the 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 the Plugin's debug logs through the following configuration. After enabling, you can find the [FT-Plugin] output logs in the Build output logs. Use this to view the Plugin ASM write status.

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

// >= 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 initializing the SDK

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 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 Guance and checking the "Infrastructure" section.

  

Compatibility Issue with OKhttp 3.12.+¶

For ft-sdk < 1.6.13, if data upload compression is enabled FTSDKConfig.setCompressIntakeRequests(true), you may find that the SDK collection is successful, but during data synchronization, there are no error prompts, and no http code logs are printed.

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

Data Loss¶

Loss of Partial Data¶

• If a RUM Session data or a few Log or Trace data 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 the SDK data processing object, including cached data.

Resource Data Loss¶

Automatic Collection, ft-plugin Not Correctly Integrated¶

Automatic Resource collection requires 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

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. Calling OkHttpClient.Builder().build() before the SDK initialization is complete will result in loading an empty configuration, losing Resource related data. Check the debug logs to confirm the initialization order is correct.
2. Creation Method Issue. Not using the standard OkHttpClient.Builder().build() method to create the OkHttpClient object, 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

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

Using Interceptor or EventListener for Secondary Data Processing¶

After Plugin ASM insertion, addInterceptor will be added to the original project code in OkHttpClient.Builder(), adding FTTraceInterceptor and FTResourceInterceptor respectively. The http request's body contentLength will be used to calculate a unique id. Data from various stages of Resource are contextually linked through this id. Therefore, if the integrator also uses addInterceptor when using Okhttp and performs secondary processing on the data, changing its size, it will lead to inconsistent id calculation across stages, resulting in data loss.

Solution:

ft-sdk < 1.4.1

Solve this problem by customizing the order of addInterceptor, allowing the SDK method to calculate the id first. To avoid duplicate settings, the custom method requires turning off 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 been performed, ensure the Interceptor is in a forward position.

OKhttp 3.12.+ Compatibility Issue¶

For 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

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

   OkHttpClient.Builder builder = new OkHttpClient.Builder()
       .addInterceptor(new CustomReadReponseInterceptor())//Read 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

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 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 operation <-----
  
  [FT-SDK]FTRUMConfigManager com.demo D unbindUserData
  

Loss of Custom Parameters or Incorrect Values¶

• Confirm that it is called in the correct scenario. FTRUMConfig.addGlobalContext, FTLoggerConfig.addGlobalContext are suitable for data that does not change during an application cycle, such as application channel provider, different Flavor attributes of the application, etc. If dynamic scenarios require real-time response, you need to manually call the RUM and Log interfaces.
• In debug mode, check the [FT-SDK]SyncTaskManager logs to verify the correctness of custom field parameters.

Lag Issue When Enabling enableConsoleLog for Logs¶

If lag occurs, the possible reason is that the log collection data is too large. The principle of FTLoggerConfig.enableConsoleLog is to capture android.util.Log compilation, 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 Becomes Ineffective After Integrating SDK¶

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

Solution:

ft-sdk < 1.4.1

Turn off automatic Plugin AOP automatic setting FTRUMConfig setEnableTraceUserResource(false), and customize a CustomEventListenerFactory that inherits FTResourceEventListener.FTFactory, and use 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

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

TraceID Missing or Not Matching Trace Propagation Header¶

When performing complete request data collection, information usually needs to be obtained from both Interceptor and EventListener. To effectively associate these two parts of data, the SDK needs to use 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 unique identifiers for each request, thereby avoiding interference issues between identical requests. For setup instructions, please refer to here