콘텐츠로 이동

RUM 설정

RUM 초기화 설정

let rumConfig: FTRUMConfig = {
  androidAppId: Config.ANDROID_APP_ID,
  iOSAppId: Config.IOS_APP_ID,
  enableAutoTrackUserAction: true,
  enableAutoTrackError: true,
  enableNativeUserAction: true,
  enableNativeUserView: false,
  enableNativeUserResource: true,
  enableIOSWebSocketResource: true,
  sessionSamplingRate: 100,
  errorMonitorType: ErrorMonitorType.all,
  deviceMonitorType: DeviceMetricsMonitorType.all,
  detectFrequency: DetectFrequency.rare,
  enableLongTask: true,
  longTaskThresholdMs: 200,
};

await FTReactNativeRUM.setConfig(rumConfig);
필드 타입 필수 설명
androidAppId string 예 app_id, 애플리케이션 액세스 모니터링 콘솔에서 신청
iOSAppId string 예 app_id, 애플리케이션 액세스 모니터링 콘솔에서 신청
sessionSamplingRate number 아니요 RUM 세션 샘플링 백분율, 범위 [0,100], 소수 지원, 기본값 100. 0은 수집하지 않음, 100은 전체 수집을 의미합니다. sampleRate보다 우선합니다. SDK 0.4.3부터 지원합니다.
sessionOnErrorSamplingRate number 아니요 일반 세션 샘플링에서 선택되지 않았을 때의 오류 세션 샘플링 백분율, 범위 [0,100], 소수 지원, 기본값 0. sessionOnErrorSampleRate보다 우선합니다. SDK 0.4.3부터 지원합니다.
visitorIdConfig FTVisitorIdConfig 아니요 SDK 0.4.3부터 지원합니다. 익명 방문자 식별자 설정이며 기본적으로 비활성화됩니다. 자세한 내용은 방문자 식별자 Visitor ID를 참고하세요.
sampleRate number 아니요 SDK 0.4.3부터 폐기되었으며 호환성을 위해 유지됩니다. sessionSamplingRate 사용을 권장합니다. 값 범위 [0,1], 0은 수집하지 않음, 1은 전체 수집을 의미하며 기본값은 1입니다. 적용 범위는 동일한 session_id 아래의 모든 View, Action, LongTask, Error 데이터입니다.
sessionOnErrorSampleRate number 아니요 SDK 0.4.3부터 폐기되었으며 호환성을 위해 유지됩니다. sessionOnErrorSamplingRate 사용을 권장합니다. 세션이 일반 세션 샘플링에서 선택되지 않았을 때 세션 중 오류가 발생하면 오류 발생 전 1분 범위의 데이터를 수집할 수 있습니다. 값 범위 [0,1], 0은 수집하지 않음, 1은 전체 수집을 의미하며 기본값은 0입니다. 적용 범위는 동일한 session_id 아래의 모든 View, Action, LongTask, Error 데이터입니다. SDK 0.3.14 이상에서 지원합니다.
enableAutoTrackUserAction boolean 아니요 React Native 컴포넌트 클릭 이벤트 자동 수집 여부. 활성화하면 accessibilityLabel과 함께 actionName을 설정할 수 있습니다. SDK 0.4.3부터 Babel 플러그인으로 Action 이름 자동 생성을 사용할 수 있습니다.
enableAutoTrackError boolean 아니요 React Native Error 자동 수집 여부, 기본값 false
enableNativeUserAction boolean 아니요 Native Action 추적 여부. 네이티브 Button 클릭 이벤트, 앱 시작 이벤트, 기본값 false
enableNativeUserView boolean 아니요 Native View 자동 추적 여부. 순수 React Native 앱에서는 비활성화를 권장합니다. 기본값 false
enableNativeUserResource boolean 아니요 네이티브 HTTP(S) Resource 자동 추적 활성화 여부. Android WebSocket 핸드셰이크도 이 항목으로 제어됩니다. 기본값 false; iOS WebSocket 핸드셰이크는 enableIOSWebSocketResource를 별도로 활성화해야 합니다.
enableIOSWebSocketResource boolean 아니요 SDK 0.4.3부터 지원합니다. iOS React Native WebSocket 핸드셰이크 Resource를 수집합니다. 기본값 false, enableNativeUserResource와 독립적입니다. 자세한 내용은 WebSocket 핸드셰이크 수집을 참고하세요.
errorMonitorType enum ErrorMonitorType 아니요 보조 모니터링 정보를 설정하고 RUM Error 데이터에 추가 모니터링 데이터를 추가합니다. 기본적으로 비활성화됩니다.
deviceMonitorType enum DeviceMetricsMonitorType 아니요 View 주기에 모니터링 데이터를 추가합니다. 기본적으로 비활성화됩니다.
detectFrequency enum DetectFrequency 아니요 View 성능 모니터링 샘플링 주기, 기본값은 DetectFrequency.normal
enableResourceHostIP boolean 아니요 요청 대상 도메인 주소의 IP 수집 여부. 적용 범위: enableNativeUserResource = true인 기본 수집에만 영향을 줍니다. iOS: >= iOS 13 지원; Android: 동일한 OkhttpClient에 IP 캐시 메커니즘이 존재합니다.
globalContext object 아니요 사용자 모니터링 데이터 소스를 구분하기 위한 사용자 정의 태그를 추가합니다. 추적 기능을 사용하려면 key 매개변수를 track_id로, value를 임의의 숫자 값으로 설정합니다. 태그 추가 규칙 주의사항은 여기를 참고하세요.
enableTrackNativeCrash boolean 아니요 Android Java Crash 및 OC/C/C++ 크래시 모니터링 활성화 여부, 기본값 false
enableTrackNativeAppANR boolean 아니요 Native ANR 모니터링 활성화 여부, 기본값 false
enableTrackNativeFreeze boolean 아니요 Native Freeze 수집 여부, 기본값 false
nativeFreezeDurationMs number 아니요 Native Freeze 수집 임계값 설정, 값 범위 [100,), 단위 밀리초. iOS 기본값 250ms, Android 기본값 1000ms
enableLongTask boolean 아니요 React Native JS LongTask 모니터링 활성화 여부, 기본값 false. 이 설정은 JS 스레드 지연만 수집하며 Native Freeze 모니터링과 상호 독립적입니다. SDK 0.4.3부터 지원합니다.
longTaskThresholdMs number 아니요 React Native JS LongTask 모니터링 임계값 설정, 값 범위 [100, 5000], 단위 밀리초, 기본값 100ms. enableLongTask = true인 경우에만 적용됩니다. 100 미만의 값은 100으로 처리하고, 5000 초과의 값은 5000으로 처리합니다. SDK 0.4.3부터 지원합니다.
rumDiscardStrategy string 아니요 폐기 정책: FTRUMCacheDiscard.discard는 새 데이터 폐기(기본값), FTRUMCacheDiscard.discardOldest는 오래된 데이터 폐기
rumCacheLimitCount number 아니요 로컬 캐시 최대 RUM 항목 수 제한 [10_000,), 기본값 100_000
enableTraceWebView boolean 아니요 WebView 데이터 수집 활성화 여부, 기본값 true. SDK 0.3.16 이상에서 지원합니다.
allowWebViewHost Array / null 아니요 데이터 추적을 허용할 WebView 호스트 주소를 설정합니다. null은 모든 호스트를 허용하고, []는 모든 호스트를 금지합니다. SDK 0.3.16부터 지원합니다. SDK 0.4.3부터는 FTMobileConfig.allowWebViewHost 사용을 권장하며, 이 필드는 호환성을 위해 유지되고 기본 설정이 지정되지 않은 경우에만 적용됩니다. 자세한 내용은 WebView host 설정을 참고하세요.
iosCrashMonitoringType enum IOSCrashMonitoringType 아니요 SDK 크래시 모니터링의 유형 범위를 설정합니다. 기본값은 IOSCrashMonitoringType.highCompatibility입니다. SDK 0.3.16 이상에서 지원합니다.
React Native JS LongTask 설명

