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
version3.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
version3.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)
3.0.0
compatibility issue. The issue explains this problem, which can be resolved by upgrading AGP to version 3.1.0
or higher, or using a newer SDK version. Upgrading the version in app/build.gradle
will resolve this issue.
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.
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.
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
ordatawayUrl
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, disableFTRUMConfig
'senableTraceUserResource
andFTTraceConfig
'senableAutoTrace
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.
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 fromFTResourceEventListener.FTFactory
, and integrate via custom methods. -
ft-sdk >= 1.4.1
Customize a CustomEventListenerFactory inheriting from
FTResourceEventListener.FTFactory
, and setFTRUMConfig.setOkHttpEventListenerHandler
to customize theeventListenerFactory
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.