故障排查¶

本文用于提供 HarmonyOS SDK 初始化和上报异常时的基础排查入口。

初始化与日志诊断¶

初始化失败¶

如果 SDK 初始化失败，建议优先检查：

1. datakitUrl、datawayUrl、clientToken 是否按部署方式正确配置
2. ft_sdk.har、ft_native.har 是否已正确放入 libs 目录，并在 oh-package.json5 中分别声明为 @guancecloud/ft_sdk、@guancecloud/ft_native 后执行 ohpm install
3. 应用是否已按文档完成 oh-package.json5 依赖声明
4. SDK 初始化是否发生在应用启动阶段

SDK 初始化异常校验¶

查看 hilog 确认是否存在 Tag 为 [FT-SDK] 前缀的日志。SDK 初始化、配置安装、数据同步等内部日志会通过该前缀输出，可用于定位初始化失败、配置未生效或网络同步异常等问题。

开启 Debug 调试¶

可通过以下配置开启 SDK Debug 模式。setDebug(true) 是 SDK 内部日志的总开关；开启后，控制台 hilog 会输出 SDK 调试日志，可过滤 [FT-SDK] 字符定位 SDK 内部日志。setSdkLogLevel(...) 用于控制输出阈值：

import { FTSDK, FTSDKConfig, SDKLogLevel } from '@guancecloud/ft_sdk/Index';

const sdkConfig = FTSDKConfig.builder(datawayUrl, clientToken)
  .setDebug(true)
  .setSdkLogLevel(SDKLogLevel.D);

FTSDK.install(sdkConfig, this.context);

建议 Release 版本发布时，关闭这个配置。

SDK 内部日志写入本地文件¶

排查线上或偶发问题时，可将 SDK 内部诊断日志写入应用沙箱本地文件，便于后续导出和分析。必须同时开启 setDebug(true)；可通过 setSdkLogLevel(...) 控制记录的日志级别。

import { FTSDK, FTSDKConfig, SDKLogLevel } from '@guancecloud/ft_sdk/Index';

const sdkConfig = FTSDKConfig.builder(datawayUrl, clientToken)
  .setDebug(true)
  .setSdkLogLevel(SDKLogLevel.D)
  .setEnableInnerLogFile(true, {
    singleFileMaxSize: 5 * 1024 * 1024,
    totalFileMaxSize: 50 * 1024 * 1024,
    flushBatchSize: 20,
    flushIntervalMs: 200
  });

FTSDK.install(sdkConfig, this.context);

FTInnerLogFileConfig¶

setEnableInnerLogFile(true, config) 可传入 FTInnerLogFileConfig 调整内部日志文件写入策略：

日志文件默认写入应用沙箱 filesDir/ft_sdk_logs/ 目录：

• 当前日志文件：ft_inner_current.log
• 历史轮转文件：ft_inner_*.log

当日志总大小超过配置阈值时，SDK 会从最早的历史轮转文件开始清理，当前日志文件会保留。内部日志文件只记录 SDK 自身的诊断日志，不包含 FTLogger 写入的业务 Log；

为了内部日志的完整性，需要在 FTSDK.install(...) 之前设置该配置，并同时开启 setDebug(true)。超出配置范围的数值会被 SDK 截断到允许范围并取整。

数据上报与缓存¶

没有数据上报¶

建议按以下顺序排查：

1. 确认 前置条件 已完成，尤其是 DataKit 和 RUM 采集器配置
2. 确认应用设备可以访问 datakitUrl 或 datawayUrl
3. 如果配置了 setProxy(...)、setProxyAuthenticator(...) 或 setDns(...)，确认代理、认证信息、DNS 服务器或 DoH 地址正确；这些配置只作用于 SDK 数据上传请求
4. 参考 开启 Debug 调试，查看初始化与上报日志
5. 确认 RUM 已执行 installRUMConfig，并至少开启了一个需要验证的采集项
6. SDK 默认对上传数据启用 deflate 压缩；如果怀疑服务端或网络链路不兼容，可临时设置 setCompressIntakeRequests(false) 进行对照验证

缓存与同步¶

