NHN Cloud > SDK 사용 가이드 > Log & Crash > iOS

[공지] NHN Cloud SDK 0.13.0부터 arm64e 아키텍처를 사용하는 기기(iPhone XS, XR, XS Max, iPad Pros 3rd)에서 발생한 크래시의 집계, 분석이 가능합니다.

Prerequisites

1. NHN Cloud SDK를 설치합니다.
2. NHN Cloud 콘솔에서 Log & Crash Search를 활성화합니다.
3. Log & Crash Search에서 AppKey를 확인합니다.

NHN Cloud Logger 구성

• iOS용 NHN Cloud Logger SDK의 구성은 다음과 같습니다.

Service	Cocoapods Pod Name	Framework	Dependency	Build Settings
Log & Crash	ToastLogger	ToastLogger.framework	[External & Optional] * CrashReporter.framework (Toast)
Mandatory	ToastCore ToastCommon	ToastCore.framework ToastCommon.framework		OTHER_LDFLAGS = ( "-ObjC", "-lc++" );

NHN Cloud Logger SDK를 Xcode 프로젝트에 적용

1. Cococapods 적용

• Podfile을 생성하여 NHN Cloud SDK에 대한 pod를 추가합니다.

platform :ios, '9.0'
use_frameworks!

target '{YOUR PROJECT TARGET NAME}' do
    pod 'ToastLogger'
end

2. 바이너리를 다운로드하여 NHN Cloud SDK 적용

프레임워크 설정

• NHN Cloud의 Downloads 페이지에서 전체 iOS SDK를 다운로드할 수 있습니다.
• Xcode Project에 ToastLogger.framework, ToastCore.framework, ToastCommon.framework를 추가합니다.
• NHN Cloud Logger의 Crash Report 기능을 사용하려면 함께 배포되는 CrashReporter.framework도 프로젝트에 추가해야 합니다.

프로젝트 설정

• Build Settings의 Other Linker Flags에 -lc++와 -ObjC 항목을 추가합니다.

  • Project Target > Build Settings > Linking > Other Linker Flags

• CrashReporter.framewor를 직접 다운로드하거나 빌드한 경우에는 Build Setting의 Enable Bitcode의 값을 NO로 변경해야 합니다.

  • Project Target > Build Settings > Build Options > Enable Bitcode

    NHN Cloud의 Downloads 페이지에서 다운로드한 CrashReporter.framework는 bitCode를 지원합니다.

NHN Cloud Symbol Uploader 적용

프로젝트의 디버그 설정 변경

• 빌드 설정을 변경하여 프로젝트의 디버그 정보 형식을 변경해야합니다.
• Xcode -> Project Target -> Build Settings -> Debug Information Format -> Debug -> DWARF with dSYM File

개발 환경에서 Run Script를 사용하여 자동 업로드

• Xcode -> Project Target -> Build Phases -> + -> New Run Script Phase
• 표시되는 새 Run Script 섹션을 펼칩니다.
• Shell(셸) 필드 아래에 있는 스크립트 필드에서 새 실행 스크립트를 추가합니다.

if [ "${CONFIGURATION}" = "Debug" ]; then
    ${PODS_ROOT}/ToastSymbolUploader/toastcloud.sdk-*/run --app-key LOG_N_CRASH_SEARCH_DEV_APPKEY
fi

• LOG_N_CRASH_SEARCH_APPKEY에는 Log&Crash Search의 AppKey를 입력해야합니다.
• Run Script 섹션 하단의 Input Files에 dSYM의 기본 경로를 설정합니다.
  • ${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME}/Contents/Resources/DWARF/${TARGET_NAME}

Symbol Uploader를 사용하여 직접 업로드

• SymbolUploader 사용법

USAGE: symbol-uploader -ak <ak> -pv <pv> [-sz <sz>] <path> [--verbose]

ARGUMENTS:
  <path>                  dSYM file path is must be entered. 

OPTIONS:
  -ak, --app-key <ak>     [Log&Crash Search]'s AppKey must be entered. 
  -pv, --project-version <pv>
                          Project version must be entered. 
  -sz, --service-zone <sz>
                          You can choose between real, alpha, and demo. (default: real)
  --verbose               Show more debugging information 
  -h, --help              Show help information.

• Xcode의 Run Script를 사용하지 않고 사용자가 원하는 시점에 아래와 같은 방법으로 SymbolUploader를 사용하여 직접 Symbol을 업로드 할 수 있습니다.

