콘텐츠로 이동

RUM 설정

이 문서에서는 Cocos Creator RUM 초기화 매개변수, 자동 수집 범위 및 Native 모니터링 설정을 설명합니다.

RUM 초기화

설명

이 페이지의 코드 예시에서 ...는 sdk 기본 설정(예: datakitUrl)이 생략되었음을 의미합니다. 먼저 SDK 초기화를 참조하여 공통 설정을 완료하세요. 이 페이지에서는 RUM 관련 설정만 설명합니다.

guanceSdk.start({
  ...,
  rum: {
    androidAppId: 'android-rum-app-id',
    iosAppId: 'ios-rum-app-id',
    sampleRate: 1,
    sessionOnErrorSampleRate: 0,
    enableNativeCrash: true,
    enableNativeAnr: true,
    globalContext: {
      game_mode: 'ranked',
    },
  },
});
필드 타입 필수 설명
androidAppId string Android 필수 Android RUM 애플리케이션 ID
iosAppId string iOS 필수 iOS RUM 애플리케이션 ID
sampleRate number 아니요 세션 샘플링 비율, 범위 0–1
sessionOnErrorSampleRate number 아니요 일반 샘플링에 포함되지 않은 오류 세션의 추가 샘플링 비율, 범위 0–1
enableNativeUserAction boolean 아니요 네이티브 UI Action 수집 여부
enableNativeUserView boolean 아니요 네이티브 페이지 View 수집 여부
enableNativeUserResource boolean 아니요 네이티브 네트워크 Resource 자동 수집 여부
enableNativeCrash boolean 아니요 Native Crash 수집 여부
enableNativeAnr boolean 아니요 Native ANR 수집 여부
enableNativeUiBlock boolean 아니요 Native UI 멈춤 또는 Freeze 수집 여부
nativeUiBlockDurationMs number 아니요 Native UI 멈춤 임계값(밀리초). enableNativeUiBlock이 활성화된 경우에만 적용
errorMonitorType number 아니요 오류 이벤트에 추가되는 모니터링 항목의 Native SDK 비트마스크
deviceMetricsMonitorType number 아니요 View 디바이스 메트릭 모니터링 항목의 Native SDK 비트마스크
detectFrequency normal / frequent / rare 아니요 디바이스 메트릭 감지 빈도
globalContext Record<string, string> 아니요 RUM 데이터에 추가되는 정적 글로벌 태그

Android 런타임에서는 androidAppId가 필요하며, iOS 런타임에서는 iosAppId가 필요합니다. 동일한 크로스 플랫폼 TypeScript 설정에서 두 값을 모두 전달할 수 있습니다.

errorMonitorType와 deviceMetricsMonitorType는 숫자 비트마스크를 직접 전달하며, 현재 Native SDK 버전의 정의와 일치해야 합니다. 구체적인 조합은 Android RUM 설정 및 iOS RUM 설정을 참조하세요.

Cocos 자동 수집

자동 수집은 guanceSdk.start()의 autoTrack 설정으로 활성화되며, 모든 옵션은 기본적으로 비활성화되어 있습니다.

guanceSdk.start({
  ...,
  rum: {
    androidAppId: 'android-rum-app-id',
    iosAppId: 'ios-rum-app-id',
  },
  logger: {
    enableCustomLog: true,
  },
  trace: {
    traceType: 'ddTrace',
  },
  autoTrack: {
    scenes: true,
    actions: true,
    errors: true,
    console: false,
    network: true,
  },
});
필드 수집 동작 의존성
scenes 씬 시작 시 이전 View를 종료하고 씬 이름으로 새 View 시작 RUM
actions 전역 TOUCH_END를 Action으로 변환. 이벤트 대상 노드 이름을 우선 사용하고 터치 좌표를 첨부 RUM
errors 처리되지 않은 JavaScript Error 및 Promise rejection 감지 RUM. 런타임에 globalThis.addEventListener와 globalThis.removeEventListener가 모두 제공되어야 함
console console.log/info/warn/error를 래핑하여 커스텀 로그로 변환 Log. 자세한 내용은 Log 설정 참조
network fetch와 XMLHttpRequest를 래핑하여 Resource를 수집하고 Trace Header를 주입 RUM. Trace Header를 사용하려면 Trace 초기화도 필요

guanceSdk.shutdown()을 호출하면 Console, Fetch, XHR 및 씬/터치 리스너가 복원됩니다.

JavaScript 오류 자동 수집의 런타임 전제 조건

autoTrack.errors를 활성화하면 SDK는 전역 error 및 unhandledrejection 이벤트를 통해 처리되지 않은 JavaScript 예외와 처리되지 않은 Promise rejection을 수집합니다. 현재 Cocos JavaScript 런타임에 globalThis.addEventListener와 globalThis.removeEventListener가 모두 제공되는 경우에만 SDK가 이 두 리스너를 등록합니다.

