コンテンツにスキップ

RUM 設定

この記事では、HarmonyOS RUM の初期化設定と手動収集機能について説明します。

サンプリングフィールドの移行(ft_sdk >= 0.1.18):setSessionSamplingRate、setSessionOnErrorSamplingRate は 0~100 の浮動小数点パーセントを使用します。旧 setSamplingRate、setSessionErrorSampleRate は 0~1 の単位を維持しており、移行時は値を 100 倍します。新しいフィールドは明示的に設定された場合にのみ旧フィールドより優先され、不正な値は例外をスローし、以前の有効値を変更しません。このバージョン未満では引き続き旧メソッドを使用します。非推奨は削除を意味せず、旧メソッドは元の単位と動作を維持します。

RUM 初期化設定

import {
  DetectFrequency,
  DeviceMetricsMonitorType,
  ErrorMonitorType,
  FTSDK,
  FTRUMConfig
} from '@guancecloud/ft_sdk/Index';

const rumConfig = new FTRUMConfig()
  .setRumAppId('your-app-id')
  .setSessionSamplingRate(100)
  .setSessionOnErrorSamplingRate(0)
  .setEnableTraceUserAction(true)
  .setEnableTraceUserView(true)
  .setEnableTraceUserResource(true)
  .setEnableTrackAppUIBlock(true)
  .setEnableTrackAppANR(true)
  .setEnableTrackAppCrash(true)
  .setEnableTraceWebView(true)
  .setDeviceMetricsMonitorType(DeviceMetricsMonitorType.ALL, DetectFrequency.DEFAULT)
  .setExtraMonitorTypeWithError(ErrorMonitorType.ALL)
  .addGlobalContext('rum_channel', new String('official'));

