콘텐츠로 이동

SourceMap 구성


Sourcemap(소스 코드 매핑)은 프로덕션 환경의 압축된 코드를 원본 소스 코드로 매핑하는 데 사용됩니다. RUM은 해당 심볼 테이블 파일을 zip으로 압축하여 업로드하는 방식으로 이러한 소스 코드 파일 정보 매핑을 지원하며, 이를 통해 전송된 error 메저먼트 데이터를 자동으로 변환할 수 있습니다.

Zip 패키징 방법

webpack으로 난독화 및 압축된 js 파일에서 생성된 .map 파일을 zip으로 압축하여 패키징할 때, 압축 패키지 압축 해제 후 파일 경로가 error_stack의 URL 경로와 반드시 일치해야 합니다. 다음과 같은 error_stack이 있다고 가정합니다.

ReferenceError
  at a.hideDetail @ http://localhost:8080/static/js/app.7fb548e3d065d1f48f74.js:1:1037
  at a.showDetail @ http://localhost:8080/static/js/app.7fb548e3d065d1f48f74.js:1:986
  at <anonymous> @ http://localhost:8080/static/js/app.7fb548e3d065d1f48f74.js:1:1174

변환해야 할 경로는 /static/js/app.7fb548e3d065d1f48f74.js이며, 이에 대응하는 sourcemap 경로는 /static/js/app.7fb548e3d065d1f48f74.js.map입니다. 그러면 해당 압축 패키지의 압축 해제 후 디렉터리 구조는 다음과 같습니다.

sourcemap.zip
└──static/
    └── js
    └── app.7fb548e3d065d1f48f74.js.map

변환 후의 error_stack_source:

ReferenceError
  at a.hideDetail @ webpack:///src/components/header/header.vue:94:0
  at a.showDetail @ webpack:///src/components/header/header.vue:91:0
  at <anonymous> @ webpack:///src/components/header/header.vue:101:0

Web과 패키징 방식이 기본적으로 동일합니다.

Android에는 현재 두 가지 유형의 sourcemap 파일이 있습니다. 하나는 Java 바이트코드가 R8/Proguard로 압축·난독화된 후 생성되는 mapping 파일이고, 다른 하나는 C/C++ 네이티브 코드 컴파일 시 심볼 테이블과 디버그 정보가 제거되지 않은(unstripped) .so 파일입니다. Android 앱에 이 두 가지 sourcemap 파일이 모두 포함된 경우 패키징할 때 두 파일을 모두 zip 패키지에 포함해야 합니다. zip 패키지 압축 해제 후 디렉터리 구조는 다음과 유사합니다.

sourcemap.zip
├── mapping.txt
├── armeabi-v7a/
│   ├── libgameengine.so
│   ├── libothercode.so
│   └── libvideocodec.so
├── arm64-v8a/
│   ├── libgameengine.so
│   ├── libothercode.so
│   └── libvideocodec.so
├── x86/
│   ├── libgameengine.so
│   ├── libothercode.so
│   └── libvideocodec.so
└── x86_64/
    ├── libgameengine.so
    ├── libothercode.so
    └── libvideocodec.so

기본적으로 mapping 파일은 <프로젝트 폴더>/<Module>/build/outputs/mapping/<build-type>/에 있으며, CMake로 프로젝트를 컴파일할 때 .so 파일은 <프로젝트 폴더>/<Module>/build/intermediates/cmake/debug/obj/에, NDK로 컴파일할 때는 <프로젝트 폴더>/<Module>/build/intermediates/ndk/debug/obj/(debug 컴파일) 또는 <프로젝트 폴더>/<Module>/build/intermediates/ndk/release/obj/(release 컴파일)에 있습니다.

변환 효과는 다음과 같습니다.

변환 전 error_stack:

java.lang.ArithmeticException: divide by zero
    at prof.wang.activity.TeamInvitationActivity.o0(Unknown Source:1)
    at prof.wang.activity.TeamInvitationActivity.k0(Unknown Source:0)
    at j9.f7.run(Unknown Source:0)
    at java.lang.Thread.run(Thread.java:1012)