런타임이 위 API를 제공하지 않으면 errors: true는 오류 리스너를 설치하지 않으며 초기화 오류도 발생시키지 않습니다. 비즈니스 코드에서 이미 처리된 예외는 전역 이벤트를 트리거하지 않으므로 guanceSdk.rum.addError()를 호출하여 수동으로 보고해야 합니다.

중복 수집 방지

autoTrack.actions와 enableNativeUserAction, autoTrack.network와 enableNativeUserResource는 동일한 상호작용이나 요청을 중복 수집할 수 있습니다. 실제 요청 스택에 따라 Cocos 레이어 또는 Native 레이어 중 하나의 자동 수집 방식을 선택하고, 테스트 환경에서 중복 데이터가 발생하는지 확인하세요.

Android에서는 autoTrack.network를 활성화하고 네이티브 setEnableHttpURLConnectionResource(false)를 유지하여 동일한 XHR이 두 레이어에서 수집되지 않도록 권장합니다. Android 네트워크 수집 권장사항을 참조하세요.

RUM 수동 계측

자동 수집이 커스텀 페이지, 비즈니스 작업, 처리된 예외, 커스텀 네트워크 스택 등의 시나리오를 다루지 못하는 경우 guanceSdk.rum을 통해 수동으로 보고할 수 있습니다. 독립 실행 모드에서는 먼저 guanceSdk.start()에서 rum을 초기화해야 하며, 네이티브 호스트 하이브리드 모드에서는 네이티브 측에서 RUM을 먼저 초기화해야 합니다.

속성 유형

다음 메서드의 attributes는 모두 선택적 매개변수이며, JSON 직렬화 가능한 문자열, 숫자, 불리언, null, 배열 및 객체를 지원합니다.

Action

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

즉시 Action 추가:

guanceSdk.rum.addAction('Use Skill', 'click', {
  skill_id: 'fireball',
});

Native SDK가 연관 수명 주기를 관리하는 Action 시작:

guanceSdk.rum.startAction('Matchmaking', 'custom', {
  queue: 'ranked',
});

메서드 시그니처:

guanceSdk.rum.addAction(
  name: string,
  type?: string,
  attributes?: FTAttributes,
): void

guanceSdk.rum.startAction(
  name: string,
  type?: string,
  attributes?: FTAttributes,
): void

name과 type은 비어 있을 수 없으며, type의 기본값은 click입니다.

autoTrack.actions를 활성화하면 전역 터치 종료 이벤트가 자동으로 Action을 생성합니다. 동일한 터치에 대해 수동 Action API를 동시에 호출하지 마세요.

View

View 시작:

guanceSdk.rum.startView('Battle', {
  map_id: 'map-001',
});

현재 View 종료:

guanceSdk.rum.stopView({
  battle_result: 'victory',
});

메서드 시그니처:

guanceSdk.rum.startView(name: string, attributes?: FTAttributes): void
guanceSdk.rum.stopView(attributes?: FTAttributes): void

name은 비어 있을 수 없습니다. 애플리케이션은 View가 쌍으로 종료되도록 보장해야 하며, 새 View를 시작하기 전에 이전 View를 종료해야 합니다.

autoTrack.scenes를 활성화하면 SDK가 씬 View를 자동으로 관리합니다. 동일한 씬에 대해 View API를 수동으로 다시 호출하지 마세요. 중복되거나 중첩된 오류가 발생할 수 있습니다.

Error

try {
  startBattle();
} catch (error) {
  const exception = error instanceof Error
    ? error
    : new Error(String(error));

  guanceSdk.rum.addError(
    exception.message,
    exception.stack || '',
    'game_logic_error',
    'run',
    {
      scene: 'Battle',
    },
  );
}

메서드 시그니처:

guanceSdk.rum.addError(
  message: string,
  stack: string,
  type?: string,
  state?: 'run' | 'startup' | 'unknown',
  attributes?: FTAttributes,
): void
매개변수 기본값 설명
message 없음 오류 메시지
stack 없음 오류 스택
type cocos_error 비즈니스 오류 유형
state run 발생 단계: 실행(run), 시작(startup) 또는 알 수 없음(unknown)
attributes 없음 현재 오류에 첨부되는 속성

autoTrack.errors를 활성화하면 처리되지 않은 JavaScript Error와 Promise rejection이 자동으로 보고됩니다. 비즈니스 코드에서 이미 처리되어 수동으로 보고된 예외는 전역 리스너가 다시 캡처하지 않습니다.

LongTask

guanceSdk.rum.addLongTask(
  'GenerateWorld',
  850 * 1_000_000,
  {
    map_size: 'large',
  },
);

메서드 시그니처:

guanceSdk.rum.addLongTask(
  stack: string,
  durationNs: number,
  attributes?: FTAttributes,
): void

durationNs의 단위는 나노초입니다. Cocos JavaScript 레이어는 현재 LongTask를 자동으로 인식하지 않으므로, 비즈니스 코드에서 시간이 오래 걸리는 작업이 종료된 후 호출해야 합니다.