FTSDK.installRUMConfig(rumConfig);
メソッド名 型 必須 説明
setRumAppId string 是 RUM アプリケーション ID。[RUM]アプリから取得します
setSessionSamplingRate number 否 セッションサンプリング率を設定します。値の範囲は [0,100] で、0 はサンプリングしない、100 はすべてサンプリングすることを示します。デフォルト値は 100 で、小数をサポートします。スコープは同じ session_id 配下の RUM データです。ft_sdk 0.1.18 以降でサポートされます
setSessionOnErrorSamplingRate number 否 エラーサンプリング率を設定します。セッションが setSessionSamplingRate でサンプリングされていない場合、セッション中にエラーが発生すると、エラー発生前 1 分間の範囲のデータを収集できます。値の範囲は [0,100] で、0 はサンプリングしない、100 はすべてサンプリングすることを示します。デフォルト値は 0 で、小数をサポートします。ft_sdk 0.1.18 以降でサポートされます
setSamplingRate number 否 非推奨の互換 API です。値の範囲は [0,1]、デフォルト値は 1 です。setSessionSamplingRate に置き換えてください
setSessionErrorSampleRate number 否 非推奨の互換 API です。値の範囲は [0,1]、デフォルト値は 0 です。setSessionOnErrorSamplingRate に置き換えてください
setEnableTraceUserAction boolean 否 自動アクショントラッキングを有効にするかどうか。デフォルトは false です
setEnableTraceUserView boolean 否 ページトラッキングを有効にするかどうか。デフォルトは false です
setEnableTraceUserResource boolean 否 リソーストラッキングを有効にするかどうか。デフォルトは false です
setEnableTrackAppUIBlock boolean, number 否 UI ブロック検出を有効にするかどうか。デフォルトは false です。2 番目の引数 blockDurationMs は検出時間範囲 [100,) を制御するために使用し、単位はミリ秒、デフォルトは 1000ms です
setEnableTrackAppANR boolean 否 ANR 監視を有効にするかどうか。デフォルトは false です
setEnableTrackAppCrash boolean 否 アプリクラッシュ監視を有効にするかどうか。デフォルトは false です。Native Crash が必要な場合は、@guancecloud/ft_native に依存する必要があります
setEnableTraceWebView boolean 否 WebView RUM データ収集を有効にするかどうか。デフォルトは false です。完全な導入が必要な場合は、WebView データモニタリング を参照してください
setAllowWebViewHost Array<string> \| null 否 このメソッドは非推奨です。FTSDKConfig.setAllowWebViewHost(...) を使用して WebView RUM と Replay の Host 範囲を統一的に設定してください。詳細は SDK 初期化設定 を参照してください
setActionTrackingHandler FTActionTrackingHandler \| null 否 自動 Action ハンドラーを設定します。HandlerAction のカスタム名と属性を返します。null は収集をスキップし、undefined はデフォルトを維持します。自動 Click フィルタリングは 0.1.16 以降でサポートされています。コールドスタート、ホットスタートの処理およびカスタム戻り値の動作は 0.1.18 以降を参照してください。setEnableTraceUserAction(true) を有効にする必要があります。詳細はデータ収集カスタムルールを参照してください
setViewTrackingHandler handler: FTViewTrackingHandler \| null, type?: FTViewTrackingType 否 Router、Navigation、またはすべての自動 View のハンドラーを設定します。setEnableTraceUserView(true) を有効にした場合にのみ有効になります。ハンドラーは FTViewTrackingContext を受け取り、HandlerView を返すと名前変更や属性追加ができ、null を返すと収集をスキップします。詳細はデータ収集カスタムルールを参照してください。ft-sdk 0.1.17 以降でサポートされます
setResourceUrlHandler FTInTakeUrlHandler 否 自動 Resource の URL フィルターハンドラーを設定します。ハンドラーが true を返すと収集をスキップします。RCP、Axios、NetworkKit の自動 Resource にのみ影響し、Trace Header の注入と手動 Resource には影響しません。詳細はデータ収集カスタムルールを参照してください。ft-sdk 0.1.17 以降でサポートされます
setNetworkErrorHandler FTNetworkErrorHandler \| null 否 自動 RCP、Axios、NetworkKit リクエストで HTTP レスポンスがない場合のデフォルトエラーハンドラーを設定します。Resource を保持し、派生する Network Error をスキップできます。0.1.18 以降でサポートされます。詳細はローカルネットワーク障害フィルタリングを参照してください
setDeviceMetricsMonitorType DeviceMetricsMonitorType, DetectFrequency(オプション) 否 View の監視情報とサンプリング頻度を設定し、View 周期に監視データを追加します。第 1 引数には CPU、MEMORY、BATTERY、FPS のビット OR 組み合わせ、または ALL ですべて有効にすることを指定できます。TV デバイスはバッテリー指標をサポートしません。第 2 引数には DetectFrequency.DEFAULT(500ms)、DetectFrequency.FREQUENT(100ms)、DetectFrequency.RARE(1000ms)を指定できます。省略した場合は現在のサンプリング頻度を引き継ぎ、初期値は DEFAULT です。デフォルトでは収集しません。ft-sdk 0.1.16 以降でサポートされます
setDeviceMetricsDetectFrequency DetectFrequency 否 旧版のデバイス指標設定方法で、ソース互換性のためにのみ保持されています。単一引数の setDeviceMetricsMonitorType(...) と組み合わせて使用できます。新規導入では、setDeviceMetricsMonitorType(deviceMetricsMonitorType, detectFrequency) を使用して収集タイプと頻度を一度に設定することを推奨します
setExtraMonitorTypeWithError ErrorMonitorType 否 Error イベントに追加するデバイス指標を設定します。CPU、MEMORY、BATTERY のビット OR 組み合わせ、または ALL ですべて有効にすることを指定できます。有効にすると、Error データに CPU、メモリ、バッテリー関連のフィールドが追加されます。デフォルトでは収集しません。TV デバイスはバッテリー指標をサポートしません。フィールドの説明はアプリケーションデータ収集を参照してください。ft-sdk 0.1.16 以降でサポートされます
addGlobalContext key: string, value: object 否 RUM カスタムタグを追加し、ユーザーモニタリングデータを区別するために使用します。追加ルールはこちらを参照してください
setRumCacheLimitCount number 否 RUM データのキャッシュ数上限。デフォルトは 100000、最小値は 10000 です
setRumCacheDiscardStrategy RUMCacheDiscard 否 RUM データが上限に達した後の RUM 破棄ルールを設定します。デフォルトは RUMCacheDiscard.DISCARD です。DISCARD は追加データを破棄し、DISCARD_OLDEST は古いデータを破棄します

RUM 手動収集

