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 ルートエントリからインポートする場合は、以下も使用できます。
インターセプターを手動で組み込む
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 |
段階の時点が欠落しているか無効な場合、対応する段階の指標は送信されません。