トラブルシューティング¶
本記事は、HarmonyOS SDK の初期化時および送信異常時の基本的なトラブルシューティングの入口を提供するものです。
初期化とログ診断¶
初期化の失敗¶
SDK の初期化に失敗した場合は、まず以下を確認することを推奨します。
datakitUrl、datawayUrl、clientTokenがデプロイ方式に応じて正しく設定されているかft_sdk.har、ft_native.harが正しくlibsディレクトリに配置され、oh-package.json5でそれぞれ@guancecloud/ft_sdk、@guancecloud/ft_nativeとして宣言した後にohpm installを実行しているか- アプリケーションがドキュメントに従って
oh-package.json5の依存関係を宣言済みか - SDK の初期化がアプリケーション起動段階で行われているか
SDK 初期化異常のチェック¶
hilog を確認し、Tag が [FT-SDK] プレフィックスのログが存在するか確認します。SDK の初期化、設定のインストール、データ同期などの内部ログは、このプレフィックスで出力されます。初期化失敗、設定が反映されない、ネットワーク同期の異常などの問題を特定するために使用できます。
デバッグを有効化¶
以下の設定で SDK のデバッグモードを有効にできます。setDebug(true) は SDK 内部ログのマスタースイッチです。有効にすると、コンソールの hilog に SDK デバッグログが出力され、[FT-SDK] 文字列でフィルタして SDK 内部ログを特定できます。setSdkLogLevel(...) は出力しきい値の制御に使用します。
| ログレベル | 出力内容 |
|---|---|
SDKLogLevel.V、SDKLogLevel.D |
現在のすべての SDK 診断ログを出力:D、I、W、E |
SDKLogLevel.I |
I、W、E を出力 |
SDKLogLevel.W |
W、E を出力 |
SDKLogLevel.E |
E のみを出力 |
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);
リリース版を公開する際は、この設定を無効にすることを推奨します。
カスタムログを HiLog に出力¶
デバッグ時に FTLogger.logBackground(...) の内容も確認したい場合は、setPrintCustomLogToConsole(true) を有効にできます。この機能は Hvigor プラグインを必要とせず、setEnableConsoleLog(...) による自動収集とは独立しています。
import {
FTSDK, FTSDKConfig, FTLoggerConfig, FTLogger, SDKLogLevel, Status
} from '@guancecloud/ft_sdk/Index';
const sdkConfig = FTSDKConfig.builder('YOUR_DATAKIT_URL')
.setDebug(true)
.setSdkLogLevel(SDKLogLevel.D);
FTSDK.install(sdkConfig, this.context);
FTSDK.installLogConfig(new FTLoggerConfig()
.setEnableCustomLog(true)
.setPrintCustomLogToConsole(true));
FTLogger.logBackground('登录成功', Status.INFO);
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 を渡すことで、内部ログファイルの書き込みポリシーを調整できます。
| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
singleFileMaxSize |
number |
いいえ | 単一ログファイルのサイズ。デフォルトは 5MB、範囲は 1MB ~ 10MB です |
totalFileMaxSize |
number |
いいえ | ログファイル合計サイズのしきい値。デフォルトは 50MB、範囲は 10MB ~ 100MB です。しきい値を超えると、最も古いローテーション済みファイルから削除し、現在のファイルは保持されます |
flushBatchSize |
number |
いいえ | バッチ書き込み件数。デフォルトは 20、範囲は 1 ~ 100 です |
flushIntervalMs |
number |
いいえ | フラッシュ間隔。デフォルトは 200ms、範囲は 50ms ~ 5000ms です |
ログファイルはデフォルトでアプリケーションサンドボックスの filesDir/ft_sdk_logs/ ディレクトリに書き込まれます。
- 現在のログファイル:
ft_inner_current.log - 過去のローテーションファイル:
ft_inner_*.log
ログの合計サイズが設定されたしきい値を超えると、SDK は最も古いローテーション済みファイルから削除し、現在のログファイルは保持します。内部ログファイルには SDK 自体の診断ログのみが記録され、FTLogger が書き込む業務 Log は含まれません。
内部ログの完全性を保つため、この設定は
FTSDK.install(...)の前に設定し、同時にsetDebug(true)を有効にする必要があります。設定範囲を超える値は SDK によって許容範囲にクランプされ、整数に丸められます。
データ送信とキャッシュ¶
データが送信されない¶
以下の順序で確認することを推奨します。
- 前提条件 が満たされていること、特に DataKit と RUM コレクターの設定を確認します
- アプリケーションを実行するデバイスが
datakitUrlまたはdatawayUrlにアクセスできることを確認します setProxy(...)、setProxyAuthenticator(...)、またはsetDns(...)を設定した場合は、プロキシ、認証情報、DNS サーバー、または DoH アドレスが正しいことを確認します。これらの設定は SDK のデータアップロードリクエストにのみ適用されます- デバッグを有効化 を参照し、初期化と送信のログを確認します
- RUM で
installRUMConfigが実行され、検証対象の収集項目が少なくとも 1 つ有効になっていることを確認します - SDK はデフォルトでアップロードデータに対して
deflate圧縮を有効にします。サーバー側またはネットワーク経路との互換性に問題がある疑いがある場合は、一時的にsetCompressIntakeRequests(false)を設定して比較検証できます 0.1.18以降のバージョンではデフォルトでメインプロセスのみが初期化されます。サブプロセスでインストールを実行する場合は、インストール前にsetOnlySupportMainProcess(false)を呼び出す必要があるか確認します- 実際のサンプリング値とリモートオーバーライドを確認します。新しいパーセント API の
1は 1%、旧setSamplingRate(1)は 100% です。詳細は RUM 初期化設定 を参照してください
キャッシュと同期¶
- SDK の自動同期では 10 秒の集約ウィンドウが採用されているため、収集後すぐにアップロードが開始されなくても正常な動作です
FTSDKConfig.setAutoSync(false)またはFTSDK.setAutoSync(false)で自動同期を無効にした場合、SDK 初期化 のFTSDK.flushSyncData()を手動で呼び出す必要があります- SDK 初期化後は
FTSDK.setAutoSync(true)で自動同期を再度有効にできます FTSDK.flushSyncData()は 10 秒の集約ウィンドウを待たず、未処理の RUM および Log ワーカーキューを可能な限りフラッシュした後、即座にアップロードをスケジュールします- ローカルキャッシュに異常がある場合は、
FTSDK.clearAllData()を使用して未送信データをクリアした後、再検証できます - FileStore を使用する場合は、まずシャドウモードかどうかを確認します。シャドウモードでは引き続き SQLite が読み取りとアップロードを担当し、同時に書き込みを FileStore にミラーリングします。これは移行前の検証に使用します。詳細な設定は SDK 初期化 を参照してください
- 旧 SQLite キャッシュの初回移行では、明示的に
setNeedTransformOldCache(true)を呼び出す必要があります。容量不足または旧キャッシュが破損している場合、ソースキャッシュは保持されます。条件を修正して再起動すると、処理を継続できます
RUM 自動収集¶
プラグインはインストール済みだが自動収集が有効にならない¶
ft_sdk 0.1.18 以降のバージョンを使用する場合、プラグインはソースコードが所属するモジュールの oh-package.json5 に基づいて SDK 依存関係を判断します。自動収集が必要な各 HAP、HAR、または HSP は、それぞれの dependencies でコアパッケージを宣言する必要があります。Replay の場合は Replay パッケージも宣言する必要があります。プロジェクトルート、他のモジュール、または devDependencies にのみ配置しても、現在のモジュールのインストルメンテーションは有効になりません。
HAP の hvigorfile.ts に ftConsoleLogPlugin() が登録されていることを確認し、クリーンビルドを 1 回実行します。実行時には、ログ、Action、または Replay の設定をそれぞれ有効にする必要があります。sdk_pkg_info.track は、登録済みのプラグインバージョンの確認に使用できます。オプショナルチェーン形式の console?.info(...)、hilog.info?.(...) は自動ログ収集の対象外です。
DevEco Studio の Build 出力または .hvigor/outputs/build-logs/build.log で [GuanceBuild] を検索すると、機能名、ソースファイル、行・列位置、スキップ理由を確認できます。これらのビルド時のヒントは FTSDKConfig.setDebug(true) に依存しません。
コールドスタート Action が表示されない¶
- プラグインが有効であり、エントリでできるだけ早く SDK と RUM のインストールを完了し、
setEnableTraceUserAction(true)を有効にしていることを確認します。 - 自動初回フレーム収集には API 22+ が必要です。最初の UI フレームが観測されない場合、完全なコールドスタート Action は送信されません。
- バックグラウンド起点の起動では、同一プロセスで最初に UI が表示されるまで待機します。
0.1.18ではapp_launch_type=backgroundが保持され、所要時間にはバックグラウンドでの待機が含まれます。UI が一度も表示されないプロセスでは、この Action は生成されません。 - Session サンプリングと
setActionTrackingHandler(...)が起動イベントをフィルタしていないか確認します。カスタム Handler はgetSourceType()で起動元を区別する必要があり、起動イベントのgetSource()はnullです。 - アプリケーションの初期化ステージが不完全な場合、HAP の
module.json5でAbilityStageがsrcEntryとして設定されているか確認します。設定されていない場合は、概算のステージ時間しか取得できません。
ページまたは Session の帰属が想定と異なる¶
まず、イベント発生時のフォアグラウンド/バックグラウンド状態を確認します。新しい SDK では、起動イベントに ApplicationLaunch を使用し、バックグラウンドイベントまたはページのないイベントに BackgroundView、RootView を使用します。これらは SDK が管理する View です。Session は、ユーザー操作がない状態が 15 分を超えた場合、または継続時間が 4 時間を超えた場合に更新されます。
自動 View が有効な場合は、同じページに対して手動で startView(...) を呼び出さないでください。0.1.18 以降、同名 View の手動開始を繰り返した場合も新しいレコードが作成されます。使用方法は View の手動収集 を参照してください。
UI ジャンクが収集されない¶
RUM 設定で setEnableTrackAppUIBlock(true, blockDurationMs) を有効にしていることを確認します。HarmonyOS の UI ジャンク収集は、システムの MAIN_THREAD_JANK イベントのみに依存します。SDK はイベントの begin_time、end_time を使用して時間を計算し、blockDurationMs しきい値を超えるフォアグラウンドのジャンクのみを送信します。
システムイベントには、起動時の猶予期間、連続タイムアウトの要件、プロセス単位の送信制限があります。そのため、単一のブロックテストだけを収集が有効かどうかの唯一の判断材料にすることはできません。調査時は SDK デバッグログを有効にし、hilog で [FT-UI-BLOCK] をフィルタして、システムイベントリスナーが登録されているか、ジャンクが送信済みかを確認します。
ネットワークリクエストの自動収集¶
HttpInterceptorChain が有効にならない¶
@kit.NetworkKit の HttpInterceptorChain による自動収集が有効にならない場合は、まず以下を確認することを推奨します。
- 現在のデバイスまたはコンパイルターゲットが HarmonyOS API 22 以上かどうか。API 22 未満ではこの機能はサポートされません
- プロジェクトに
ft_sdk.harとft_sdk_ext.harがインストールされ、oh-package.json5でそれぞれ@guancecloud/ft_sdkと@guancecloud/ft_sdk_extとして宣言した後にohpm installを完了しているか setEnableTraceUserResource(true)を有効にしているか。Trace Headers を自動注入する必要がある場合は、Trace 設定のsetEnableAutoTrace(true)も有効にする必要があります@kit.NetworkKitの並行リクエストのシナリオでは、各リクエストに対して独立したHttpRequestとHttpInterceptorChainを作成しても、次の例外が発生する可能性があります:{"code":2300003,"message":"Invalid URL format or missing URL"}- 上記のエラーが発生した場合は、まずシリアル検証に切り替えることを推奨します。並行シナリオでは RCP または Axios 互換モードに変更するか、高並行の経路で
HttpInterceptorChainを一時的に使用しないようにしてください
Resource を収集できない¶
HTTP リクエストがすでに作成され、自動収集インターセプターがマウントされている一方で、SDK の初期化と RUM 設定が後から実行される場合、リクエストは成功しても Resource データが生成されないことがあります。
まず以下を確認することを推奨します。
- 先に
HttpRequestを作成し、createFTHttpInterceptorChain()またはapplyFTHttpTrack()を呼び出した後でFTSDK.installRUMConfig()を実行していないか - RUM 設定で
setEnableTraceUserResource(true)を有効にしているか
原因:
HttpInterceptorChainの作成時に、現在の RUM 設定を即座に読み取り、Resource の自動収集を有効にするかどうかを決定します- この処理が
FTSDK.installRUMConfig()より前に発生すると、SDK が読み取るデフォルト値はfalseになります - その後 SDK の初期化を完了しても、すでに作成済みの自動収集インターセプターインスタンスは自動的に有効状態に更新されないため、
Resourceは生成されません
推奨される対処方法:
- 先に
FTSDK.install()、FTSDK.installRUMConfig()を完了してから、HttpRequestを作成しHttpInterceptorChainをマウントします - リクエストオブジェクトまたはインターセプターチェーンを事前に作成済みの場合は、SDK 初期化完了後に再作成し、再マウントする必要があります
- SDK 初期化前に自動収集オブジェクトを先に作成する必要がある場合は、作成時にスイッチを明示的に渡し、デフォルト設定値への依存を避けてください
任意の記述例:
applyFTAxiosTrack(client, {
enableTraceInterceptor: true,
enableResourceInterceptor: true
});
// その後、FTSDK.install(...) と FTSDK.installRUMConfig(...) を完了してから、業務リクエストを送信します。
注意:
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 })
Resource は存在するが Network Error がない¶
リクエストに HTTP レスポンスがない場合は、まず FTRUMConfig.setNetworkErrorHandler(...) および統合レベルの networkErrorHandler を確認します。Handler が true を返すと、ステータスコード 0 の Resource は保持され、そこから派生する Network Error のみがスキップされます。HTTP 4xx/5xx はこのフィルタの影響を受けません。詳細は ローカルネットワーク失敗のフィルタ を参照してください。
ネットワークフェーズまたはリクエストサイズが欠落¶
RCP ではプラットフォームが timeInfo を提供する必要があり、HTTP/Axios では performanceTiming が必要です。プラットフォームが公開していない場合、タイムスタンプの順序が異常な場合、接続が再利用された場合などには一部のフェーズが欠落しますが、SDK は値を補完しません。HTTPS の接続所要時間は 0.1.18 以降 TLS を含むため、SSL の所要時間と加算することはできません。
リクエストサイズ、プロトコル、接続の再利用も、プラットフォームまたは統合側が提供する有効な値に依存します。欠落をゼロまたは false として解釈しないでください。リクエスト開始時の帯域幅、検証状態、信号も、すべてのデバイスで取得できるわけではありません。Resource パフォーマンスの説明 および アプリケーションデータ収集 を参照してください。
セッションリプレイ¶
- コアパッケージ、Replay パッケージ、プラグインのバージョンを確認し、HarmonyOS セッションリプレイ(実験的) に従ってインストールを完了します。
- SDK と RUM を先に初期化し、その後 Replay を初期化してプライベート
filesDirを渡すことを確認します。setDelayInit(true)を設定した場合は、明示的にstart()を呼び出す必要があります。 - サンプリングにヒットしていることを確認します。Replay の
setSampleRate(10)は 10% であり、RUM のサンプリングとは独立して設定されます。エラーサンプリングモードのみ、関連する RUM Error が発生した場合にアップロードキューに入ります。 - プラグインが現在のモジュールとページを処理しているか確認します。プラグインを使用しない場合は、表示可能なページのルートノードを手動登録していることを確認します。初期化および
isEnabled()がtrueを返すことは、有効なリプレイフレームが保存されたことを証明するものではありません。 - テキスト、画像、タッチはデフォルトでマスクされます。画面内容がマスクされている、またはタッチ位置がない場合は、まずプライバシーポリシーを確認してから、収集異常の有無を判断してください。
- ArkWeb では、ネイティブ WebView RUM Bridge と Web ページの Browser SDK による録画開始も必要です。ネイティブ Replay は Web ページ SDK の読み込み前に準備されている必要があり、必要に応じて Web ページを再読み込みしてください。
- コアのアップロード先が有効であることを確認します。ローカルの DataKit を使用する場合は、リプレイ受信設定を確認してください。
disable() は新しい収集のみを停止します。すでに受け付けたフレームは引き続き保存され、自動アップロードは引き続きキューを処理します。停止後もアップロードリクエストが残っていても、録画が継続していることを意味しません。
関連ドキュメント¶
- インストールとエントリページ:アプリケーションの接続 を参照してください
- 初期化パラメータ:SDK 初期化 を参照してください
- RUM ネットワーク収集:RUM 設定 を参照してください
- Trace 分散型トレーシング:Trace 設定 を参照してください