トラブルシューティング¶
コンパイルのトラブルシューティング¶
コンパイル中にエラーが発生した場合は、まずコンパイル環境を確認する必要があります。
実行可能なコンパイル環境¶
✅ 実行可能環境¶
- 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 はこちらです。プラグイン設定で 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 未満
現在のプラグインバージョンは、org.ow2.asm:asm 7.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] で始まるログが存在するか確認します。
Debug モードの有効化¶
ft-sdk Debug モード¶
以下の設定で、SDK の Debug 機能を有効にできます。有効にすると、コンソールの Logcat に SDK のデバッグログが出力されます。[FT-SDK] 文字列でフィルタリングして、Guance SDK のログを特定できます。
ログ例¶
データ同期¶
// SDK 設定へのアップロード URL が正しいか確認
[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:]
リリースバージョンでは、この設定を無効にすることを推奨します。
ft-plugin Debug モード¶
以下の設定で、プラグインのデバッグログを有効にできます。有効にすると、Build 出力ログに [FT-Plugin] のログが出力されます。これにより、プラグインの ASM 書き込み状況を確認できます。
リリースバージョンでは、この設定を無効にすることを推奨します。
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 は現在セマンティクスノードに基づいてマッピングを行うため、再生時に背景色が欠落したり、ツールバーやブロックの背景がデフォルトの白で表示されたりする可能性があります。
その背景が再生表示にとって重要な場合は、コンテナに空のセマンティクスを追加して、セマンティクスノードツリーに含めることができます。
Row(
modifier = Modifier
.fillMaxWidth()
.height(56.dp)
.semantics { }
.background(Color(0xFFFF6600))
)
この方法は画面表示には影響を与えず、Session Replay がこの Compose コンテナノードを取得するのを助けるためのものです。今後の SDK では、セマンティクスのないコンテナ背景の自動収集機能を強化していく予定です。
SDK は正常に動作しているがデータがない¶
-
Datakit が正常に動作しているか確認してください。
-
SDK のアップロード URL
datakitUrlまたはdatawayUrlが正しく設定され、正しく初期化されていることを確認してください。debug モードで、ログを確認してアップロードの問題を判断してください。 -
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 の特定のセッションデータや Log、Trace 内の数件のデータが欠落している場合、まず FTRUMConfig、FTLoggerConfig、FTTraceConfig で
sampleRate < 1が設定されていないか確認してください。 - データをアップロードするデバイスのネットワーク、および Datakit をインストールしているデバイスのネットワークと負荷の問題を確認してください。
FTSdk.shutDownが正しく呼び出されていることを確認してください。このメソッドは、キャッシュされたデータを含む SDK のデータ処理オブジェクトを解放します。
Resource データの欠落¶
自動収集、ft-plugin が正しく組み込まれていない¶
Resource の自動収集には、プラグイン ASM のバイトコード書き込みが必要です。これにより、OkHttpClient の Interceptor と EventListener が自動的に設定され、FTTraceInterceptor、FTResourceInterceptor、FTResourceEventListener.FTFactory が書き込まれます。プラグインを使用しない場合は、こちらを参照してください。
カスタム WebView の自動収集が有効にならない¶
ネイティブの WebView ページの収集は正常だが、カスタム WebView ページで期待した自動収集がトリガーされない場合は、まずプラグインのログで 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 ログが出力される場合、プラグインが現在の owner をカスタム WebView として認識し、対応する呼び出しを処理したことを意味します。
このようなログが一度も出力されないが、実際に呼び出されているのはビジネス上のカスタム WebView である場合、通常はそのクラスが knownWebViewClasses に追加されているかどうかを確認する必要があります。これは自動収集の認識に影響を与えるだけでなく、プラグインがカスタム WebView の内部メソッドを通常のメソッドとして扱い、ASM 書き込みを続行するかどうかにも関係します。正しく認識されない場合、実行時に loadUrl などのメソッドがループ呼び出しされ、最終的に WebView が白くなる可能性があります。その場合、次のようなログにも注目してください。
これは、現在のクラスがまだプラグインに WebView として認識されていないことを示しています。
対処方法:
FTExt に knownWebViewClasses を追加し、実際に使用しているカスタム WebView クラスを設定に追加します。ビジネス上の WebView 基底クラスを優先的に追加することをお勧めします。継承階層が深い場合は、基底クラスと現在使用しているクラスの両方を追加できます。これにより、プラグインが WebView 呼び出しを正しく認識できるようになり、カスタム WebView の内部メソッドが重複して ASM 書き込みされるのを防ぐことができます。
FTExt {
showLog = true
verboseLog = true
knownWebViewClasses = [
'com.example.web.BaseWebView',
'com.example.web.CustomWebView'
]
}
knownWebViewClasses の役割は、ビジネス上のカスタム WebView をプラグインの既知の WebView リストに事前に追加することです。これにより、カスタム WebView の認識問題を解決できるとともに、プラグインが WebView 内部メソッドの重複書き込みをスキップし、実行時のループ呼び出しや白画面を回避できます。
OkHttpClient.build() の設定問題¶
プラグイン 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 を使用してデータを二次処理した場合¶
プラグイン 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 の内容を読み取る場合、現在の 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 をキャプチャする機能を持つサードパーティ SDK を同時に使用していないか確認してください。その場合は、SDK の初期化メソッドを他の SDK の後に配置する必要があります。
データの特定フィールド情報が欠落している¶
ユーザーデータフィールド¶
-
ユーザーデータのバインド方法が正しく呼び出されていることを確認してください。デバッグモードでは、ログでこの問題を追跡できます。
カスタムパラメータまたは値の欠落・誤り¶
- 正しいシナリオで呼び出されていることを確認してください。
FTRUMConfig.addGlobalContext、FTLoggerConfig.addGlobalContextは、アプリケーションのライフサイクル内で変更されないシナリオ（アプリケーションのチャネル、フレーバー属性など）に適しています。動的なシナリオにリアルタイムで対応する必要がある場合は、手動で RUM および Log インターフェースを呼び出す必要があります。 - デバッグモードで、
[FT-SDK]SyncTaskManagerログを確認します。このログで、カスタムフィールドパラメータの正確性を検証できます。
ログで enableConsoleLog を有効にすると応答が遅くなる¶
応答が遅くなる場合、原因はログ収集のデータ量が多すぎる可能性があります。FTLoggerConfig.enableConsoleLog の原理は、コンパイルされた android.util.Log、Java と Kotlin の println をキャプチャすることです。必要に応じて FTLoggerConfig 設定 の sampleRate、logPrefix、logLevelFilters パラメータを調整して、この問題を解消または軽減することをお勧めします。
OkHttp EventListener が SDK 統合後に機能しない¶
プラグイン AOP ASM が挿入されると、元のプロジェクトコードに基づいて、OkHttpClient.Builder() に eventListenerFactory が追加されます。これにより、元の eventListener または eventListenerFactory が上書きされます。
対処方法:
ft-sdk < 1.4.1
プラグイン 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 からそれぞれ情報を取得する必要があります。これらの2つのデータを効果的に関連付けるために、SDK は一意の ID を使用して同じネットワークリクエストを連携する必要があります。しかし、1.6.10 より前のバージョンでは、この ID は同じリクエスト内で同じであったため、高並行シナリオでデータの混乱や欠落が発生する可能性がありました。1.6.10 以降では、FTSDKConfig.setEnableOkhttpRequestTag(true) を呼び出すか、Request に明示的に ResourceID を追加することで、各リクエストに一意の識別子を割り当て、同じリクエスト間の干渉を防ぐことができます。設定方法はこちらを参照してください。