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

このドキュメントでは、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);

リリースバージョンを公開する際は、この設定を無効にすることを推奨します。

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 によって書き込まれるビジネスログは含みません。

内部ログの完全性を保つために、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() を使用して未送信のデータをクリアした後、再検証できます

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

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 ヘッダーを自動的に注入する必要がある場合は、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 設定 を参照