FTRUMConfig で setEnableTraceUserAction、setEnableTraceUserView、setEnableTraceUserResource、setEnableTrackAppUIBlock、setEnableTrackAppCrash、setEnableTrackAppANR を設定すると、Action、View、Resource、LongTask、Error の自動収集を実現できます。カスタム収集が必要な場合は、FTRUMGlobalManager を使用して手動で送信できます。

View

使用方法

/**
 * View のライフサイクルを開始します。
 *
 * @param viewName View 名。
 * @param property オプションの拡張属性。
 */
startView(viewName: string, property?: Record<string, object>): Promise<void>

/**
 * 現在の View のライフサイクルを終了します。
 *
 * @param property オプションの拡張属性。
 */
stopView(property?: Record<string, object>): Promise<void>

/**
 * 現在の View のロード時間を更新します。
 *
 * @param loadTime ロード時間(ナノ秒単位)。
 */
updateLoadTime(loadTime: number): void

コード例

import { FTRUMGlobalManager } from '@guancecloud/ft_sdk/Index';

@Entry
@Component
struct ProductPage {
  async aboutToAppear() {
    // シナリオ 1(シナリオ 2 とのいずれかを選択)
    // await FTRUMGlobalManager.getInstance().startView('ProductPage');

    // シナリオ 2: 動的パラメータ
    const viewProperty: Record<string, object> = {
      ft_key: new String('ft_value'),
      ft_key_will_change: new String('ft_value')
    };
    await FTRUMGlobalManager.getInstance().startView('ProductPage', viewProperty);
  }

  async aboutToDisappear() {
    // シナリオ 1(シナリオ 2 とのいずれかを選択)
    // await FTRUMGlobalManager.getInstance().stopView();

    // シナリオ 2: 動的パラメータ
    const stopViewProperty: Record<string, object> = {
      ft_key_will_change: new String('ft_value_change')
    }; // ft_key_will_change の値は stopView 時に ft_value_change に更新されます
    await FTRUMGlobalManager.getInstance().stopView(stopViewProperty);
  }

  build() {
    Column() {
      Text('Product Page');
    }
  }
}

Action

使用方法

/**
 * 完了済みの Action を追加します。このデータは Error、Resource、LongTask に関連付けられません。
 *
 * @param actionName Action 名。
 * @param actionType Action タイプ。例: `click`。
 * @param durationOrProperty オプション。number を渡した場合は継続時間(ナノ秒)を表し、Record を渡した場合は拡張属性を表します。
 * @param property オプション。第 3 引数が継続時間の場合にのみ拡張属性を渡します。
 */
addAction(
  actionName: string,
  actionType: string,
  durationOrProperty?: number | Record<string, object>,
  property?: Record<string, object>
): void

/**
 * Action を開始します。SDK が終了タイミングを管理し、近くで発生した Resource、LongTask、Error データを関連付けます。
 *
 * @param actionName Action 名。
 * @param actionType Action タイプ。例: `click`。
 * @param property オプションの拡張属性。
 */
startAction(
  actionName: string,
  actionType: string,
  property?: Record<string, object>
): void

addAction(...) は直接完了した Action に使用し、Error、Resource、LongTask などのデータを関連付けることはできません。duration の単位はナノ秒です。第 3 引数には拡張属性を直接渡せます。時間と拡張属性を同時に渡す場合は、第 3、第 4 引数として順に渡します。

startAction(...) は SDK が終了タイミングと関連データを管理します。現時点では stopAction(...)、待機状態などの手動制御インターフェースは提供していません。

コード例

import { FTRUMGlobalManager } from '@guancecloud/ft_sdk/Index';

// シナリオ 1:
FTRUMGlobalManager.getInstance().addAction('buy_button_click', 'click');

// シナリオ 2: 拡張属性付き
const actionProperty: Record<string, object> = {
  product_id: new String('product_id'),
  product_name: new String('product_name')
};
FTRUMGlobalManager.getInstance().addAction('buy_button_click', 'click', actionProperty);

// シナリオ 1:
FTRUMGlobalManager.getInstance().startAction('buy_button_click', 'click');

// シナリオ 2: 拡張属性付き
const startActionProperty: Record<string, object> = {
  product_id: new String('product_id'),
  product_name: new String('product_name')
};
FTRUMGlobalManager.getInstance().startAction('buy_button_click', 'click', startActionProperty);

Error

使用方法