./SymbolUploader --app-key {APP_KEY} --project-version {CFBundleShortVersionString || MARKETING_VERSION} {symbol path(~/Project.dSYM)}

동일한 버전의 Symbol이 이미 업로드되어 있는 경우 SymbolUploader는 업로드되어 있는 Symbol을 제거하고 업로드를 수행합니다. 이때 두 Symbol 파일의 파일명이 다를 경우 업로드되어 있던 Symbol은 제거되지 않습니다. Log & Crash Search 콘솔에서 업로드되어 있는 Symbol을 제거해야 합니다. https://console.toast.com/-> 조직 선택 -> 프로젝트 선택 -> Anaytics -> Log & Crash Search -> 설정 -> 심벌 파일

CrashReport 사용시 주의사항

• arm64e 아키텍처를 사용하는 기기의 크래시 분석을 위해서는 NHN Cloud Logger와 함께 배포되는 PLCrashReporter를 사용해야 합니다.
  • NHN Cloud의 Downloads 페이지가 아닌 다른 곳에서 다운로드하거나 직접 빌드한 PLCrashReporter를 사용할 경우 arm64e 아키텍처를 사용하는 기기의 크래시 분석이 불가능합니다.

NHN Cloud Logger SDK 초기화

• Log & Crash Search에서 발급받은 AppKey를 설정합니다.

초기화 API 명세

// 초기화
+ (void)initWithConfiguration:(ToastLoggerConfiguration *)configuration;

초기화 예

ToastLoggerConfiguration *configuration = [ToastLoggerConfiguration configurationWithAppKey:@"YOUR_APP_KEY"];
[ToastLogger initWithConfiguration:configuration];

로그 전송

• NHN Cloud Logger는 5가지 레벨의 로그 전송 함수를 제공합니다.

로그 전송 API 명세

// DEBUG Level log
+ (void)debug:(NSString *)message;

// INFO Level log
+ (void)info:(NSString *)message;

// WARN Level log
+ (void)warn:(NSString *)message;

// ERROR Level log
+ (void)error:(NSString *)message;

// FATAL Level log
+ (void)fatal:(NSString *)message;

로그 전송 API 사용 예

[ToastLogger info:@"NHN Cloud Log & Crash Search!"];

사용자 정의 필드 설정

• 원하는 사용자 정의 필드를 설정합니다.
• 사용자 정의 필드를 설정하면 로그 전송 API를 호출할 때마다 설정한 값을 로그와 함께 서버로 전송합니다.

사용자 정의 필드 API 명세

// 사용자 정의 필드 추가
+ (void)setUserFieldWithValue:(NSString *)value forKey:(NSString *)key;

• 사용자 정의 필드는 Log & Crash Search > 로그 검색을 클릭한 후 로그 검색 화면의 선택한 필드에 표시되는 값과 같습니다.

사용자 정의 필드 제약사항

• 이미 예약된 필드는 사용할 수 없습니다.
• 필드 이름은 'A-Z, a-z'로 시작하고 'A-Z, a-z, 0-9, -, _' 문자를 사용할 수 있습니다.
• 필드 이름의 공백은 '_'로 치환됩니다.

사용자 정의 필드 사용 예

// 사용자 정의 필드 추가
[ToastLogger setUserFieldWithValue:@"USER_VALUE" forKey:@"USER_KEY"];

크래시 로그 수집

• NHN Cloud Logger는 크래시 정보를 로그로 전송하는 기능을 제공합니다.
• NHN Cloud Logger를 초기화할 때 함께 활성화되고 사용 여부를 설정할 수 있습니다.
• 크래시 로그를 전송하려면 PLCrashReporter를 사용합니다.

CrashReporter 사용 여부 설정

• CrashReporter 기능은 기본적으로 NHN Cloud Logger를 초기화할 때 함께 활성화됩니다.
• NHN Cloud Logger를 초기화할 때 사용 여부를 설정할 수 있습니다.
• 크래시 로그 전송을 기능을 사용하지 않으려면 CrashReporter 기능을 비활성화해야 합니다.

사용자 아이디가 설정되어 있으면 Log&Crash Search 콘솔의 크래시 사용자 항목에서 사용자별 크래시 경험을 확인 할 수 있습니다. 사용자 아이디 설정은 시작하기에서 확인 가능합니다.

CrashReporter 활성화