변환 후 error_stack_source:

java.lang.ArithmeticException: divide by zero
at prof.wang.activity.TeamInvitationActivity.onClick$lambda-0(TeamInvitationActivity.java:1)
at java.lang.Thread.run(Thread.java:1012)

변환 전 error_stack:

backtrace:
#00 pc 00000000000057fc  /data/app/~~Taci3mQyw7W7iWT7Jxo-ag==/com.ft-Q8m2flQFG1MbGImPiuAZmQ==/lib/arm64/libft_native_exp_lib.so (xc_test_call_4+12)
#01 pc 00000000000058a4  /data/app/~~Taci3mQyw7W7iWT7Jxo-ag==/com.ft-Q8m2flQFG1MbGImPiuAZmQ==/lib/arm64/libft_native_exp_lib.so (xc_test_call_3+8)
#02 pc 00000000000058b4  /data/app/~~Taci3mQyw7W7iWT7Jxo-ag==/com.ft-Q8m2flQFG1MbGImPiuAZmQ==/lib/arm64/libft_native_exp_lib.so (xc_test_call_2+12)
#03 pc 00000000000058c4  /data/app/~~Taci3mQyw7W7iWT7Jxo-ag==/com.ft-Q8m2flQFG1MbGImPiuAZmQ==/lib/arm64/libft_native_exp_lib.so (xc_test_call_1+12)
#04 pc 0000000000005938  /data/app/~~Taci3mQyw7W7iWT7Jxo-ag==/com.ft-Q8m2flQFG1MbGImPiuAZmQ==/lib/arm64/libft_native_exp_lib.so (xc_test_crash+112)
...

변환 후 error_stack_source:

backtrace:

Abort message: 'abort message for ftNative internal testing'
#00 0x00000000000057fc /data/app/~~Taci3mQyw7W7iWT7Jxo-ag==/com.ft-Q8m2flQFG1MbGImPiuAZmQ==/lib/arm64/libft_native_exp_lib.so (xc_test_call_4+12)
xc_test_call_4
/Users/Brandon/Documents/workplace/working/StudioPlace/xCrash/xcrash_lib/src/main/cpp/xcrash/xc_test.c:65:9
#01 0x00000000000058a4 /data/app/~~Taci3mQyw7W7iWT7Jxo-ag==/com.ft-Q8m2flQFG1MbGImPiuAZmQ==/lib/arm64/libft_native_exp_lib.so (xc_test_call_3+8)
xc_test_call_3
/Users/Brandon/Documents/workplace/working/StudioPlace/xCrash/xcrash_lib/src/main/cpp/xcrash/xc_test.c:73:13
#02 0x00000000000058b4 /data/app/~~Taci3mQyw7W7iWT7Jxo-ag==/com.ft-Q8m2flQFG1MbGImPiuAZmQ==/lib/arm64/libft_native_exp_lib.so (xc_test_call_2+12)
xc_test_call_2
/Users/Brandon/Documents/workplace/working/StudioPlace/xCrash/xcrash_lib/src/main/cpp/xcrash/xc_test.c:79:13
#03 0x00000000000058c4 /data/app/~~Taci3mQyw7W7iWT7Jxo-ag==/com.ft-Q8m2flQFG1MbGImPiuAZmQ==/lib/arm64/libft_native_exp_lib.so (xc_test_call_1+12)
xc_test_call_1
/Users/Brandon/Documents/workplace/working/StudioPlace/xCrash/xcrash_lib/src/main/cpp/xcrash/xc_test.c:85:13
#04 0x0000000000005938 /data/app/~~Taci3mQyw7W7iWT7Jxo-ag==/com.ft-Q8m2flQFG1MbGImPiuAZmQ==/lib/arm64/libft_native_exp_lib.so (xc_test_crash+112)
xc_test_crash
/Users/Brandon/Documents/workplace/working/StudioPlace/xCrash/xcrash_lib/src/main/cpp/xcrash/xc_test.c:126:9
...