활성화하면 SDK는 React Native JS 스레드의 인접 프레임 간격을 모니터링하고, 전체 프레임 간격이 longTaskThresholdMs보다 엄격히 클 때 LongTask를 보고합니다. 현재 버전은 JS 호출 스택을 수집하지 않습니다.

샘플링 설정

SDK 0.4.3부터 소수 백분율 샘플링을 지원합니다.

새 필드를 사용하는 것을 권장합니다. sessionSamplingRate: 12.5는 세션의 12.5%를 수집함을 의미하며, sessionSamplingRate: 1은 1%, 100은 전체 수집을 의미합니다.

동일 항목에 신규 필드와 기존 필드를 동시에 설정하면 신규 필드가 우선하며, 명시적으로 0으로 설정한 경우도 마찬가지입니다. 기존 필드는 [0,1]의 의미를 유지하므로 기존 값을 신규 필드에 그대로 복사하지 마세요. 오류 세션 샘플링은 일반 세션 샘플링에서 선택되지 않은 세션에 사용되며, 오류 발생 시 오류 발생 전 1분 범위의 데이터를 수집할 수 있습니다.

기존 필드는 SDK 0.4.3부터 폐기되었으며 호환성을 위해 유지됩니다. 업그레이드 후에는 실제 필요한 백분율에 따라 신규 필드를 설정하는 것을 권장합니다. 예를 들어 전체 수집 설정은 다음과 같이 마이그레이션합니다:

 const rumConfig: FTRUMConfig = {
   androidAppId: 'YOUR_ANDROID_APP_ID',
   iOSAppId: 'YOUR_IOS_APP_ID',
-  sampleRate: 1,
+  sessionSamplingRate: 100,
 };

