Troubleshooting¶
Compilation Troubleshooting¶
When errors occur during the compilation process, the compilation environment should be checked first.
Runnable Compilation Environment¶
✅ Runnable Environment¶
- AGP
com.android.tools.build:gradle
version3.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 compatibility of these versions will also change. If you encounter compilation errors despite meeting the above conditions, please contact our developers.
⚠️ Compatible Runnable Environment¶
- AGP
com.android.tools.build:gradle
version3.0.1
or above - Gradle version
4.8.1
or above - Java version
8.0
or above - 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 error occurs 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)
3.0.0
. This issue explains the problem. You can resolve it by upgrading to AGP 3.1.0
or above, or by using a newer version of the SDK. Upgrade the version in app/build.gradle
as follows:
dependencies {
implementation('com.cloudcare.ft.mobile.sdk.tracker.agent:ft-sdk:1.3.10.beta01')//1.3.10 or above
}
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 been adapted to this change. 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
. 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 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. You can resolve this by depending on org.ow2.asm:asm-commons:7.2
or above 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
Currently, the 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 problem can be fixed by forcibly depending on 7.x or above versions. 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 see 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 SDK's debug function with the following configuration. Once enabled, the SDK debug logs will be output to the console LogCat
. You can filter the [FT-SDK]
characters to locate the Guance SDK logs.
Log Sample¶
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
//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 sync 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 with the following configuration. Once enabled, you can find the [FT-Plugin]
output logs in the Build
output logs. Use this to check the Plugin ASM write status.
It is recommended to turn off this configuration when releasing the Release version
SDK Internal Logs Converted 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 should 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
ordatawayUrl
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 Guance and checking the "Infrastructure" section.
Compatibility Issues with Okhttp 3.12.+¶
ft-sdk < 1.6.13, if data upload compression is enabled FTSDKConfig.setCompressIntakeRequests(true)
, 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 above to resolve this issue.
Data Loss¶
Partial Data Loss¶
- If some Session data or Log, Trace data is 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 failure:
1. Timing issue - SDK initialization is not complete. If OkHttpClient.Builder().build()
is called before SDK initialization is complete, it will lead to loading empty configurations, resulting in Resource data loss. Check the debug logs to confirm the initialization sequence 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 integrate manually here.
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, including FTTraceInterceptor
and FTResourceInterceptor
, which will use the http request body contentLength to calculate a unique id. The data of each stage of Resource
is concatenated through this id. Therefore, if the integrator also adds addInterceptor
when using Okhttp
and processes the data twice, causing its 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 disableFTRUMConfig
'senableTraceUserResource
andFTTraceConfig
'senableAutoTrace
configurations. -
ft-sdk >= 1.4.1
The SDK adapts to this issue in non-manual settings. If manual settings have been made, ensure that
Interceptor
is in a forward position.
Compatibility Issues 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 be uncollectable.
Solution:
-
ft-sdk < 1.6.13
- Without changing the Okhttp version, manually set to solve this problem.
* Upgrading Okhttp to 4.5.0 or above can also solve this problem. * ft-sdk >= 1.6.13OkHttpClient.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();
The SDK 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 at the same time. If so, the SDK initialization method should be placed after other SDKs.
Missing Field Information in Data¶
User Data Field¶
-
Confirm that the user data binding method is called correctly. In debug mode, you can track this issue through logs.
Missing Custom Parameters or Numerical Errors¶
- Confirm that
FTRUMConfig.addGlobalContext
,FTLoggerConfig.addGlobalContext
are called in the correct scenarios. These are suitable for data that does not change during an application cycle, such as application channel providers, different Flavor attributes, etc. If dynamic scenarios need to be responded to in real-time, use the manual RUM and Log interfaces. - In debug mode, check the
[FT-SDK]SyncTaskManager
logs to verify the correctness of custom field parameters.
Lag Issues When enableConsoleLog is Enabled¶
If lag occurs, it may be due to the large amount of data collected by the log. The principle of FTLoggerConfig.enableConsoleLog
is to capture android.util.Log
, Java and Kotlin println
. It is recommended to adjust the FTLoggerConfig
configuration parameters sampleRate
, logPrefix
, logLevelFilters
as needed 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 the automatic Plugin AOP setting
FTRUMConfig setEnableTraceUserResource(false)
, and customize a CustomEventListenerFactory that inheritsFTResourceEventListener.FTFactory
, and use custom method for integration. -
ft-sdk >= 1.4.1
Customize a CustomEventListenerFactory that inherits
FTResourceEventListener.FTFactory
, and customize the ASM-writteneventListenerFactory
by settingFTRUMConfig.setOkHttpEventListenerHandler
. -
ft-sdk >= 1.6.7
The SDK adapts to this issue in non-manual settings.
TraceID Missing or Not Matching Trace Propagation Header¶
When collecting complete request data, 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 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 issues between the same requests. For setup, refer to here.