トラブルシューティング¶
コンパイルのトラブルシューティング¶
コンパイル処理でエラーが発生した場合は、まずコンパイル環境を確認してください。
実行可能なコンパイル環境¶
✅ 実行可能な環境¶
- 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 バージョンのバグです。元の 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 以上のバージョンを使用するビルド環境のみをサポートしています。./gradlew buildEnvironment でビルド環境を確認できます。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] プレフィックスのログが存在するか確認します。
デバッグを有効にする¶
ft-sdk のデバッグモード¶
以下の設定で SDK のデバッグ機能を有効にできます。有効にすると、コンソールの Logcat に SDK デバッグログが出力されます。[FT-SDK] 文字列でフィルタして、Guance 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 のデバッグモード¶
以下の設定で Plugin のデバッグログを有効にできます。有効にすると、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が正しく設定されていること、および正しく初期化されていることを確認します。デバッグモードでは、ログを確認してアップロードの問題を判断します。 -
datakit が対応するワークスペースにデータをアップロードしているか、オフライン状態でないかを確認します。これは Guance にログインし、「インフラストラクチャ」を確認することで判断できます。
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に関連する出力を検索し、次のようなログが出現するかどうかに注目してください:
この種の 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() を呼び出したときにネットワーク収集機能を自動注入します。次の 2 つのケースでは、ネットワーク収集が失敗する可能性があります:
- タイミングの問題 - 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 の非手動設定シナリオでは、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 の非手動設定シナリオでは、SDK がこの問題を独自に吸収して互換性を確保します。
Error データおよび Crash タイプのデータの欠損¶
- Crash をキャプチャする機能を持つ他のサードパーティ SDK を同時に使用しているか確認してください。使用している場合は、SDK の初期化メソッドを他の SDK の後に配置する必要があります。
特定のフィールド情報が欠損する¶
ユーザーデータフィールド¶
-
ユーザーデータのバインドメソッドを正しく呼び出していることを確認してください(ユーザーデータのバインド)。デバッグモードでは、ログでこの問題を追跡できます。
カスタムパラメータの欠損または値の誤り¶
- 正しいシナリオで呼び出していることを確認してください。
FTRUMConfig.addGlobalContext、FTLoggerConfig.addGlobalContextは、アプリのライフサイクル内で変更されないシナリオ、たとえばアプリの配信チャネル、アプリの異なる Flavor 属性などのデータに適しています。動的なシナリオに応じてリアルタイムに反映する必要がある場合は、RUM と Log インターフェースを手動で呼び出す必要があります。 - デバッグモードでは、
[FT-SDK]SyncTaskManagerログを確認できます。このログを通じて、カスタムフィールドパラメータの正確性を検証できます。
ログで enableConsoleLog を有効にするとカクつきが発生する問題¶
カクつきが発生する場合、ログ収集のデータ量が大きすぎることが原因である可能性があります。FTLoggerConfig.enableConsoleLog の原理は、コンパイルされた android.util.Log、Java と Kotlin の println をフックすることです。必要に応じて 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 の非手動設定シナリオでは、SDK がこの問題を独自に吸収して互換性を確保します。
TraceID が失われる、または Trace Propagation Header と一致しない¶
完全なリクエストデータを収集する場合、通常は Interceptor と EventListener からそれぞれ情報を取得する必要があります。これら 2 つの部分のデータを有効に関連付けるために、SDK は一意の ID を利用して同じネットワークリクエストを連結する必要があります。しかし、1.6.10 バージョン以前では、この ID は同じリクエスト内で同一であったため、高い並行性が求められるシナリオでデータの不整合や欠損が発生する可能性がありました。1.6.10 バージョン以降では、FTSDKConfig.setEnableOkhttpRequestTag(true) を呼び出すか、Request に ResourceID を明示的に追加することで、各リクエストに一意の識別子を設定し、同じリクエスト間の干渉問題を回避できます。設定方法についてはこちらを参照してください。