/**
 * Error を送信します。
 *
 * @param log エラーログまたはスタック情報。
 * @param message メッセージ。
 * @param errorType エラータイプ。`ErrorType` 列挙型または文字列を渡せます。
 * @param state エラー発生時のアプリケーション実行状態。
 * @param property オプションの拡張属性。
 */
addError(
  log: string,
  message: string,
  errorType: string | ErrorType,
  state: AppState,
  property?: Record<string, object> | null
): void

/**
 * 発生時刻を指定して Error を送信します。
 *
 * @param log エラーログまたはスタック情報。
 * @param message メッセージ。
 * @param dateline エラー発生時刻(ナノ秒単位)。
 * @param errorType エラータイプ。`ErrorType` 列挙型または文字列を渡せます。
 * @param state エラー発生時のアプリケーション実行状態。
 * @param property オプションの拡張属性。
 */
addError(
  log: string,
  message: string,
  dateline: number,
  errorType: string | ErrorType,
  state: AppState,
  property?: Record<string, object> | null
): void

カスタム Error には ErrorType.CUSTOM を使用してください。dateline は任意の発生時刻で、単位はナノ秒です。

コード例

import { FTRUMGlobalManager, ErrorType, AppState } from '@guancecloud/ft_sdk/Index';
import { systemDateTime } from '@kit.BasicServicesKit';

// シナリオ 1:
FTRUMGlobalManager.getInstance().addError('error log', 'error message', ErrorType.CUSTOM, AppState.RUN);

// シナリオ 2: 遅延送信時は、エラーが実際に発生した時刻を渡します(単位: ナノ秒)。
const errorTimeNs = systemDateTime.getTime(true);
FTRUMGlobalManager.getInstance().addError('error log', 'error message', errorTimeNs, ErrorType.CUSTOM, AppState.RUN);

// シナリオ 3: 拡張属性付き。
const errorProperty: Record<string, object> = {
  module: new String('checkout'),
  action: new String('submit_order')
};
FTRUMGlobalManager.getInstance().addError('error log', 'error message', ErrorType.CUSTOM, AppState.RUN, errorProperty);

LongTask

使用方法

/**
 * LongTask を送信します。
 *
 * @param log ブロック発生時のログまたはスタック情報。
 * @param duration ブロック継続時間(ナノ秒単位)。
 * @param property オプションの拡張属性。
 */
addLongTask(log: string, duration: number, property?: Record<string, string | number | boolean>): void

duration の単位はナノ秒です。

コード例

import { FTRUMGlobalManager } from '@guancecloud/ft_sdk/Index';

const durationMs = 350;
const durationNs = durationMs * 1000000;
const stack = new Error('checkout render long task').stack ?? 'Stack trace not available';

// シナリオ 1:
FTRUMGlobalManager.getInstance().addLongTask(stack, durationNs);

// シナリオ 2: 拡張属性付き。
const longTaskProperty: Record<string, string | number | boolean> = {
  module: 'checkout',
  operation: 'render_order_list',
  threshold_ms: 200
};
FTRUMGlobalManager.getInstance().addLongTask(stack, durationNs, longTaskProperty);

Resource

使用方法

/**
 * Resource のライフサイクルを開始します。
 *
 * @param resourceId リソースの一意な識別子。`stopResource`、`addResource` と同じ値を使用する必要があります。
 * @param property オプションの拡張属性。
 */
startResource(resourceId: string, property?: Record<string, object>): void

/**
 * Resource のライフサイクルを終了します。
 *
 * @param resourceId リソースの一意な識別子。`startResource` と同じ値を使用してください。
 * @param property オプションの拡張属性。
 */
stopResource(resourceId: string, property?: Record<string, object>): void

/**
 * Resource のリクエスト、レスポンス、ネットワークパフォーマンスデータを補足します。
 *
 * @param resourceId リソースの一意な識別子。`startResource`、`stopResource` と同じ値を使用してください。
 * @param resourceParams リソース詳細。URL、リクエストメソッド、レスポンスステータス、レスポンス長、拡張属性など。
 * @param netStatusBean ネットワークパフォーマンスデータ。DNS、TCP、TTFB、レスポンス時間など。
 */
addResource(resourceId: string, resourceParams: ResourceParams, netStatusBean: NetStatusBean): void