Resource

전체 Resource는 세 단계로 구성됩니다.

  1. startResource(): 타이밍 시작
  2. stopResource(): 타이밍 종료
  3. addResource(): 요청 내용 및 선택적 성능 메트릭 보충
export async function requestMatch(): Promise<void> {
  const key = `match-${Date.now()}`;
  const url = 'https://api.example.com/match';
  const started = Date.now() * 1_000_000;

  guanceSdk.rum.startResource(key, {
    request_source: 'matchmaking',
  });

  try {
    const traceHeaders = guanceSdk.trace.getHeaders(url, key);
    const response = await fetch(url, {
      headers: traceHeaders,
    });
    const ended = Date.now() * 1_000_000;

    guanceSdk.rum.stopResource(key);
    guanceSdk.rum.addResource(
      key,
      {
        url,
        httpMethod: 'GET',
        requestHeaders: traceHeaders,
        statusCode: response.status,
        responseContentType: response.headers.get('content-type') || undefined,
      },
      {
        fetchStartTime: started,
        responseStartTime: ended,
        responseEndTime: ended,
      },
    );
  } catch (error) {
    guanceSdk.rum.stopResource(key);
    const exception = error instanceof Error
      ? error
      : new Error(String(error));
    guanceSdk.rum.addError(
      exception.message,
      exception.stack || '',
      'network_error',
    );
  }
}

메서드 시그니처:

guanceSdk.rum.startResource(
  key: string,
  attributes?: FTAttributes,
): void

guanceSdk.rum.stopResource(
  key: string,
  attributes?: FTAttributes,
): void

guanceSdk.rum.addResource(
  key: string,
  content: FTResourceContent,
  metrics?: FTResourceMetrics,
): void

Resource 내용

필드 타입 필수 설명
url string 예 전체 요청 URL
httpMethod string 예 HTTP 메서드
requestHeaders Record<string, string> 아니요 요청 헤더
responseHeaders Record<string, string> 아니요 응답 헤더
responseBody string 아니요 응답 Body. 민감한 데이터가 포함될 수 있으므로 주의하여 수집
statusCode number 아니요 HTTP 상태 코드
responseContentType string 아니요 응답 Content-Type
responseContentEncoding string 아니요 응답 Content-Encoding

Resource 성능 메트릭

모든 시간 필드의 단위는 나노초입니다.

필드 설명
fetchStartTime 요청 시작 시간
tcpStartTime TCP 연결 시작 시간
tcpEndTime TCP 연결 종료 시간
dnsStartTime DNS 조회 시작 시간
dnsEndTime DNS 조회 종료 시간
responseStartTime 응답 시작 시간
responseEndTime 응답 종료 시간
sslStartTime TLS 연결 시작 시간
sslEndTime TLS 연결 종료 시간

key는 세 가지 RUM 메서드와 guanceSdk.trace.getHeaders()에서 동일해야 합니다.

자동과 수동 중 하나만 선택

autoTrack.network를 활성화하면 fetch와 XMLHttpRequest가 이미 자동 수집됩니다. 동일한 요청에 대해 위의 수동 Resource 프로세스를 다시 실행하지 마세요.

업로드 동작

현재 Cocos API는 수동 Flush를 노출하지 않습니다. 이벤트가 Native SDK에 기록된 후 Native SDK가 자체 캐시 및 업로드 전략에 따라 전송합니다. 애플리케이션 종료 전에 guanceSdk.shutdown()으로 강제 업로드하는 방식에 의존하지 마세요.

Cocos와 Native 데이터 경계

  • scenes, actions, errors, network는 Cocos JavaScript 레이어의 동작을 수집합니다.
  • enableNative* 옵션은 Android/iOS 네이티브 컨테이너의 동작을 수집합니다.
  • Native Crash, ANR, UI Block 및 디바이스 메트릭은 하위 Android/iOS SDK에서 생성됩니다.
  • Cocos Long Task는 현재 자동 수집되지 않으므로 수동 API를 호출해야 합니다.
  • 자동 네트워크 수집은 현재 런타임에서 실제로 제공하는 fetch와 XMLHttpRequest만 대상으로 합니다.

네이티브 앱이 일부 페이지에서만 Cocos를 사용하는 경우, 네이티브 SDK 요구 사항에 따라 초기화를 완료하고 enterCocos()와 leaveCocos()를 통해 Cocos 페이지가 표시되는 동안 View 수명 주기를 전환합니다. 전체 설정은 네이티브와 Cocos 하이브리드 개발을 참조하세요.

샘플링 설명

sampleRate와 sessionOnErrorSampleRate는 유한한 숫자여야 하며 0–1 범위에 있어야 합니다. 범위를 벗어나면 TypeScript 레이어가 초기화 단계에서 RangeError를 발생시킵니다. 값을 전달하지 않으면 해당 Native SDK의 기본값이 사용됩니다.

관련 주제

문서 평가

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