Troubleshooting¶

Compilation Troubleshooting¶

If errors occur during the compilation process, the first step is to 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 also change. If you encounter compilation errors despite meeting the above 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, and the automatic data capture part needs to be manually integrated. For more information on manual integration, refer to here.

SDK Cannot Resolve Import¶

The above errors occur because the maven repository is not correctly set up. 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 due to a compatibility issue with AGP 3.0.0. This issue explains the problem. You can resolve this by upgrading AGP to 3.1.0 or higher, or by using a newer version of the SDK, upgrading the version in app/build.gradle.

dependencies {
    implementation('com.cloudcare.ft.mobile.sdk.tracker.agent:ft-sdk:1.3.10.beta01')//1.3.10 or higher
}

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 already been adapted. 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 is below this version, 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. You can resolve this by depending on org.ow2.asm:asm-commons: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 below 7.0

The current plugin version only supports build environments using org.ow2.asm:asm7.x or higher. Use ./gradlew buildEnvironment to query the build environment and confirm this issue. This problem can be fixed by forcibly depending on version 7.x or higher, preferably 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 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 with the following configuration. Once enabled, the SDK debug logs will be output in the console LogCat. You can filter the [FT-SDK] characters to locate the TrueWatch 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 disable this configuration when releasing the Release version

ft-plugin Debug Mode¶

You can enable the Plugin's debug logs with the following configuration. Once enabled, 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 show 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 must be set before SDK initialization

SDK Runs Normally but No Data¶

Check Datakit to see if it 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 TrueWatch and checking the "Infrastructure" section.

Compatibility Issue with Okhttp 3.12.+¶

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

Solution: Use ft-sdk >= 1.6.13 or okhttp 4.5.0 or higher to resolve this issue.

Data Loss¶

Partial Data Loss¶

If some Session data in RUM or a few Logs or Traces are missing, first check if 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 will release the SDK data processing objects, including cached data.

Resource Data Loss¶

Automatic Collection, ft-plugin Not Correctly Integrated¶

Resource automatic collection requires Plugin ASM bytecode writing to automatically set OkHttpClient Interceptor and EventListener, and write FTTraceInterceptor, FTResourceInterceptor, FTResourceEventListener.FTFactory. If Plugin is not used, refer to here

OkHttpClient.build() ASM Writing Issue¶

Plugin ASM will automatically inject 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 is 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 if the initialization order is correct. 2. Creation method issue. The standard OkHttpClient.Builder().build() method is not used 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

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

If the initialization call order cannot be adjusted, you can choose to manually integrate

Using Interceptor or EventListener to Process Data Twice¶

After Plugin ASM is inserted, addInterceptor will be added to OkHttpClient.Builder() in the original project code, adding FTTraceInterceptor and FTResourceInterceptor, which will use the http request's body contentLength to calculate a unique id. The data of each stage of Resource is concatenated through this id. Therefore, if the integration party also uses addInterceptor when using Okhttp and processes the data twice, causing the size to change, the id calculation at each stage will be inconsistent, resulting in data loss.

Solution:

ft-sdk < 1.4.1

By customizing the addInterceptor position order, let the SDK method calculate the id first to solve this problem. To avoid duplicate settings, the custom method needs to disable FTRUMConfig's enableTraceUserResource and FTTraceConfig's enableAutoTrace configurations.
ft-sdk >= 1.4.1

The SDK automatically adapts to this issue in non-manual settings. If manual settings have been made, ensure that Interceptor is 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 read, it may cause the current Resource data to not be collected.

Solution:

ft-sdk < 1.6.13

Without changing the Okhttp version, manually set up 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())//Encrypt or modify body
    .eventListenerFactory(new FTResourceEventListener.FTFactory());

OkHttpClient client = builder.build();

* Upgrading Okhttp to 4.5.0 or higher can also solve this problem. * ft-sdk >= 1.6.13

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

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 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 FTRUMConfig.addGlobalContext and FTLoggerConfig.addGlobalContext are called in the correct scenarios. These are suitable for data that does not change within an application cycle, such as application channel providers, different Flavor attributes of the application, etc. If dynamic scenarios require real-time response, manually call RUM and Log interfaces.
In debug mode, check the [FT-SDK]SyncTaskManager logs to verify the correctness of custom field parameters.

Lagging Issues When Enabling enableConsoleLog¶

If lagging occurs, it might be due to the large amount of data collected by the logs. The principle of FTLoggerConfig.enableConsoleLog is to capture android.util.Log in compilation, Java, and Kotlin println. It is recommended to adjust FTLoggerConfig configuration parameters such as sampleRate, logPrefix, and logLevelFilters to eliminate or alleviate this problem.

Okhttp EventListener Fails After Integrating SDK¶

After Plugin AOP ASM is inserted, eventListenerFactory will be 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 settings FTRUMConfig setEnableTraceUserResource(false), and customize a CustomEventListenerFactory that inherits FTResourceEventListener.FTFactory, and use custom methods 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 settings.

TraceID Missing or Mismatched with Trace Propagation Header¶

When collecting complete request data, information usually needs to be obtained from Interceptor and EventListener respectively. To effectively associate these two parts of data, the SDK needs to use a unique ID to concatenate the same network request. However, before version 1.6.10, this ID was the same in the same request, which could cause data confusion or loss in high concurrency scenarios. Since version 1.6.10, you can call FTSDKConfig.setEnableOkhttpRequestTag(true) or explicitly add ResourceID to the Request to distinguish unique identifiers for each request, avoiding interference between the same requests. For setup, refer to here