// CrashReporter 활성화
ToastLoggerConfiguration *configuration = [ToastLoggerConfiguration configurationWithAppKey:@"YOUR_APP_KEY" 
                                                                        enableCrashReporter:YES];

[ToastLogger initWithConfiguration:configuration];

CrashReporter 비활성화

// CrashReporter 비활성화
ToastLoggerConfiguration *configuration = [ToastLoggerConfiguration configurationWithAppKey:@"YOUR_APP_KEY" 
                                                                        enableCrashReporter:NO];

[ToastLogger initWithConfiguration:configuration];

크래시 발생 시점에 추가 정보를 설정하여 전송

• 크래시 발생 직후, 추가 정보를 설정할 수 있습니다.
• setShouldReportCrashHandler의 Block에서 사용자 정의 필드를 설정하면 정확히 크래시가 발생한 시점에 추가 정보를 설정할 수 있습니다.

Data Adapter API 명세

+ (void)setShouldReportCrashHandler:(void (^)(void))handler;

Data Adapter 사용 예

[ToastLogger setShouldReportCrashHandler:^{
  // 사용자 정의 필드 를 통해 Crash가 발생한 상황에서 얻고자 하는 정보를 함께 전송    
  // 사용자 정의 필드 추가
  [ToastLogger setUserFieldWithValue:@"USER_VALUE" forKey:@"USER_KEY"];

}];

로그 전송 후 추가작업 진행

• Delegate를 등록하면 로그 전송 후 추가 작업을 진행할 수 있습니다.

Delegate 설정 API 명세

+ (void)setDelegate:(id<ToastLoggerDelegate>) delegate;

Delegate API 명세

@protocol ToastLoggerDelegate <NSObject>
@optional
// 로그 전송 성공
- (void)toastLogDidSuccess:(ToastLog *)log;

// 로그 전송 실패
- (void)toastLogDidFail:(ToastLog *)log error:(NSError *)error;

// 네트워크 단절 등의 이유로 로그 전송에 실패한 경우 재전송을 위해 SDK 내부 저장
- (void)toastLogDidSave:(ToastLog *)log;

// 로그 필터링
- (void)toastLogDidFilter:(ToastLog *)log logFilter:(ToastLogFilter *)logFilter;
@end

Delegate 설정 및 사용 예

#import <ToastLogger/ToastLogger.h>

@interface AppDelegate () <UIApplicationDelegate, ToastLoggerDelegate>

@end


@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    // ...

    // 초기화
    ToastLoggerConfiguration *configuration = [ToastLoggerConfiguration configurationWithAppKey:@"YOUR_APP_KEY" 
                                                                            enableCrashReporter:YES];
    [ToastLogger initWithConfiguration:configuration];

    // Delegate 설정
    [[ToastLogger setDelegate:self];

    return YES;
}

#pragma mark - ToastLoggerDelegate
// 로그 전송 성공
- (void)toastLogDidSuccess:(ToastLog *)log {
      // ...
 }

// 로그 전송 실패
- (void)toastLogDidFail:(ToastLog *)log error:(NSError *)error {
      // ...
}

// 네트워크 단절 등의 이유로 로그 전송에 실패한 경우 재전송을 위해 SDK 내부 저장
- (void)toastLogDidSave:(ToastLog *)log {
      // ...
}

// 로그 필터링
- (void)toastLogDidFilter:(ToastLog *)log logFilter:(ToastLogFilter *)logFilter {
      // ...
}

@end

Network Insights

• Network Insights는 콘솔에 등록한 URL을 호출하여 지연 시간과 응답값을 측정합니다. 이를 활용하여 세계 여러 나라(디바이스의 국가 코드 기준)에서의 지연 시간과 응답값을 측정할 수 있습니다.

콘솔을 통해 Network Insights 기능을 활성화하면 NHN Cloud Logger를 초기화할 때, 콘솔에 등록한 URL로 1회 요청합니다.

Network Insights 활성화

1. NHN Cloud Console에서 Log & Crash Search 서비스를 클릭합니다.
2. 설정 메뉴를 클릭합니다.
3. 로그 전송 설정 탭을 클릭합니다.
4. Network Insights 로그를 활성화합니다.

URL 설정

1. NHN Cloud Console에서 Log & Crash Search 서비스를 클릭합니다.
2. 네트워크 인사이트 메뉴를 클릭합니다.
3. URL 설정 탭을 클릭합니다.
4. 측정하려는 URL을 입력하고 추가 버튼을 클릭합니다.