startResource(...)、stopResource(...) に渡した拡張属性は、呼び出し順に ResourceParams の属性とマージされます。リソースステータスコードとレスポンス長は ResourceParams で設定してください。stopResource(...) の引数としては渡さなくなりました。

コード例

import {
  FTRUMGlobalManager,
  ResourceParams,
  NetStatusBean
} from '@guancecloud/ft_sdk/Index';

const resourceId = 'https://api.example.com/data';

// シナリオ 1:
// リクエスト開始
FTRUMGlobalManager.getInstance().startResource(resourceId);

// リクエスト終了後、リクエスト、レスポンス、ネットワークパフォーマンスデータを補足します。
const resourceParams = new ResourceParams();
resourceParams.setUrl(resourceId);
resourceParams.setResourceStatus(200);
resourceParams.setResponseContentLength(1024);
resourceParams.resourceType = 'xhr';

// オプション: 転送情報を設定します(0.1.18 以降)。
resourceParams.setRequestBodySize(128);
resourceParams.setRequestHeaderSize(256);
resourceParams.setHttpProtocol('HTTP/2');
resourceParams.setConnectionReuse(true);

const netStatusBean = new NetStatusBean();
netStatusBean.setResourceHostIP('192.168.1.1');
netStatusBean.setDNSTime(10000000);
netStatusBean.setTcpTime(20000000);
netStatusBean.setTTFB(50000000);
netStatusBean.setResponseTime(100000000);

FTRUMGlobalManager.getInstance().stopResource(resourceId);
FTRUMGlobalManager.getInstance().addResource(resourceId, resourceParams, netStatusBean);

// シナリオ 2: 拡張属性付き。以下は独立したリクエストで、使用時はシナリオ 1 の startResource と stopResource の呼び出しを置き換えてください。
const startResourceProperty: Record<string, object> = {
  request_source: new String('checkout')
};
FTRUMGlobalManager.getInstance().startResource(resourceId, startResourceProperty);

const stopResourceProperty: Record<string, object> = {
  response_cache: new Boolean(false)
};
FTRUMGlobalManager.getInstance().stopResource(resourceId, stopResourceProperty);

リクエストヘッダーとリクエストボディのサイズの単位は byte です。setRequestSize(...) でリクエストの総バイト数を直接設定することもできます。フィールドの説明はアプリケーションデータ収集を参照してください。

NetStatusBean プロパティ説明

NetStatusBean は、手動 Resource 収集のネットワークパフォーマンスデータを補足するために使用します。すべての時間パラメータの単位はナノ秒です。*StartTime は Resource 開始時刻に対するオフセットを表します。未設定の時間値のデフォルトは -1 で、対応する指標には書き込まれません。

メソッド 説明
setDNSTime DNS 解決時間
setDNSStartTime DNS 解決開始オフセット
setTcpTime TCP 接続確立時間
setConnectStartTime TCP 接続確立開始オフセット
setSSLTime SSL/TLS ハンドシェイク時間
setSslStartTime SSL/TLS ハンドシェイク開始オフセット
setTTFB 最初のバイトが到着するまでの待機時間(TTFB)
setResponseTime レスポンス転送時間
setFirstByteTime 初回バイト段階の所要時間
setFirstByteStartTime 初回バイト段階の開始オフセット
setDownloadTime レスポンスダウンロード時間
setDownloadTimeStart レスポンスダウンロード開始オフセット
setHoleRequestTime リクエスト全体の所要時間(API 名は SDK 定義に従い Hole の綴りを維持)
setResourceHostIP リソースサーバー IP アドレス

Resource 自動トラッキング

setEnableTraceUserResource(true) を有効にすると、SDK は RCP、Axios 互換モード、または @kit.NetworkKit HTTP インターセプター経由で送信されたリクエストを自動的に追跡します。

業務で @guancecloud/ft_sdk_ext を導入する場合は、公開 API を @guancecloud/ft_sdk_ext/Index から統一的にインポートし、src/main/... の深いパスを使用しないことを推奨します。

RCP 自動トラッキングの導入

RUM 設定で setEnableTraceUserResource を有効にすると、SDK は RCP 経由で送信された HTTP リクエストの Resource データを自動収集します。