iOS 플랫폼의 sourcemap 파일은 .dSYM 접미사가 붙은 디버그 정보가 포함된 심볼 테이블 파일입니다. 일반적으로 프로젝트 컴파일이 완료되면 .app 파일과 같은 디렉터리에 있습니다. 예시는 다음과 같습니다.

$ ls -l Build/Products/Debug-iphonesimulator/
total 0
drwxr-xr-x   6 zy  staff  192  8  9 15:27 Fishing.app
drwxr-xr-x   3 zy  staff   96  8  9 14:02 Fishing.app.dSYM
drwxr-xr-x  15 zy  staff  480  8  9 15:27 Fishing.doccarchive
drwxr-xr-x   6 zy  staff  192  8  9 13:55 Fishing.swiftmodule

참고로 XCode Release 컴파일은 기본적으로 .dSYM 파일을 생성하지만 Debug 컴파일은 기본적으로 생성하지 않으므로 XCode에서 다음과 같이 설정해야 합니다.

Build Settings -> Code Generation -> Generate Debug Symbols -> Yes
Build Settings -> Build Option -> Debug Information Format -> DWARF with dSYM File

zip으로 패키징할 때 해당 .dSYM 파일을 zip 패키지에 포함하면 됩니다. 프로젝트에 .dSYM 파일이 여러 개 포함된 경우 모두 zip 패키지에 함께 포함해야 합니다. zip 패키지 압축 해제 후 디렉터리 구조는 다음과 유사합니다(.dSYM 파일은 본질적으로 디렉터리이며 macOS의 실행 프로그램인 .app 파일과 유사합니다).

sourcemap.zip
├── AFNetworking.framework.dSYM
│   └── Contents
│       ├── Info.plist
│       └── Resources
│           └── DWARF
│               └── AFNetworking
└── App.app.dSYM
    └── Contents
        ├── Info.plist
        └── Resources
            └── DWARF
                └── App

React Native의 sourcemap에는 네이티브 iOS, Android 및 js 부분이 포함되며 총 3가지 소스 맵이 있습니다.

네이티브 iOS 및 Android의 sourcemap 획득 방법은 해당 플랫폼의 패키징 설명을 참조하세요.

js 부분의 sourcemap 획득 방법은 다음과 같습니다.

Android 소스 맵은 기본적으로 활성화되어 있습니다. 소스 맵 파일은 android/app/build/generated/sourcemaps/react/release/index.android.bundle.map에 있습니다.

iOS에서 소스 맵 생성을 활성화하려면 몇 가지 추가 구성이 필요합니다. Xcode를 열고 build phase의 "Bundle React Native code and images"를 편집합니다. 다른 export 항목 위에 원하는 출력 경로가 포함된 SOURCEMAP_FILE 항목을 추가합니다.

With Hermes,React Native <0.71

set -e
#  output source maps
export SOURCEMAP_FILE="./main.jsbundle.map";
#  React Native 0.70에서 Hermes를 사용하는 경우 USE_HERMES를 true로 설정해야 합니다. 그렇지 않으면 소스 맵이 생성되지 않습니다.
export USE_HERMES=true 

# keep the rest of the script unchanged

# When React Native (0.69,0.71) and using Hermes
# add these lines to compose the packager and compiler source maps into one file
REACT_NATIVE_DIR=../node_modules/react-native

if [ -f "$REACT_NATIVE_DIR/scripts/find-node-for-xcode.sh" ]; then
    source "$REACT_NATIVE_DIR/scripts/find-node-for-xcode.sh"
else
    # Before RN 0.70, the script was named find-node.sh
    source "$REACT_NATIVE_DIR/scripts/find-node.sh"
