故障排查¶
编译故障排查¶
编译过程发生错误，需要首先检查编译环境。
可运行编译环境¶
✅ 可运行环境¶
- AGP
com.android.tools.build:gradle版本3.5.0以上 - gradle 版本
5.4.0以上 - java 版本
8.0以上 - Android minSdkVersion 21
注意：随着 Android Studio 版本更新，这部分版本兼容度也会发生变化，如果您遇到编译环境符合以上条件，但仍然遇到编译出错的问题，请联系我们的开发人员。
⚠️ 可兼容运行环境¶
- AGP
com.android.tools.build:gradle版本3.0.1以上 - Gradle 版本
4.8.1以上 - Java 版本
8.0以上 - Android minSdkVersion 21
此环境
ft-plugin无法使用，数据自动捕获的部分需要手动接入完成。更多手动接入相关，可参考手动接入。
SDK 无法解析导入¶
发生以上错误是因为 maven 仓库没有正确设置，请参考这里的配置。
编译错误¶
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 兼容性问题导致，这里 issue 说明了这个问题，可以提升 AGP 3.1.0 以上版本来解决这个问题，或者使用较新版本 SDK, 在app/build.gradle中升级版本即可。
dependencies {
implementation('com.cloudcare.ft.mobile.sdk.tracker.agent:ft-sdk:1.3.10.beta01')//1.3.10 以上均可以
}
API 'android.registerTransform' is obsolete¶
AGP 7.0 中 Transform 已标记为 Deprecated，并在 AGP 8.0 中已弃用。 ft-plugin:1.2.0 已经完成适配，请升级相应版本，修复这个错误。 具体说明请见集成配置
AndroidComponentsExtension ClassNotFoundException¶
AndroidComponentsExtension 是 AGP 7.4.2 支持的方法，低于这个版本的编译环境，就会产生这个错误，可以使用 ft-plugin-legacy 版本，修复这个错误。具体说明请见集成配置
java.lang.IllegalArgumentException:¶
- Invalid opcode 169
如果在使用 ft_plugin_legacy 发生了这个错误，这个是 asm-commons:7.0 版本的 bug，原始 issue 在这里, 通过在 plugin 配置中依赖 org.ow2.asm:asm-commons:7.2 以上的版本，解决这个问题。通过 ./gradlew buildEnvironment 可以确认真实 asm-commons 使用版本。
buildscript {
dependencies {
classpath 'com.cloudcare.ft.mobile.sdk.tracker.plugin:ft-plugin-legacy:[version]'
// 添加依赖
classpath 'org.ow2.asm:asm-commons:7.2'
}
}
- org.ow2.asm:asm 版本低于 7.0
目前 plugin 版本仅支持使用 org.ow2.asm:asm7.x 以上版本的 build 环境，通过 ./gradlew buildEnvironment 可以查询 build 环境，来确认。可通过强制依赖 7.x 以上版本修复，建议使用 7.2 以上版本。
buildscript {
dependencies {
classpath 'com.cloudcare.ft.mobile.sdk.tracker.plugin:ft-plugin-legacy:[version]'
// 添加依赖
classpath 'org.ow2.asm:asm:7.2'
classpath 'org.ow2.asm:asm-commons:7.2'
}
}
SDK 初始化异常校验¶
查看 Logcat 确认是否存在日志 Level 为 Error ，Tag 为 [FT-SDK] 前缀的日志
开启 Debug 调试¶
ft-sdk Debug 模式¶
您可以通过以下配置，开启 SDK 的 debug 功能，开启之后，控制台 LogCat 会输出 SDK 调试日志，您可以过滤 [FT-SDK] 字符，定位到观测云 SDK 日志。
日志示例¶
数据同步¶
//检查上传地址是否正确进入 SDK 配置
[FT-SDK]FTHttpConfigManager com.demo D serverUrl ==>
Datakit Url:http://10.0.0.1:9529
//以下是连接错误日志
[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,检查本地网络连接是否正常]
//以下是正常同步日志
[FT-SDK]SyncTaskManager com.demo D Sync Success-[code:200,response:]
建议 Release 版本发布时，关闭这个配置
ft-plugin Debug 模式¶
您可以通过以下配置，开启 Plugin 的 debug 日志，开启之后，你可以在 Build 输出日志中，找到 [FT-Plugin]的输出日志。通过这个来查看 Plugin ASM 写入情况。
建议 Release 版本发布时，关闭这个配置
SDK 内部日志转化为缓存文件¶
// >= 1.4.6
// 默认路径：/data/data/{package_name}/files/LogInner.log
LogUtils.registerInnerLogCacheToFile()
// >= 1.4.5+
val cacheFile = File(filesDir, "LogCache.log")
LogUtils.registerInnerLogCacheToFile(cacheFile)
为了内部日志的完整性，需要在 SDK 初始化之前设置该配置
Session Replay Compose 回放中纯容器背景色缺失¶
当使用 Jetpack Compose Session Replay 时，如果页面中存在仅用于布局和背景绘制的 Row、Column、Box 等容器，例如只设置了 Modifier.background(...)，但没有文本、点击、语义或其他可访问性信息，该容器可能不会出现在 Compose 语义节点树中。Session Replay 当前基于语义节点进行映射，因此回放中可能出现背景色缺失、Toolbar 或区块背景显示为默认白色的情况。
如果该背景对回放展示很重要，可以为容器补充空语义标记，使其进入语义节点树：
Row(
modifier = Modifier
.fillMaxWidth()
.height(56.dp)
.semantics { }
.background(Color(0xFFFF6600))
)
该方式不会改变界面展示效果，仅用于帮助 Session Replay 捕获该 Compose 容器节点。后续 SDK 会持续增强对无语义容器背景的自动采集能力。
SDK 正常运行但是没有数据¶
-
排查 Datakit 是否正常运行
-
确认 SDK 上传地址
datakitUrl或datawayUrl配置正确，并正确初始化。debug 模式下，查看日志来判断上传问题。 -
datakit 是否往对应工作空间上传数据，是否处于离线状态。这个可以通过登录观测云，查看「基础设施」来确认这个问题。
OKhttp 3.12.+ 的兼容性问题¶
ft-sdk < 1.6.13 版本中，若开启数据压缩 FTSDKConfig.setCompressIntakeRequests(true)，SDK 数据采集正常，但在数据同步阶段不会产生错误提示，亦不会输出 HTTP 状态码日志。
处理方式： 使用 ft-sdk >= 1.6.13 的版本或使用 okhttp 4.5.0 以上的版本都能解决这个问题
数据丢失¶
丢失部份数据¶
- 如果丢失 RUM 某一个 Session 数据或 Log，Trace 中的几条数据时，首先需要排除是否在 FTRUMConfig, FTLoggerConfig, FTTraceConfig 设置了
sampleRate < 1 - 排查上传数据设备的网络，以及安装 datakit 设备的网络与负载问题
- 确认正确调用
FTSdk.shutDown，这个方法会释放 SDK 数据处理对象，包括缓存的数据。
Resource 数据丢失¶
自动采集，未正确接入 ft-plugin¶
Resource 自动采集需要借助 Plugin ASM 字节码写入，自动对 OkHttpClient Interceptor 和 EventListener 进行设置，写入 FTTraceInterceptor, FTResourceInterceptor, FTResourceEventListener.FTFactory。如果不使用 Plugin，请参考这里
自定义 WebView 自动采集未生效¶
如果原生 WebView 页面采集正常，但自定义 WebView 页面没有触发预期的自动采集，建议优先通过 Plugin 日志定位是否属于 WebView 识别问题。
定位方式：
- 先参考接入配置，在
FTExt中开启日志：
- 重新编译后，在
Build日志中搜索[FT-Plugin]和WEBVIEW相关输出，重点关注是否出现类似以下日志：
[FT-Plugin]:TARGET_CUSTOM_WEBVIEW_METHOD-> owner:com/example/CustomWebView, class:com/example/WebViewActivity$2, super:java/lang/Object, method:loadUrl(Ljava/lang/String;)V | onItemSelected(Landroid/widget/AdapterView;Landroid/view/View;IJ)V
如果出现这类 TARGET_CUSTOM_WEBVIEW_METHOD 日志，说明 Plugin 已经把当前 owner 识别为自定义 WebView，并对对应调用进行了处理。
如果一直没有命中这类日志，但实际调用的又是业务自定义 WebView，通常就需要检查该类是否加入了 knownWebViewClasses。这不只是影响自动采集识别，也关系到 Plugin 是否会把自定义 WebView 内部方法当作普通方法继续做 ASM 写入；如果没有正确识别，运行时可能出现 loadUrl 等方法循环调用，最终表现为 WebView 白屏。排查时也可以继续关注类似下面的日志：
这通常说明当前类还没有被 Plugin 识别为 WebView。
处理方式：
在 FTExt 中添加 knownWebViewClasses，把实际使用的自定义 WebView 类加入配置。建议优先添加业务里的 WebView 基类；如果继承层级较深，可以同时添加基类和当前使用类。这样既能让 Plugin 正确识别 WebView 调用，也能避免自定义 WebView 内部方法被重复 ASM 写入。
FTExt {
showLog = true
verboseLog = true
knownWebViewClasses = [
'com.example.web.BaseWebView',
'com.example.web.CustomWebView'
]
}
knownWebViewClasses 的作用是把业务自定义 WebView 提前加入 Plugin 的已知 WebView 列表。这样既能解决自定义 WebView 的识别问题，也能配合 Plugin 跳过 WebView 内部方法的重复写入，避免运行时循环调用和白屏。
OkHttpClient.build() 设置问题¶
Plugin ASM 会在应用调用 OkHttpClient.Builder().build() 时自动注入网络采集功能。以下两种情况可能导致网络采集失败：
- 时序问题 - SDK 初始化未完成。如果在 SDK 初始化完成前就调用了
OkHttpClient.Builder().build()，会导致加载空配置，丢失 Resource 相关数据，可通过检查调试日志确认初始化顺序是否正确。 - 创建方式问题。 未使用标准的
OkHttpClient.Builder().build()方法创建 OkHttpClient 对象，例如直接实例化 OkHttpClient 或使用其他构建方式。
//SDK 初始化日志
[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() 调用时，打印的日志
//（需要在 SDK 初始化之后被调用）
[FT-SDK]AutoTrack com.ft D trackOkHttpBuilder
如果无法调整初始化调用次序，可以选择手动方式接入
使用 Interceptor 或 EventListener 对数据进行了二次处理¶
Plugin ASM插入后，会在原工程代码基础上，在 OkHttpClient.Builder() 加入 addInterceptor，分别加入 FTTraceInterceptor 和 FTResourceInterceptor, 其中会使用 http 请求中 body contentLength 参与唯一 id 计算，Resource 数据各个阶段数据通过这个 id 进行上下文串联，所以如果集成方在使用 Okhttp 时，也加入 addInterceptor 并对数据进行二次处理使其发生大小改变，从而导致 id 各阶段计算不一致，导致数据丢失。
处理方式：
ft-sdk < 1.4.1
通过 自定义 addInterceptor 位置顺序，让 SDK 方法第一时间去计算 id，可以解决这个问题。为了避免重复设置，自定义方式需要关闭 FTRUMConfig的enableTraceUserResource ，FTTraceConfig的 enableAutoTrace 配置。
ft-sdk >= 1.4.1
SDK 非手动设置场景下，自行适配兼容这个问题，如果已经进行手动设置，需要确保 Interceptor 处于靠前的位置。
OKhttp 3.12.+ 的兼容性问题¶
ft-sdk < 1.6.13 如果使用的 Interceptor 会读取 response body 内容进行 read，那么就可能会导致无法采集到当前 Resource 数据。
处理方式：
ft-sdk < 1.6.13
-
在不改变 Okhttp 版本的前提下，进行手动设置解决这个问题
OkHttpClient.Builder builder = new OkHttpClient.Builder() .addInterceptor(new CustomReadReponseInterceptor())//读取响应 body .addInterceptor(new FTTraceInterceptor()) .addInterceptor(new FTResourceInterceptor()) .addInterceptor(new CustomRequestBodyFixInterceptor())//拥有加密或修改body .eventListenerFactory(new FTResourceEventListener.FTFactory()); OkHttpClient client = builder.build(); -
升级及 Okhttp 至 4.5.0 以上的版本也可以解决这个问题。
ft-sdk >= 1.6.13
SDK 非手动设置场景下，自行适配兼容这个问题。
Error 数据丢失 Crash 类型数据¶
- 确认是否同时使用了其他第三方具有捕获 Crash 功能的 SDK，如果是，需要将 SDK 初始化方法放置到其他 SDK 后面。
数据丢失某个字段信息¶
用户数据字段¶
-
确认正确调用用户数据绑定方法。debug 模式下，可以通过 log 来追踪这个问题。
丢失自定义参数或数值发生错误¶
- 确认在正确的场景下调用，
FTRUMConfig.addGlobalContext，FTLoggerConfig.addGlobalContext适合一个应用周期内不变更的场景，例如应用渠道商、应用不同 Flavor 属性等数据，如果需要根据动态场景，实时响应，需要使用手动调用 RUM 和 Log 接口。 - debug 模式下，查看
[FT-SDK]SyncTaskManager日志，可以通过这个日志，来验证自定义字段参数的正确性
日志开启 enableConsoleLog 发生卡顿问题¶
如果发生卡顿，有可能原因是日志采集的数据过大。FTLoggerConfig.enableConsoleLog原理是抓取编译 android.util.Log，Java 与 Kotlinprintln，建议按需调整 FTLoggerConfig 配置 下 sampleRate、logPrefix、logLevelFilters 参数来消除或缓解这个问题。
Okhttp EventListener 集成 SDK 后失效¶
Plugin AOP ASM 插入之后，会在原工程代码基础上，会在 OkHttpClient.Builder() 加入 eventListenerFactory ，这会覆盖原来的 eventListener 或 eventListenerFactory。
处理方式：
ft-sdk < 1.4.1
关闭自动 Plugin AOP 自动设置 FTRUMConfig setEnableTraceUserResource(false)，同时自定义一个 CustomEventListenerFactory 并继承 FTResourceEventListener.FTFactory，使用自定义方式进行接入。
ft-sdk >= 1.4.1
自定义一个 CustomEventListenerFactory 并继承 FTResourceEventListener.FTFactory，通过设置 FTRUMConfig.setOkHttpEventListenerHandler 对 ASM 写入的 eventListenerFactory 进行自定义。
ft-sdk >= 1.6.7
SDK 非手动设置场景下，自行适配兼容这个问题。
TraceID 丢失或与 Trace Propagation Header 不对应¶
在进行完整的请求数据采集时，通常需要从 Interceptor 和 EventListener 中分别获取信息。为了将这两部分数据进行有效关联，SDK 需要借助一个唯一的 ID 来串联同一个网络请求。然而，在 1.6.10 版本之前，该 ID 在相同的请求中是相同的，导致在高并发场景下可能出现数据错乱或丢失的问题。自 1.6.10 版本起，可以通过调用 FTSDKConfig.setEnableOkhttpRequestTag(true) 或者在 Request 上显式添加 ResourceID，来为每一个请求区分唯一标识，从而避免相同请求之间的干扰问题。设置方式请参考这里。