現在のバージョンから、SDK はグローバル RCP Session を自動で作成または保持しなくなり、以下の機能を業務側で組み込むために提供します。

  • RCPTraceInterceptor:Trace Headers を自動注入
  • RCPResourceInterceptor:Resource データとパフォーマンス指標を自動収集
  • createFTRCPInterceptors():デフォルトの RCP インターセプター一覧を返し、カスタム SessionConfiguration とマージしやすくします
  • createFTRCPTrackConfig():デフォルトのインターセプターと TracingConfiguration を含む SessionConfiguration をすばやく生成します

推奨導入方法:デフォルトの SessionConfiguration ファクトリ関数を使用する

import { rcp } from '@kit.RemoteCommunicationKit';
import { createFTRCPTrackConfig } from '@guancecloud/ft_sdk/Index';

const session = rcp.createSession(
  createFTRCPTrackConfig({
    baseAddress: 'https://api.example.com'
  })
);

// GET リクエスト
const request = new rcp.Request('/data', 'GET');
const response = await session.fetch(request);

// POST リクエスト
const headers: rcp.RequestHeaders = { 'Content-Type': 'application/json' };
const postRequest = new rcp.Request('/data', 'POST', headers, { name: 'test' });
const postResponse = await session.fetch(postRequest);

プロジェクトが SDK ルートエントリからインポートする場合は、以下も使用できます。

import { createFTRCPTrackConfig } from '@guancecloud/ft_sdk/Index';

インターセプターを手動で組み込む

Session 設定を完全に制御する必要がある場合は、SDK が提供するインターセプターを直接使用することもできます。

import { rcp } from '@kit.RemoteCommunicationKit';
import { RCPTraceInterceptor, RCPResourceInterceptor } from '@guancecloud/ft_sdk/Index';

const session = rcp.createSession({
  baseAddress: 'https://api.example.com',
  interceptors: [
    new RCPTraceInterceptor(),
    new RCPResourceInterceptor()
  ],
  requestConfiguration: {
    tracing: {
      collectTimeInfo: true
    }
  }
});

TracingConfiguration の説明:

  • collectTimeInfo: true:有効化を推奨します。SDK は response.timeInfo に依存して DNS、TCP、SSL、TTFB、ダウンロード時間などのパフォーマンス指標を計算します
  • incomingHeader / outgoingHeader:オプション。デフォルトで有効です
  • incomingData / outgoingData:デフォルトで無効です。追加のオーバーヘッドを削減します

HTTP インターセプター導入

業務で @kit.NetworkKit の http.createHttp() を使用してリクエストを送信する場合、@guancecloud/ft_sdk_ext が提供する HTTP インターセプターにより、Trace Header の自動注入と Resource 収集を実現できます。この導入方法には ft_sdk_ext 0.1.14 以降および HarmonyOS API 22 以降が必要です。

まず、プロジェクトに以下がインストールされていることを確認してください。

  • ft_sdk.har。oh-package.json5 で @guancecloud/ft_sdk として宣言します
  • ft_sdk_ext.har。oh-package.json5 で @guancecloud/ft_sdk_ext として宣言します
  • ローカル HAR で ft_sdk_ext.har をインストールする場合、プロジェクトルートの oh-package.json5 に overrides["@guancecloud/ft_sdk"] = "file:./libs/ft_sdk.har" を追加し、その内部依存をローカル HAR に書き換える必要があります

SDK は以下の機能を提供します。

  • HttpInitialRequestInterceptor:リクエスト開始段階で Trace Header を注入し、Resource を開始します
  • HttpFinalResponseInterceptor:レスポンス終了段階で Resource データを補足し、収集を終了します
  • createFTHttpInterceptorChain():再利用可能な http.HttpInterceptorChain を作成します
  • applyFTHttpTrack():デフォルトのインターセプターチェーンを単一の http.HttpRequest に直接マウントします
  • disposeFTHttpTrack(request):リクエストをキャンセルまたは破棄する前に収集リソースを解放します

2 つの導入方法を提供します。

方法 1:SDK が提供するデフォルトファクトリを使用する

import { http } from '@kit.NetworkKit';
import { createFTHttpInterceptorChain, disposeFTHttpTrack } from '@guancecloud/ft_sdk_ext/Index';

const request = http.createHttp();
const interceptorChain = createFTHttpInterceptorChain();
interceptorChain.apply(request);