fi
source "$REACT_NATIVE_DIR/scripts/node-binary.sh"
"$NODE_BINARY" "$REACT_NATIVE_DIR/scripts/compose-source-maps.js" "$CONFIGURATION_BUILD_DIR/main.jsbundle.map" "$CONFIGURATION_BUILD_DIR/$UNLOCALIZED_RESOURCES_FOLDER_PATH/main.jsbundle.map" -o "../$SOURCEMAP_FILE"

js sourcemap 파일을 확보한 후 빌드 플랫폼에 해당하는 네이티브 soucemap과 함께 아래 형식으로 zip 패키징합니다.

// Android
sourcemap.zip
├── js/
    ├── index.android.bundle.map
└── android/
    ├── mapping.txt
    ├── armeabi-v7a/
    │   ├── libgameengine.so
    │   ├── libothercode.so
    │   └── libvideocodec.so
    └── arm64-v8a/
        ├── libgameengine.so
        ├── libothercode.so
        └── libvideocodec.so    
// iOS
sourcemap.zip
├── js/
    ├── main.jsbundle.map 
└── ios/
    ├── AFNetworking.framework.dSYM
    │   └── Contents
    │       ├── Info.plist
    │       └── Resources
    │           └── DWARF
    │               └── AFNetworking
    └── App.app.dSYM
        └── Contents
            ├── Info.plist
            └── Resources
                └── DWARF
                    └── App

source-map-visualization 같은 소스 맵 시각화 도구를 사용하여 파일 사용 가능 여부를 검증할 수 있습니다.

업로드 방식

현재 다음과 같은 세 가지 SourceMap 업로드 방식을 지원합니다.

  • 웹 UI 업로드: SourceMap 파일을 수동으로 업로드하고 삭제하는 방식에 적합합니다.
  • 스크립트 업로드: 공용 네트워크 DataWay 환경에서 자동화 업로드에 적합합니다.
  • 빌드 단계 플러그인 업로드: Web 프로젝트가 패키징 단계에서 SourceMap을 자동으로 업로드하는 방식에 적합합니다.

웹 UI 업로드 및 삭제

구성 및 패키징이 완료된 후 사용자는 웹 UI의 [RUM] > [애플리케이션 목록] > [업로드할 애플리케이션 오른쪽 상단의 더보기 아이콘 클릭] > [SourceMap]에서 파일 업로드 및 삭제 작업을 수행할 수 있습니다. 현재 계정에 "편집" 이상의 권한이 있는지 확인하세요.

업로드 및 삭제는 애플리케이션이 속한 워크스페이스에서 수행해야 하며 현재 워크스페이스만 선택해야 합니다. 워크스페이스 간 읽기 전용 상태에서는 이러한 구성 항목이 제공되지 않습니다. 자세한 내용은 워크스페이스 간 조회 설명을 참조하세요.

SourceMap 文件列表、环境筛选及自动清理入口

파일 목록에는 업로드된 파일, 환경, 버전 및 최근 업로드 시간이 표시됩니다. 환경을 필터링하거나 환경, 버전을 입력하여 검색할 수 있으며, 파일의 삭제 아이콘을 클릭하면 해당 파일을 삭제할 수 있습니다.

업로드 시 주의사항:

  1. 파일 크기는 500M를 초과할 수 없습니다.
  2. 파일 형식은 .zip이어야 합니다.
  3. 압축 패키지 압축 해제 후 파일 경로가 error_stack의 URL 경로와 일치하는지 확인하세요.
  4. 여러 파일을 동시에 업로드할 수 없습니다.
  5. 동일한 이름의 파일을 업로드하면 덮어쓰기 알림이 표시되므로 주의하세요.

스크립트 업로드

현재 애플리케이션이 공용 네트워크 DataWay 연결 방식을 사용하는 경우 스크립트를 통해 OpenAPI로 패키징된 sourcemap.zip 파일을 업로드할 수도 있습니다.

자세한 내용은 스크립트 SourceMap 업로드를 참조하세요.

