WeChat Mini Program의 로그 분석

이 문서는 WeChat Mini Program AR 환경에서 로그를 획득하고 분석하는 전체 흐름을 소개합니다.

WeChat Mini Program vConsole 사용

WeChat Mini Program AR은 실제 기기에서만 실행 및 디버깅할 수 있으므로, vConsole을 사용해 실시간 출력을 관찰하는 것이 디버깅의 핵심입니다. 기본 사용법은 WeChat Mini Program 공식 문서를 참고하세요.

실제 기기 디버깅 중 vConsole 활성화 방법

AR 화면에서 오른쪽 위 첫 번째 버튼 클릭 > 아래쪽 툴바의 개발 디버깅 클릭 > 디버깅 열기 클릭 > 팝업 창에서 확인을 클릭하여 Mini Program을 재시작합니다.

디버깅 열기

다시 연 후 적용

그 후 화면에는 vConsole 플로팅 버튼이 계속 표시됩니다.

vConsole 버튼

vConsole 버튼을 클릭하면 현재 실행 중인 모든 로그를 볼 수 있습니다.

Mini Program 로그

로그 출처 구분 방법

로그 출처는 일반적으로 다음과 같이 나눌 수 있습니다.

WeChat Mini Program 시스템 로그: 일반적으로 페이지 라우팅 전환이나 컴포넌트 lifecycle 변화 시 트리거되며, vConsole에서는 파란색 글자로 표시됩니다.
xr-frame 로그: 공식 렌더링 프레임워크가 출력하며, 로그 내용은 [xr-frame]으로 시작합니다.
사용자 정의 로그: 개발자가 console.log() 등 표준 인터페이스를 통해 출력합니다.
Mini Program 프레임워크 오류 로그: WeChat 하위 계층에서 던지며, 내용은 MiniProgramError로 시작합니다.
Mega Mini Program 플러그인 로그: Mega Mini Program 플러그인 내부에서 출력하며, 로그 내용은 [MegaTracker]처럼 대괄호로 감싼 클래스명으로 시작합니다. 현재는 주로 exception을 포착할 때 출력됩니다.
예 1:

첫 번째 파란색 부분은 시스템 로그이며 페이지 라우팅 및 로딩 상태를 보여줍니다.

두 번째 부분은 [xr-frame]으로 시작하며 렌더링 프레임워크의 lifecycle 정보를 보여줍니다.

세 번째 부분은 개발자 사용자 정의 출력입니다.
예 2:

[MegaTracker], [EasyARSession(xrframe)] 등의 클래스명으로 시작하는 로그가 나타납니다. 이는 Mega 플러그인이 런타임 exception을 포착했다는 의미입니다.
예 3:

MiniProgramError 안에 WAXRFrameRenderContext.js 문구가 나타났으며, xr-frame 관련 인터페이스 또는 컴포넌트 설정 사용에 문제가 있음을 설명합니다.
예 4:

이 로그는 mega 플러그인의 onCloudLocalization 메서드 실행 중 exception이 발생하여 Mini Program 프레임워크가 오류를 던졌음을 설명합니다.

Mega Mini Program 플러그인의 로그 형식

dumpLog(signal) 메서드로 내보낸 로그는 |로 구분되며, 내용은 순서대로 다음과 같습니다.

타임스탬프: ISO 8601 표준 형식으로, 로그를 출력할 때의 시스템 시간을 나타냅니다.
로그 레벨: Info, Warning, Error, FatalError 포함.
클래스명: 대괄호로 감쌉니다.
상세 정보: 구체적인 로그 설명.
Caller: 일반적으로 Unspecified이며 자연 실행 과정을 의미합니다. 사용자가 인터페이스를 호출하여 발생한 exception이면 User로 표시됩니다.
실행 단계: Unspecified로 표시되면 주의할 필요가 없음을 의미하며, 다른 필드가 표시되면 해당 exception이 특정 실행 단계에서 발생했음을 의미합니다.

Mini Program 로그

로그 기록 및 전달 방법

로그 획득 및 내보내기 방안을 소개합니다.

vConsole 로그 내보내기

로그가 출력된 위치의 오른쪽 복사 버튼을 클릭하여 내보냅니다.

Mega Mini Program 플러그인 dump log 인터페이스

dumpLog(signal) 인터페이스를 호출하여 로그 내보내기 흐름을 제어합니다.

true 전달: 기록을 시작합니다.
false 전달: 기록을 중지하고 생성된 **파일 임시 경로 (tempFilePath)**를 반환합니다.

일반적으로 기록 로직을 UI 버튼과 바인딩하는 것을 권장합니다. 기록을 시작할 때는 wx.showToast() 메서드로 기록 시작을 안내하고, 기록이 끝날 때는 wx.shareFileMessage() 메서드로 기록된 파일을 WeChat 채팅을 통해 전달합니다.

/**
 * Session 기록 로직 처리
 * @param signal true는 기록 시작, false는 기록 종료 및 전달을 의미합니다
 */
dumpLog(signal: boolean): void {
  // 인터페이스를 호출하여 경로 가져오기
  const logPath = session.dumpLog(signal);
  // signal이 true이면 인터페이스가 빈 문자열을 반환하여 기록 중임을 나타냅니다
  if (logPath.length == 0) {
      wx.showToast({
          title: '开始记录日志',
          icon: 'success',
          duration: 2000
      });
      return;
  }
  // signal이 false이면 반환된 파일 경로를 처리합니다
  wx.shareFileMessage({
      filePath: logPath,
      success() {
          wx.showToast({
              title: '日志转发成功',
              icon: 'success',
              duration: 2000
          });
      },
      fail() {
          wx.showToast({
              title: '日志转发失败',
              icon: 'error',
              duration: 2000
          });
      }
  })
}

이 예시는 xr-frame 컴포넌트에서 session.dumpLog() 메서드를 사용해 로그 파일을 기록하고 전달하며, 그에 맞는 Toast 안내를 제공하는 방법을 보여줍니다.

중요

Mega 사용 중 프로그램 exception이 아니라 localization 또는 tracking 관련 문제가 발생한 경우, 로그 외에도 반드시 당시의 화면 녹화 파일과 session dump 파일을 제공해 주세요. 순수 로그 파일은 부가 참고만 제공할 수 있으며, 화면 녹화와 dump 데이터가 문제 해결의 핵심 근거입니다.

Table of Contents