try {
  const response = await request.request('https://httpbin.org/get', {
    method: http.RequestMethod.GET,
    header: {
      'Accept': 'application/json'
    }
  });
} finally {
  disposeFTHttpTrack(request);
  request.destroy();
}

業務独自のインターセプターをさらに追加する場合は、次のように記述することもできます。

import { http } from '@kit.NetworkKit';
import { createFTHttpInterceptorChain } from '@guancecloud/ft_sdk_ext/Index';

const request = http.createHttp();
const interceptorChain = createFTHttpInterceptorChain({
  interceptors: [
    new CustomAfterInterceptor()//カスタムを追加
  ]
});
interceptorChain.apply(request);

この場合の実行順序は次のとおりです。

[
  new HttpInitialRequestInterceptor(),
  new HttpFinalResponseInterceptor(),
  new CustomAfterInterceptor()
]

方法 2:HttpInterceptorChain を手動で組み込む

業務側にすでにカスタムインターセプターがある場合、またはインターセプターの順序を自由に決める必要がある場合は、http.HttpInterceptorChain を直接手動で作成することを推奨します。

import { http } from '@kit.NetworkKit';
import {
  HttpInitialRequestInterceptor,
  HttpFinalResponseInterceptor
} from '@guancecloud/ft_sdk_ext/Index';

const request = http.createHttp();
const interceptorChain = new http.HttpInterceptorChain();
interceptorChain.addChain([
  new CustomBeforeInterceptor(),
  new HttpInitialRequestInterceptor(),
  new HttpFinalResponseInterceptor()
]);
interceptorChain.apply(request);

注意事項:

  • HTTP インターセプターは、@kit.NetworkKit が API 22+ で提供するインターセプター機能に依存します。API 22 未満では RCP または Axios 互換モードを使用してください
  • http.createHttp() を直接使用する HTTP インターセプターモードでは、HttpRequestContext から現在安定して実際のリクエストメソッドを取得できないため、Resource の method が UNKNOWN として記録される可能性があります
  • 業務で @ohos/axios の interceptorChain モードを使用する場合は、axios の実際の method、url、headers をブリッジするために applyFTAxiosChainMethodBridge() を追加でマウントすることを推奨します

Axios 導入

業務で @ohos/axios を使用する場合、以下の方法で自動トラッキングを導入できます。

  • @guancecloud/ft_sdk:Axios の request/response interceptors に基づく互換モード
  • @guancecloud/ft_sdk_ext:0.1.14 以降で interceptorChain に基づく拡張モードを提供します

@ohos/axios 2.2.4 以降のバージョン

この導入方法は Axios の request/response interceptors に基づきます。

import axios from '@ohos/axios';
import { applyFTAxiosTrack } from '@guancecloud/ft_sdk/Index';

const client = axios.create({
  timeout: 10000
});

applyFTAxiosTrack(client);

この導入方法は、業務独自のインターセプターと共存できます。

import axios from '@ohos/axios';
import { applyFTAxiosTrack } from '@guancecloud/ft_sdk/Index';

const client = axios.create({
  timeout: 10000
});

applyFTAxiosTrack(client);

client.interceptors.request.use((config) => {
  config.headers = {
    ...(config.headers || {}),
    Authorization: 'Bearer <token>',
    'X-Signature': 'signed-value'
  };
  return config;
});

client.interceptors.response.use((response) => {
  return response;
});

実行順序の説明:

  • @ohos/axios の compat モードでは、request インターセプターは 後から登録したものが先に実行される 動作になります
  • これは、複数の request interceptors が共存できる一方で、登録順序によって FT が「変更前」と「変更後」のどちらのリクエストヘッダーを認識するかに影響することを意味します
  • FT が、業務側で認証や署名などのフィールドを補完した後の最終的なリクエストヘッダーを収集することを希望する場合、推奨順序は 先に applyFTAxiosTrack(client)、その後で業務の request interceptor を登録する です
  • 上記の順序では、業務の request interceptor が先に実行され、その後に FT が実行されて最終的な headers を読み取ります
  • 順序を調整したい場合は、登録順序を変更するだけです。たとえば、先に業務側を登録し、その後に applyFTAxiosTrack(client) を呼び出すと、FT が先に実行され、業務のインターセプターが後で実行されます

@ohos/axios 2.2.8 以降

