Log 설정¶

이 문서에서는 Cocos Creator 커스텀 로그, Console 자동 수집, RUM 연동 설정에 대해 설명합니다.

Log 초기화¶

설명

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

guanceSdk.start({
  ...,
  logger: {
    sampleRate: 1,
    enableCustomLog: true,
    enableLinkRumData: true,
    printCustomLogToConsole: false,
    discardStrategy: 'discard',
    logLevelFilters: ['info', 'warning', 'error', 'critical', 'ok'],
    logCacheLimitCount: 5000,
    globalContext: {
      game_channel: 'app-store',
    },
  },
});

필드	유형	필수	설명
`sampleRate`	`number`	아니요	로그 샘플링 비율, 범위 `0–1`
`enableLinkRumData`	`boolean`	아니요	로그에 현재 RUM Session, View 등의 컨텍스트를 연결할지 여부
`enableCustomLog`	`boolean`	아니요	Cocos API를 통해 커스텀 로그를 작성할지 여부
`printCustomLogToConsole`	`boolean`	아니요	커스텀 로그를 네이티브 콘솔에도 함께 출력할지 여부
`discardStrategy`	`discard` / `discardOldest`	아니요	캐시 제한에 도달하면 새 데이터 또는 가장 오래된 데이터를 폐기하는 방식
`logLevelFilters`	`string[]`	아니요	수집이 허용된 로그 레벨
`logCacheLimitCount`	`number`	아니요	Native SDK 로컬 로그 캐시 항목 수 상한
`globalContext`	`Record<string, string>`	아니요	모든 로그에 추가되는 정적 태그

sampleRate가 0–1 범위를 벗어나면 초기화 시 RangeError가 발생합니다. 전달되지 않은 필드는 해당 Native SDK 기본값을 사용합니다.

Logger 로그 출력¶

guanceSdk.logger.log()를 사용하려면 독립 실행 모드의 logger 설정에서 enableCustomLog: true를 활성화해야 합니다. 네이티브 호스트 Hybrid 모드에서는 네이티브 측에서 커스텀 로그를 활성화해야 합니다.

guanceSdk.logger.log(
  'battle started',
  'info',
  {
    battle_id: 'battle-001',
    player_count: 10,
  },
);

메서드 시그니처:

guanceSdk.logger.log(
  content: string,
  level?: string,
  attributes?: FTAttributes,
): void

level의 기본값은 info입니다. Android와 iOS의 동작을 일관되게 유지하려면 다음 레벨을 사용하는 것이 좋습니다.

레벨	설명
`info`	정보
`warning`	경고
`error`	오류
`critical`	치명적
`ok`	복구

TypeScript 타입은 사용자 지정 문자열을 허용하지만, iOS Bridge는 알 수 없는 레벨을 info로 변환하므로 크로스 플랫폼 프로젝트는 사용자 지정 레벨에 의존해서는 안 됩니다.

Console 자동 수집¶

guanceSdk.start({
  ...,
  logger: {
    enableCustomLog: true,
    enableLinkRumData: true,
  },
  autoTrack: {
    console: true,
  },
});

활성화하면 다음 메서드를 래핑하고 원래 콘솔 출력을 유지하면서 Log를 기록합니다.

Console 메서드	로그 레벨
`console.log`	`info`
`console.info`	`info`
`console.warn`	`warning`
`console.error`	`error`

객체 인자는 우선 JSON.stringify()로 텍스트로 변환되며, 직렬화할 수 없으면 String()을 사용합니다.

수집 범위

console: true를 사용하면 디버그 정보, 계정, 토큰 또는 비즈니스 객체가 수집될 수 있습니다. 프로덕션 환경에서는 먼저 Console 내용을 검토하고, 필요한 경우 기능을 끈 상태로 유지한 뒤 필터링된 guanceSdk.logger.log()만 사용하세요.

guanceSdk.shutdown()을 호출하면 SDK가 원래 Console 메서드를 복원합니다.

RUM 연동¶

로그와 현재 RUM View 간의 연동을 설정하려면 다음 조건을 모두 충족해야 합니다.

RUM이 초기화되어 있어야 합니다.
현재 유효한 View가 있어야 합니다.
enableLinkRumData가 true여야 합니다.

로그가 첫 번째 View보다 먼저 생성되었거나 RUM이 샘플링 대상에 포함되지 않은 경우 연동 필드가 비어 있을 수 있습니다.

속성과 캐시¶

globalContext는 모든 로그가 공유하는 문자열 태그에 적합합니다.
attributes는 단일 로그에 적합하며, 문자열, 숫자, 불리언, 배열, JSON 객체를 사용할 수 있습니다.
현재 Cocos API는 수동 Flush를 제공하지 않습니다. 캐시, 배치 및 업로드 시점은 Native SDK가 관리합니다.
로그 내용과 속성에 비밀번호, 토큰 또는 전체 개인 민감 정보가 포함되어서는 안 됩니다. 자세한 내용은 데이터 및 개인정보 보호를 참조하세요.