빌드 단계 플러그인 업로드

Web 프로젝트의 경우 웹 UI 업로드와 스크립트 업로드 외에도 프로젝트 빌드 단계에서 플러그인을 통해 SourceMap 파일을 자동으로 업로드할 수 있습니다.

현재 지원되는 방식은 다음과 같습니다.

SourceMap 업로드가 완료되면 오류 스택 해석에 사용할 수 있습니다.

자동 정리

SourceMap 자동 정리는 애플리케이션, 환경별로 보존 개수를 설정하고 이전에 업로드된 SourceMap을 자동으로 정리하여 수동 유지 관리 작업을 줄여줍니다. 이 기능은 기본적으로 비활성화되어 있으며 각 규칙은 현재 애플리케이션에서 선택한 환경에만 적용되고 다른 환경에는 영향을 미치지 않습니다.

구성 전에 애플리케이션이 속한 워크스페이스로 이동하여 현재 워크스페이스만 선택하세요. 관리 경로는 웹 UI 업로드 및 삭제를 참조하세요.

정리 영향

삭제는 되돌릴 수 없으며 해당 버전의 새 오류 및 기존 오류에 대한 소스 코드 복원에 영향을 줄 수 있지만 원본 오류 데이터는 유지됩니다. 자동 정리를 비활성화하거나 보존 개수를 늘려도 삭제된 파일은 복구되지 않습니다. 활성화하기 전에 계속 조사해야 하는 버전에 해당 SourceMap을 보존할 필요가 있는지 확인하세요.

보존 규칙 구성

  1. RUM > 애플리케이션 목록으로 이동하여 대상 애플리케이션 오른쪽 상단의 더보기 아이콘을 클릭하고 SourceMap을 선택합니다.
  2. 자동 정리를 클릭하고 구성할 환경을 선택합니다.
  3. 자동 정리 활성화를 켜고 최근 업로드 항목 보존에 보존 개수를 입력합니다.
  4. 정리 범위 미리보기를 클릭하여 현재 개수, 보존 개수, 예상 삭제 개수 및 삭제 예정 버전을 확인합니다.
  5. 조정이 필요하면 돌아가서 수정을 클릭합니다. 정리 범위를 확인한 후 자동 정리 활성화 확인을 클릭합니다.

보존 개수는 다음 규칙에 따라 집계됩니다.

  • 동일한 애플리케이션, 동일한 환경, 동일한 버전의 파일은 1개로 집계됩니다.
  • 준비 완료된 파일이 있는 버전만 집계되며 최초 업로드 시 준비되지 않았거나 실패한 버전은 집계되지 않습니다.
  • 최근 업로드 시간 기준으로 최신 지정 개수를 보존하며 보존 개수를 초과하는 이전 업로드 버전이 정리 범위에 포함됩니다.
  • 이후 새 파일이 준비되면 시스템이 규칙에 따라 자동으로 정리합니다.

예를 들어 특정 애플리케이션의 production 환경에서 보존 개수를 5개로 설정하면 시스템은 해당 환경 내에서 최근 업로드된 5개의 SourceMap을 보존하며, 다른 환경의 파일은 이 규칙의 영향을 받지 않습니다.

按环境配置 SourceMap 保留份数并预览清理范围

정리 상태 확인

자동 정리 창의 최근 정리 영역에서 실행 상태, 삭제됨, 실패, 보류된 개수와 시작 시간 및 완료 시간을 확인할 수 있습니다. 기록 보기를 클릭하면 정리 기록을 자세히 확인할 수 있습니다.

자동 정리 비활성화

해당 애플리케이션의 SourceMap > 자동 정리로 이동하여 대상 환경을 선택하고 자동 정리 활성화를 끈 후 페이지 안내에 따라 저장합니다.

비활성화 후에는 이후 삭제가 중지되지만 실행 중인 개별 삭제는 완료될 수 있으며 이미 삭제된 파일은 복구되지 않습니다.

문서 평가

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