Log, Trace, Session Replay 및 원격 구성 재정의 규칙에서도 해당 백분율 필드를 지원합니다.

RUM 사용자 데이터 추적

FTRUMConfig는 enableAutoTrackUserAction, enableAutoTrackError, enableNativeUserAction, enableNativeUserView, enableNativeUserResource 등의 설정을 통해 자동 수집을 구현할 수 있습니다. 수동 수집이 필요한 경우 다음 API를 사용할 수도 있습니다.

View

SDK 초기화 시 RUM 설정에서 enableNativeUserView를 설정하여 Native View 자동 수집을 활성화할 수 있습니다. React Native View는 React Native가 화면 내비게이션을 생성하기 위한 다양한 라이브러리를 제공하므로 기본적으로 수동 수집만 지원합니다. React Native View 자동 수집이 필요하면 아래 "React Native View 자동 수집"을 계속 읽어 보세요.

사용 방법

/**
 * view 로딩 시간, 단위 나노초.
 */
onCreateView(viewName: string, loadTime: number): Promise<void>;

/**
 * view 시작.
 */
startView(viewName: string, property?: object): Promise<void>;

/**
 * view 종료.
 */
stopView(property?: object): Promise<void>;

사용 예시

import { FTReactNativeRUM } from '@cloudcare/react-native-mobile';
FTReactNativeRUM.onCreateView('viewName', duration);

FTReactNativeRUM.startView('viewName', { 'custom.foo': 'something' });

FTReactNativeRUM.stopView({ 'custom.foo': 'something' });

현재 View의 로딩 시간 업데이트

SDK 0.4.3부터 지원합니다.

startView() 이후, stopView() 이전에 호출합니다:

await FTReactNativeRUM.updateViewLoadingTime(25_500_000); // 25.5 ms

duration은 비즈니스 로딩 시작/종료 경계로 계산한 소요 시간이며 단위는 나노초이고, 음수가 아닌 안전한 정수여야 합니다. 경과 시간은 단조 시계로 계산하는 것을 권장합니다. 밀리초 값은 1_000_000을 곱한 후 정수로 변환해야 합니다. 호출 시 현재 View의 로딩 시간이 대체되며, 0을 전달하면 지웁니다. 이 메서드는 현재 활성 View만 업데이트하며 다른 View를 지정하는 것은 지원하지 않습니다.

React Native View 자동 수집

SDK 0.4.3부터 선택적 내비게이션 플러그인을 제공합니다.

실제 사용하는 내비게이션 라이브러리에 맞춰 하나의 플러그인을 선택하고 메인 SDK와 동일한 버전을 유지하세요. 플러그인은 JavaScript와 타입 선언만 포함하며 네이티브 링크 설정을 추가하지 않습니다. 먼저 SDK와 RUM 초기화를 완료하고, 순수 React Native 페이지에서는 enableNativeUserView: false 설정을 권장합니다.

이전에 예제의 내비게이션 수집 파일을 복사했다면, 플러그인에서 동일한 이름의 클래스를 import하도록 변경하고 이전 수집 로직을 제거하여 중복 보고를 방지하세요. 동시에 하나의 자동 내비게이션 수집 방식만 사용하세요. 플러그인은 백그라운드 진입 시 네이티브와 연동하여 View를 종료하고, 포그라운드 복귀 시 현재 페이지를 다시 시작하며 이전 로딩 시간을 재사용하지 않습니다.

react-native-navigation
yarn add @cloudcare/mobile-react-native-navigation@0.4.3

이전 예제 파일에서 마이그레이션할 때 수집 클래스의 import 경로를 교체합니다:

- import { FTRumReactNativeNavigationTracking } from './FTRumReactNativeNavigationTracking';
+ import { FTRumReactNativeNavigationTracking } from '@cloudcare/mobile-react-native-navigation';

내비게이션 루트 페이지를 표시하기 전에 수집을 시작합니다:

import { FTRumReactNativeNavigationTracking } from '@cloudcare/mobile-react-native-navigation';
// SDK와 RUM 초기화 완료 후, Navigation.setRoot() 전에 호출합니다.
FTRumReactNativeNavigationTracking.startTracking();

