トラブルシューティング¶

このドキュメントでは、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 が実行され、検証対象の収集項目が少なくとも 1 つ有効になっていることを確認します
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 のワーカーキューを可能な限りフラッシュしてから、すぐにアップロードをスケジュールします
• ローカルキャッシュに異常がある場合は、FTSDK.clearAllData() で未報告のデータをクリアした後、再度検証できます
• FileStore を使用する場合は、まずシャドーモードかどうかを確認します。シャドーモードでは、SQLite が引き続き読み取りとアップロードを担当し、同時に書き込みを FileStore にミラーリングして、移行前の検証に使用します。詳細な設定は SDK 初期化 を参照してください
• 初回の旧 SQLite キャッシュ移行では、setNeedTransformOldCache(true) を明示的に呼び出す必要があります。容量不足または旧キャッシュの破損時には、ソースキャッシュが保持されるため、条件を修正して再起動すれば処理を続行できます

RUM 自動収集¶

UI のカクつきが収集されない¶

RUM 設定で setEnableTrackAppUIBlock(true, blockDurationMs) が有効になっていることを確認します。HarmonyOS の UI カクつき収集は、システムの MAIN_THREAD_JANK イベントのみに依存します。SDK はイベントの begin_time、end_time を使用して時間を計算し、blockDurationMs のしきい値を超えるフォアグラウンドでのカクつきのみを報告します。

システムイベントには起動時の猶予期間、連続タイムアウト要件、プロセスレベルの報告制限があるため、1 回のブロックテストだけを収集の有効性を判断する唯一の基準にすることはできません。調査時には SDK の Debug ログを有効にし、hilog で [FT-UI-BLOCK] をフィルタリングして、システムイベントのリスナーが登録されているか、カクつきが報告されているかを確認します。

ネットワークリクエストの自動収集¶

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 設定 を参照してください