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을 초기화해야 하며, 네이티브 호스트 Hybrid 모드에서는 네이티브 측에서 먼저 RUM을 초기화해야 합니다.

속성 유형¶

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

Action¶

즉시 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`	발생 단계: 실행, 시작 또는 알 수 없음
`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는 세 단계로 구성됩니다:

startResource(): 타이밍 시작
stopResource(): 타이밍 종료
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의 기본값을 사용합니다.

RUM 설정¶

RUM 초기화¶

Cocos 자동 수집¶

RUM 수동 계측¶

속성 유형¶

Action¶

View¶

Error¶

LongTask¶

Resource¶

Resource 내용¶

Resource 성능 메트릭¶

업로드 동작¶

Cocos와 Native 데이터 경계¶

샘플링 설명¶

관련 주제¶

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

RUM 설정¶

RUM 초기화¶

Cocos 자동 수집¶

RUM 수동 계측¶

속성 유형¶

Action¶

View¶

Error¶

LongTask¶

Resource¶

Resource 내용¶

Resource 성능 메트릭¶

업로드 동작¶

Cocos와 Native 데이터 경계¶

샘플링 설명¶

관련 주제¶

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

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