내비게이션 통합을 제거하거나 SDK를 종료하기 전에 FTRumReactNativeNavigationTracking.stopTracking()을 호출합니다.

플러그인은 페이지 표시 및 사라짐 이벤트를 수집합니다. 로딩 시간은 componentWillAppear부터 componentDidAppear까지의 간격이며 단위는 나노초이고, 페이지의 모든 비동기 콘텐츠 로딩 완료를 의미하지 않습니다. 내비게이션 라이브러리가 will-appear 콜백을 제공하지 않거나, 시작점이 없거나 소요 시간이 양수가 아닌 경우에는 View만 수집하고 로딩 시간을 임의로 생성하지 않습니다.

react-navigation
yarn add @cloudcare/mobile-react-navigation@0.4.3

이전 예제 파일에서 마이그레이션할 때 수집 클래스의 import 경로를 교체하고, 내비게이션 라이브러리 import는 그대로 유지합니다:

- import { FTRumReactNavigationTracking } from './FTRumReactNavigationTracking';
+ import { FTRumReactNavigationTracking } from '@cloudcare/mobile-react-navigation';
import { createNativeStackNavigator } from '@react-navigation/native-stack';

라우트 모드는 일반 라우트, 중첩 내비게이션 및 Tab에 적합합니다. 컨테이너가 준비되면 현재 리프 라우트를 기록한 후 라우트 변경을 추적합니다. 이 모드는 로딩 시간을 수집하지 않습니다.

import { NavigationContainer, createNavigationContainerRef } from '@react-navigation/native';
import { FTRumReactNavigationTracking } from '@cloudcare/mobile-react-navigation';
const navigationRef = createNavigationContainerRef();

<NavigationContainer
  ref={navigationRef}
  onReady={() => FTRumReactNavigationTracking.startTrackingViews(navigationRef)}
>
  {/* 프로젝트의 내비게이션 컴포넌트 */}
</NavigationContainer>;

컨테이너를 언마운트하거나 SDK를 종료하기 전에 FTRumReactNavigationTracking.stopTrackingViews(navigationRef)를 호출합니다.

전환 모드는 @react-navigation/native-stack에 적합하며 라우트 모드와 둘 중 하나를 선택합니다. 페이지 전환을 담당하는 Stack에 설정합니다:

import { FTRumReactNavigationTracking } from '@cloudcare/mobile-react-navigation';
<Stack.Navigator screenListeners={FTRumReactNavigationTracking.StackListener}>
  {/* 프로젝트의 Stack.Screen */}
</Stack.Navigator>;

위의 Stack은 프로젝트에서 createNativeStackNavigator()로 생성한 인스턴스를 사용합니다. Stack을 언마운트하거나 SDK를 종료하기 전에 FTRumReactNavigationTracking.stopTrackingViews()를 호출합니다. 다시 마운트할 때는 StackListener를 다시 가져오고, 정리된 리스너 객체를 계속 사용하지 마세요.

로딩 시간은 관측된 focus부터 해당 열기 전환의 transitionEnd까지의 단조 시간 간격이며 단위는 나노초이고, 네트워크 또는 전체 콘텐츠 로딩 완료를 의미하지 않습니다. 새 페이지 인스턴스의 첫 표시에만 수집하며, 기존 페이지로 돌아가기, Tab 전환 및 포그라운드 복귀 시에는 타이머를 다시 시작하지 않습니다. 시작점이 없거나 소요 시간이 양수가 아니면 로딩 데이터를 추가하지 않습니다. 중첩 내비게이션의 각 계층에서 중복 등록하지 마세요.

Expo Router

Expo Router를 사용하는 경우 app/_layout.js 파일에 다음 메서드를 추가하여 데이터를 수집합니다.

import { useEffect } from 'react';
import { useSegments, usePathname, Slot } from 'expo-router';
import { FTReactNativeRUM } from '@cloudcare/react-native-mobile';
export default function Layout() {
  const pathname = usePathname();
  const segments = useSegments();
  const viewKey = segments.join('/');

  useEffect(() => {
    FTReactNativeRUM.startView(viewKey);
  }, [viewKey, pathname]);

  return <Slot />;
}

Action

startAction과 addAction의 사용 차이
  • startAction은 내부적으로 Action 소요 시간을 자동 계산합니다. 계산 중에는 가능한 한 주변에서 발생한 Resource, LongTask, Error 데이터와 연결하며, 100ms 빈번한 트리거 보호 기능이 있습니다. 사용자 작업 유형 데이터에 사용하는 것을 권장합니다.
  • 빈번하게 호출해야 하는 경우 addAction을 사용하세요. addAction으로 보고된 Action은 startAction과 충돌하지 않으며, 현재 Resource, LongTask, Error 데이터와도 연결되지 않습니다.

