콘텐츠로 이동

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 아니요 자동 Action 추적을 활성화할지 여부입니다. 기본값은 false입니다
setEnableTraceUserView boolean 아니요 페이지 추적을 활성화할지 여부입니다. 기본값은 false입니다
setEnableTraceUserResource boolean 아니요 Resource 추적을 활성화할지 여부입니다. 기본값은 false입니다
setEnableTrackAppUIBlock boolean, number 아니요 UI 지연 감지를 활성화할지 여부입니다. 기본값은 false입니다. 두 번째 매개변수 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 주기에 모니터링 데이터를 추가합니다. 첫 번째 매개변수는 CPU, MEMORY, BATTERY, FPS를 비트 OR로 조합하거나 ALL을 사용하여 모두 활성화할 수 있습니다. TV 기기에서는 배터리 지표를 지원하지 않습니다. 두 번째 매개변수는 선택 사항이며 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 선택 사항. 세 번째 매개변수가 지속 시간인 경우에만 확장 속성을 전달합니다.
 */
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의 단위는 나노초입니다. 세 번째 매개변수로 확장 속성을 바로 전달할 수 있으며, 지속 시간과 확장 속성을 동시에 전달하려면 각각 세 번째와 네 번째 매개변수로 전달합니다.

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): 요청을 취소하거나 폐기하기 전에 수집 리소스를 해제합니다

두 가지 연동 방식을 제공합니다.

방식 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)를 호출하여 브리지 누락으로 인해 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

단계별 시간 지점이 누락되었거나 유효하지 않으면 해당 단계 지표를 보고하지 않습니다.

문서 평가

이 페이지가 도움이 되었나요?