Troubleshooting¶

Compilation Fault Troubleshooting¶

Compilation errors occur, 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 above
• Gradle version 5.4.0 or above
• Java version 8.0 or above
• Android minSdkVersion 21

Note: As Android Studio versions are updated, the compatibility of these versions may also change. If you encounter a compilation error even though your environment meets the above conditions, please contact our developers.

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

This environment does not support ft-plugin, and the automatic data capture part requires manual integration. For more information on manual integration, refer to here.

SDK Unable to Resolve Imports¶

The above errors occur because the maven repository is not correctly set up. 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')// All versions above 1.3.10 are acceptable
}

API 'android.registerTransform' is obsolete¶

In AGP 7.0, Transform has been marked as Deprecated and will be removed in AGP 8.0. ft-plugin:1.2.0 has already completed adaptation. Please upgrade the corresponding version to fix this error. See the specific explanation in Integration Configuration

AndroidComponentsExtension ClassNotFoundException¶

AndroidComponentsExtension is a method supported by AGP 7.4.2. Compilation environments below this version will generate this error. Use the ft-plugin-legacy version to fix this error. For detailed instructions, see Integration Configuration

java.lang.IllegalArgumentException:¶

• Invalid opcode 169

If this error occurs while using ft_plugin_legacy, it's a bug in asm-commons:7.0. The original issue is here. By depending on org.ow2.asm:asm-commons:7.2 or later in the plugin configuration, you can solve this problem. Confirm the real 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 a build environment using org.ow2.asm:asm7.x or higher. You can query the build environment via ./gradlew buildEnvironment to confirm this issue. This problem can be resolved by forcibly depending on a 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 Validation¶

Check Logcat to confirm whether there are logs with Level as Error and Tag starting 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 feature of the SDK through the following configuration. After enabling, the console LogCat will output SDK debugging logs. You can filter logs with the prefix [FT-SDK] 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 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 local network connection]

// 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] log outputs 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

SDK Internal Logs Converted 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, set this configuration before initializing the SDK

SDK Runs Normally But No Data¶

• Troubleshoot Datakit to confirm if it runs normally

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

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

  

Data Loss¶

Partial Data Loss¶

• If RUM loses some Session data or Log, or several pieces of data in Trace, first check if sampleRate < 1 was set in FTRUMConfig, FTLoggerConfig, FTTraceConfig.
• Investigate network and load issues with devices uploading data and devices 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 ft-plugin¶

Resource automatic collection requires assistance from Plugin ASM bytecode injection, automatically setting OkHttpClient Interceptor and EventListener, injecting FTTraceInterceptor, FTResourceInterceptor, FTResourceEventListener.FTFactory. If Plugin is not used, refer to here.

OkHttpClient.build() Called Before SDK Initialization¶

Plugin ASM injects automatically upon calling OkHttpClient.build(). If called before SDK initialization, it will load an empty configuration, leading to loss of Resource-related data. This scenario can be self-inspected based on debug mode logs.

// 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 unable to adjust initialization call order, choose manual integration

Interceptor or EventListener Performs Secondary Data Processing¶

After Plugin ASM inserts, it adds addInterceptor to OkHttpClient.Builder() in the original project code, adding FTTraceInterceptor and FTResourceInterceptor. These use the body contentLength from HTTP requests to calculate unique IDs, linking Resource data across different stages via this ID. Therefore, if the integrating party uses Okhttp and also adds addInterceptor, altering the size of the data, this leads to inconsistent ID calculations across stages, causing data loss.

Solution:

• ft-sdk < 1.4.1

  Customize the order of addInterceptor so that the SDK method calculates the ID first, solving this problem. To avoid duplicate settings, close the enableTraceUserResource in FTRUMConfig and enableAutoTrace in FTTraceConfig configurations.

• ft-sdk >= 1.4.1

  In non-manual settings scenarios, the SDK adapts itself to handle this issue. If manual settings have been made, ensure that the observed Interceptor is placed in a forward position.

Error Data Loss Crash Type Data¶

• Confirm whether other third-party SDKs with crash capturing capabilities are used simultaneously. If so, place the initialization method of the observing SDK after other SDKs.

Data Loss for Certain Field Information¶

User Data Fields¶

• Confirm correct invocation of user data binding methods. In debug mode, you can track this issue via logs.

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

Lost Custom Parameters or Numerical Errors¶

• Confirm correct invocation in the right context, such as FTRUMConfig.addGlobalContext, FTLoggerConfig.addGlobalContext suitable for scenarios where data does not change within an application cycle, such as app channel or app flavor attributes. If dynamic scenarios require real-time response, manually invoke RUM and Log interfaces.
• In debug mode, check [FT-SDK]SyncTaskManager logs to verify the correctness of custom field parameters.

Log Enablement enableConsoleLog Causes Lagging Issues¶

Possible reasons could be due to excessive log data collection. The principle of FTLoggerConfig.enableConsoleLog is capturing compiled android.util.Log, Java and Kotlin println. Adjust parameters under configurations like sampleRate, logPrefix, logLevelFilters to eliminate or alleviate this problem.

Okhttp EventListener Becomes Ineffective After Integrating SDK¶

After Plugin AOP ASM insertion, eventListenerFactory will be added to OkHttpClient.Builder(), covering the original eventListener or eventListenerFactory.

Solution:

• ft-sdk < 1.4.1

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

• ft-sdk >= 1.4.1

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

• ft-sdk >= 1.6.7

  The SDK adapts itself in non-manual settings scenarios to handle this issue.

TraceID Loss or Mismatch with Trace Propagation Header¶

When collecting complete 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, the ID was the same within the same request, leading to potential data corruption or loss issues in high-concurrency scenarios. Starting from version 1.6.10, you can distinguish each request uniquely by calling FTSDKConfig.setEnableOkhttpRequestTag(true) or explicitly adding ResourceID to the Request, thus avoiding interference between identical requests. Refer to here for setup methods.