사용 방법

/**
 * RUM Action을 시작합니다.
 */
startAction(actionName: string, actionType: string, property?: object): Promise<void>;

/**
 * Action 이벤트를 추가합니다.
 */
addAction(actionName: string, actionType: string, property?: object): Promise<void>;

사용 예시

import { FTReactNativeRUM } from '@cloudcare/react-native-mobile';
FTReactNativeRUM.startAction('actionName', 'actionType', { 'custom.foo': 'something' });

FTReactNativeRUM.addAction('actionName', 'actionType', { 'custom.foo': 'something' });

Error

사용 방법

/**
 * 예외 캡처 및 로그 수집.
 */
addError(stack: string, message: string, property?: object): Promise<void>;

/**
 * 오류 유형을 지정한 예외 캡처 및 로그 수집.
 */
addErrorWithType(type: string, stack: string, message: string, property?: object): Promise<void>;

사용 예시

import { FTReactNativeRUM } from '@cloudcare/react-native-mobile';
FTReactNativeRUM.addError('error stack', 'error message', { 'custom.foo': 'something' });

FTReactNativeRUM.addErrorWithType('custom_error', 'error stack', 'error message', {
  'custom.foo': 'something',
});

Resource

WebSocket 핸드셰이크 자동 수집

SDK 0.4.3부터 iOS React Native WebSocket 핸드셰이크 수집을 지원합니다.

RUM 초기화 시 enableIOSWebSocketResource: true를 설정하고, 초기화 완료 후 연결을 생성하세요. 이 스위치는 enableNativeUserResource와 독립적입니다. Android는 네이티브 SDK를 사용하여 자동 수집하며, enableNativeUserResource를 활성화하고 Android ft-plugin 설정을 완료해야 합니다.

수집 범위는 연결 수립 핸드셰이크이며, 연결 수립 후 메시지 송수신은 포함하지 않고 전체 연결 수명 시간을 Resource 소요 시간으로 사용하지도 않습니다. iOS 소요 시간은 WebSocket 생성자 호출의 수집 경계부터 최초 핸드셰이크 성공 또는 실패 최종 상태까지 계산하며, 수집 시작/종료 시간을 네이티브에 전달하여 이후 브리지 처리 지연이 결과에 영향을 주지 않도록 합니다. 이 경로는 DNS, TCP, TLS, 첫 바이트 등의 단계별 소요 시간을 제공하지 않으며, 실제 HTTP 응답 정보가 없을 때 상태 코드나 응답 헤더를 위조하지 않습니다. Metro, Inspector, HMR 및 디버거 WebSocket 요청은 필터링됩니다.

iOS WebSocket에 Trace 요청 헤더를 자동 주입해야 하는 경우 FTTraceConfig.enableNativeAutoTrace도 활성화해야 합니다. Trace만 활성화하고 enableIOSWebSocketResource를 활성화하지 않은 경우에는 이 경로를 통해 자동 주입되지 않습니다.

수동 수집 사용 방법

/**
 * 리소스 요청을 시작합니다.
 */
startResource(key: string, property?: object): Promise<void>;

/**
 * 리소스 요청을 종료합니다.
 */
stopResource(key: string, property?: object): Promise<void>;

/**
 * 리소스 데이터 메트릭을 전송합니다.
 */
addResource(key: string, resource: FTRUMResource, metrics?: FTRUMResourceMetrics): Promise<void>;

사용 예시

import { FTReactNativeRUM } from '@cloudcare/react-native-mobile';
async function getHttp(url: string) {
  const key = Utils.getUUID();
  FTReactNativeRUM.startResource(key);
  const fetchOptions = {
    method: 'GET',
    headers: {
      Accept: 'application/json',
      'Content-Type': 'application/json',
    },
  };
  let res: Response;
  try {
    res = await fetch(url, fetchOptions);
  } finally {
    const resource: FTRUMResource = {
      url: url,
      httpMethod: fetchOptions.method,
      requestHeader: fetchOptions.headers,
    };
    if (res) {
      resource.responseHeader = res.headers;
      resource.resourceStatus = res.status;
      resource.responseBody = await res.text();
    }
    FTReactNativeRUM.stopResource(key);
    FTReactNativeRUM.addResource(key, resource);
  }
}

Action 사용자 정의 규칙에 대한 자세한 내용은 데이터 수집 사용자 정의 규칙을 참고하세요.

문서 평가

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