@ohos/axios 2.2.8 以降では、@guancecloud/ft_sdk_ext の interceptorChain を介して FT 自動トラッキングを導入することを優先的に推奨します。

import axios from '@ohos/axios';
import {
  createFTHttpInterceptorChain,
  applyFTAxiosChainMethodBridge
} from '@guancecloud/ft_sdk_ext/Index';

const client = axios.create({
  timeout: 10000,
  interceptorChain: createFTHttpInterceptorChain()
});

applyFTAxiosChainMethodBridge(client);

const response = await client.post('https://api.example.com/data', {
  source: 'axios',
  message: 'ft auto track'
});

複数のインターセプターが共存する場合、実行順序を手動で調整する必要がある場合、または業務のカスタムインターセプターと統一的に組み込む必要がある場合は、HTTP インターセプター導入 の内容を参照し、必要に応じて HttpInitialRequestInterceptor と HttpFinalResponseInterceptor を組み合わせてください。

単一リクエストごとに渡す場合は、次のように記述することもできます。

import axios from '@ohos/axios';
import { createFTHttpInterceptorChain } from '@guancecloud/ft_sdk_ext/Index';

const response = await axios.request({
  url: 'https://httpbin.org/post',
  method: 'post',
  data: {
    source: 'axios',
    message: 'ft auto track'
  },
  responseType: 'string',
  interceptorChain: createFTHttpInterceptorChain()
});

注意事項:

  • Axios インスタンス作成時に interceptorChain を統一的に注入し、applyFTAxiosChainMethodBridge(client) を呼び出すことを推奨します。bridge の呼び出し漏れにより Resource の method が正確に記録されないことを防ぎます。
  • interceptorChain モードは @guancecloud/ft_sdk_ext に依存し(ローカル HAR のファイル名は引き続き ft_sdk_ext.har)、HarmonyOS API 22+ が必要です
  • Trace Headers を自動注入するには、インターセプターチェーンの作成に加えて、Trace 設定で setEnableAutoTrace(true) を有効にする必要があります
  • Resource を自動収集するには、引き続き RUM 設定で setEnableTraceUserResource(true) を有効にする必要があります
  • 呼び出し元にすでにカスタム HTTP/Axios インターセプターがある場合は、HttpInitialRequestInterceptor、HttpFinalResponseInterceptor を直接用いて順序を手動で組み込むことを推奨します。FT 自動トラッキングの後に url、method、headers を再び書き換えないようにしてください
  • SDK はインターセプターとデフォルト設定のファクトリ関数のみを提供します。RCP Session の作成とライフサイクルは業務側で管理します
  • 業務で rcp.createSession() を直接使用して Session を作成する場合は、SDK が提供するインターセプターを自身で追加する必要があります。追加しない場合、リクエストは自動追跡されません
  • 業務で http.createHttp() または @ohos/axios を直接使用する場合は、applyFTHttpTrack()、applyFTAxiosTrack()、createFTHttpInterceptorChain() を明示的にマウントする必要があります。Axios の interceptorChain モードでは、さらに applyFTAxiosChainMethodBridge(client) を呼び出す必要があります

Resource パフォーマンス指標説明

RCP は response.timeInfo を使用し、NetworkKit HTTP およびそのネットワークアダプターを使用する Axios は performanceTiming を使用してパフォーマンスデータを取得します。以下の時点の単位はミリ秒で、計算結果は統一してナノ秒に変換して送信されます。

指標 RCP TimeInfo NetworkKit performanceTiming
DNS 時間 nameLookupTimeMs dnsTiming
TCP 時間 tlsHandshakeTimeMs - nameLookupTimeMs。有効な TLS 時点がない場合は connectTimeMs - nameLookupTimeMs tlsTiming - dnsTiming。有効な TLS 時点がない場合は tcpTiming - dnsTiming
SSL 時間 tlsHandshakeTimeMs - connectTimeMs tlsTiming - tcpTiming
TTFB startTransferTimeMs - preTransferTimeMs firstReceiveTiming - firstSendTiming
ダウンロード時間 totalTimeMs - startTransferTimeMs totalFinishTiming - firstReceiveTiming

段階の時点が欠落しているか無効な場合、対応する段階の指標は送信されません。

フィードバック

このページは役に立ちましたか?