• SDK 自动同步采用 10 秒聚合窗口，采集后未立即发起上传属于正常行为
• 若通过 FTSDKConfig.setAutoSync(false) 或 FTSDK.setAutoSync(false) 关闭了自动同步，需要手动调用 SDK 初始化 中的 FTSDK.flushSyncData()
• SDK 初始化后可通过 FTSDK.setAutoSync(true) 重新开启自动同步
• FTSDK.flushSyncData() 不等待 10 秒聚合窗口，会在尽量刷入待处理的 RUM 与 Log worker 队列后立即调度上传
• 若本地缓存异常，可使用 FTSDK.clearAllData() 清理未上报数据后重新验证

网络请求自动采集¶

HttpInterceptorChain 不生效¶

如果使用 @kit.NetworkKit 的 HttpInterceptorChain 自动采集未生效，建议优先检查：

1. 当前设备或编译目标是否为 HarmonyOS API 22 及以上；低于 API 22 时不支持该能力
2. 项目是否已安装 ft_sdk.har 和 ft_sdk_ext.har，并在 oh-package.json5 中声明为 @guancecloud/ft_sdk 和 @guancecloud/ft_sdk_ext 后完成 ohpm install
3. 是否已开启 setEnableTraceUserResource(true)；如需自动注入 Trace Headers，还需开启 Trace 配置中的 setEnableAutoTrace(true)
4. 已知在 @kit.NetworkKit 的并发请求场景下，即使为每个请求分别创建独立的 HttpRequest 和 HttpInterceptorChain，仍可能触发异常：{"code":2300003,"message":"Invalid URL format or missing URL"}
5. 如果遇到上述错误，建议优先降级为串行验证；并发场景下可改用 RCP 或 Axios 兼容模式，或暂时避免在高并发链路中使用 HttpInterceptorChain

Resource 无法采集¶

如果 HTTP 请求已经创建并挂载自动采集拦截器，但 SDK 初始化和 RUM 配置在后执行，可能出现请求成功但 Resource 数据没有生成。

建议优先检查：

1. 是否先创建了 HttpRequest、调用了 createFTHttpInterceptorChain() 或 applyFTHttpTrack()，后面才执行 FTSDK.installRUMConfig()
2. 是否已在 RUM 配置中开启 setEnableTraceUserResource(true)

原因说明：

• HttpInterceptorChain 创建时，会立即读取当前的 RUM 配置来决定是否启用 Resource 自动采集
• 如果这一步发生在 FTSDK.installRUMConfig() 之前，SDK 读取到的默认值为 false
• 后续即使再完成 SDK 初始化，已经创建好的自动采集拦截器实例也不会自动刷新为开启状态，因此不会生成 Resource

建议处理方式：

1. 先完成 FTSDK.install()、FTSDK.installRUMConfig()，再创建 HttpRequest 并挂载 HttpInterceptorChain
2. 如果请求对象或拦截器链已提前创建，需要在 SDK 初始化完成后重新创建并重新挂载
3. 如果确实需要在 SDK 初始化前先创建自动采集对象，可在创建时显式传入开关，避免依赖默认配置值

可选写法示例：

applyFTAxiosTrack(client, {
  enableTraceInterceptor: true,
  enableResourceInterceptor: true
});

sdk.init();

注意：

• 显式传入 enableTraceInterceptor、enableResourceInterceptor 只能保证自动采集机制本身处于启用状态
• 在 SDK 初始化完成之前已经发出的请求，仍可能因为 RUM 上下文尚未完成初始化而无法生成或补齐 Resource 数据
• 因此更推荐的方式仍然是先完成 SDK 初始化，再创建并使用自动采集对象

类似处理方式同样适用于 RCP 与 HttpInterceptorChain：

• Axios：applyFTAxiosTrack(client, { enableTraceInterceptor: true, enableResourceInterceptor: true })
• RCP：createFTRCPInterceptors(true, true) 或 createFTRCPTrackConfig({ enableTraceInterceptor: true, enableResourceInterceptor: true })
• HTTP：createFTHttpInterceptorChain({ enableTraceInterceptor: true, enableResourceInterceptor: true }) 或 applyFTHttpTrack(request, { enableTraceInterceptor: true, enableResourceInterceptor: true })

相关文档¶

• 安装与入口页：查看 应用接入
• 初始化参数：查看 SDK 初始化
• RUM 网络采集：查看 RUM 配置
• Trace 链路追踪：查看 Trace 配置