Android SDK 사용 방법

개요

이 장에서는 Effective Log Search & Analytics NELO Android SDK의 사용 방법을 설명합니다.

NELO는 Effective Log Search & Analytics의 프로젝트 코드 네임입니다.

Effective Log Search & Analytics의 Android SDK는 Android OS 2.3.3 이상(API 10 이상)을 지원합니다.

다운로드

API 목록

// 초기화 함수
static boolean init(Application application, String reportServer, int projectName, String appId, String projectVersion)
static boolean init(Application application, String reportServer, int projectName, String appId, String projectVersion, String userId)
static boolean init(Application application)
static boolean isInit()

//System Field 설정 함수
static void void setUserID(String userID)
static void void setLogType(String logType)
static void void setLogSource(String logSource)

// 로그 전송 함수
static void debug(String errorCode,String message,String location)
static void debug(String errorCode,String message)
static void info(String errorCode,String message,String location)
static void info(String errorCode,String message)
static void warn(String errorCode,String message,String location)
static void warn(String errorCode,String message)
static void error(String errorCode,String message,String location)
static void error(String errorCode,String message)
static void fatal(String errorCode,String message,String location)
static void fatal(String errorCode,String message)

// 로그 전송 함수(Exception 포함)
static void debug(Throwable t, String errorCode,String message,String location)
static void debug(Throwable t, String errorCode,String message)
static void info(Throwable t, String errorCode,String message,String location)
static void info(Throwable t, String errorCode,String message)
static void warn(Throwable t, String errorCode,String message,String location)
static void warn(Throwable t, String errorCode,String message)
static void error(Throwable t, String errorCode,String message,String location)
static void error(Throwable t, String errorCode,String message)
static void fatal(Throwable t, String errorCode,String message,String location)
static void fatal(Throwable t, String errorCode,String message)
static void crash(Throwable t, String errorCode,String message,String location)
static void crash(Throwable t, String errorCode,String message)

// 옵션 설정 함수
static boolean getNeloEnable()
static void setNeloEnable(boolean enabled)

static boolean getDebug()
static void setDebug(boolean enabled)

static CrashReportMode getCrashMode()
static void setCrashMode(CrashReportMode mode)

static NeloSendMode getNeloSendMOde()
static void setNeloSendMOde(NeloSendMode mode)

static int getMaxFileSize()
static void setMaxFileSize(int max_file_size)

static Nelo2LogLevel getLogLevelFilter()
static void setLogLevelFilter(Nelo2LogLevel loglevel)

Effective Log Search & Analytics Android SDK 설치

다운로드한 Effective Log Search & Analytics Android SDK를 Android 프로젝트의 libs 폴더에 저장합니다.

NELO SDK 0.9.0 버전부터 프로토콜에 따라 libs 폴더에 추가하는 라이브러리 파일이 다릅니다.

NELO SDK 필수 추가 항목 nelo2-android-sdk-common-버전명.jar
--> Thrift 프로토콜 사용시 nelo2-android-sdk-thrift-버전명.jar
--> HTTPS 프로토콜 사용시 nelo2-android-sdk-https-버전명.jar


[그림 - libs저장된 NELO2 Android SDK]

Effective Log Search & Analytics NELO Android SDK 설정

Effective Log Search & Analytics NELO Android SDK 초기화

Effective Log Search & Analytics Android SDK는 두 가지 방법으로 초기화할 수 있습니다.

  1. init 메서드를 이용한 초기화 방법

    • 기존과 동일하게 앱 크래시 발생 시, Crash Dialog를 생성하지 않고 전송합니다.
    • Activity보다는 Application에서 호출하는 것이 좋습니다.
  2. Application Class에서 @NeloConf 애너테이션과 같이 사용

    • 앱 크래시 발생 시 사용자의 설정에 따라 Crash 로그를 전송하는 Dialog를 출력합니다.
Main Activity에서 초기화하는 방법
public class MainActivity extends Activity {

    .....

    @Override

    protected void onCreate(Bundle savedInstanceState) {

        .....

        NeloLog.init(getApplication(), "elsa-col.ncloud.com", 10006, "__프로젝트_아이디__", "__프로젝트버전__");

        .....

    }

}
Application에서 초기화하는 방법
@NeloConf(
    collectorUrl = "elsa-col.ncloud.com",                   // Effective Log Search & Analytics Collector URL   (required)
    serverPort = Nelo2Constants.SERVER_PORT_THRIFT,         // Effective Log Search & Analytics Port Number     (required)
    projectName = "72356c50401b8e20_testproject",           // Effective Log Search & Analytics Project ID     (required)
    mode = CrashReportMode.DIALOG,                          // Effective Log Search & Analytics CrashReportMode (optional, Default : SLIENT)
    sendMode = NeloSendMode.ALL,                            // Effective Log Search & Analytics SendMode        (optional, Default : ALL)
    debug = true,                                           // Effective Log Search & Analytics Debug mode      (optional, Default : false)
    logSource = "elsa-android",                             // Effective Log Search & Analytics Log Source      (optional, Default : nelo2-android)
    logType = "development",                                // Effective Log Search & Analytics Log Type        (optional, Defalut : nelo2-log)
    resDialogText = R.string.crash_dialog_text,             // Crash Report Doalog Text     (required, if you set mode CrashReportMode.Dialog)
    resDialogTitle = R.string.crash_dialog_title            // Crash Report Dolog Title    (required, if you set mode CrashReportMode.Dialog)
)
public class MainApplication extends Application {
    .....
    @Override
    protected void onCreate() {
        .....
        NeloLog.init(this);
        .....
    }
}
.....

추가로 AndroidManifest.xml 파일에 권한을 추가해야 합니다. 해당 권한은 네트워크 상태, 디바이스정보, 통신사, Logcat 등의 정보를 가져오기 위해서 필요합니다.

.....
/** AndroidManifest.xml **/
    <!-- Nelo 로그 전송을 위한 인터넷 접근 권한(필수) -->
    <uses-permission android:name="android.permission.INTERNET"/>

    <!-- Platform, Carrier 등 폰의 정보를 접근하기 위한 권한(필수) -->
    <uses-permission android:name="android.permission.READ_PHONE_STATE" />

    <!-- Network 접근 여부에 대하여 접근하기 위한 권한(필수) -->
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

    <!-- Network에 접근되지 않는 경우, 파일로 data를 저장하기 위한 권한 -->
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
.....

      <!-- Crash Report Dialog를 사용하기 위하여 Application을 생성했다면 이름을 설정해야 함-->
       <application ..... android:name="ApplicationName">
.....

       <!-- Network 상태를 체크하여 WiFi 모드일 때만 로그를 보내기 위해서 추가되어야 하는 리시버 -->
    <!-- SendMode를 All로 사용 시는 추가하지 않아도 됨 -->
    <receiver android:name="com.nhncorp.nelo2.android.util.NetworkStatusReceiver">
        <intent-filter>
               <action android:name="android.net.conn.CONNECTIVITY_CHANGE"/>
        </intent-filter>
    </receiver>
.....

<!-- Crash Report Dialog를 사용하기 위한 Activity -->
<!-- CrashReportMode.DIALOG를 사용하지 않으면 추가하지 않아도 됨 -->
<activity android:name="com.nhncorp.nelo2.android.CrashReportDialog"
    android:theme="@android:style/Theme.Dialog"
    android:launchMode="singleInstance"
    android:excludeFromRecents="true"
    android:finishOnTaskLaunch="true" />
.....

Effective Log Search & Analytics NELO2 Android SDK 사용

Effective Log Search & Analytics Android SDK를 사용하는 실제 코드 예입니다.

.....
import com.nhncorp.nelo2.android.NeloLog;
.....

public class MainActivity extends Activity {
.....
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        NeloLog.init(getApplication(),"ELSA-COLLECTOR-URL",10006,"ELSA-PROJECT-ID","PROJECT-VERSION");
        NeloLog.debug("ErrorCode","Message","ErrorLocation");   // Send Debug Message
        NeloLog.info("ErrorCode","Message","ErrorLocation");    // Send Info Message
        NeloLog.warn("ErrorCode","Message","ErrorLocation");    // Send Warn Message
        NeloLog.error("ErrorCode","Message","ErrorLocation");   // Send Error Message
        NeloLog.fatal("ErrorCode","Message","ErrorLocation");   // Send Fatal Message
        String nullString = null;
        try{
            nullString.toString();
        }catch(Exception e){
            NeloLog.crash(e,"ErrorCode","Message","ErrorLcoation"); // Send caught crash Message
        }

        NeloLog.debug("ErrorCode","Message","ErrorLocation");   // Send message with custom message
        int i = 10 / 0;     // Nelo send uncaught exception
    }
.....

NELO2 Android SDK API 상세 정보

Effective Log Search & Analytics NELO Android SDK에서 제공하는 각 API에 대하여 상세히 설명합니다.

초기화 함수

boolean init(Application application, String reportServer, int serverPort, String appId, String appVersion)

boolean init(Application application, String reportServer, int serverPort, String appId, String appVersion, String userId)

Parameters

  • Application application: Android의 application 정보. 일반적으로 getApplication()을 사용합니다.
  • String reportServer: Effective Log Search & Analytics 수집 서버의 주소
    • Thrift 프로토콜 사용 시
      • Effective Log Search & Analytics 수집 서버: elsa-col.ncloud.com
    • HTTPS 프로토콜 사용 시
  • int serverPort: 수집 서버의 포트 정보
    • Thrift: 10006
    • Https: 443
  • String appId: Effective Log Search & Analytics에 등록된 프로젝트의 아이디
  • String appVersion: 전송할 앱의 버전 정보
  • String userId: 전송할 사용자 아이디(옵션)

Example

NeloLog.init(getApplication(), "elsa-col.ncloud.com", 10006, "72356c50401b8e20_testproject", "1.0.0");

설명

  • NeloLog를 초기화하는 함수. NeloLog를 사용하기 전에 사용되어 NeloLog를 초기화해야 정상 동작합니다. 초기화는 1번만 실행합니다.
  • Activity에서 위 방법으로 초기화 시에는 Crash Report Dialog를 사용할 수 없습니다.

boolean init (Application application)

Parameters

  • Application application: Android의 Application 정보. 일반적으로 getApplication()을 사용합니다.

Example

  • 아래와 같이 @NeloConf 애너테이션을 이용하여 다른 항목들을 설정함
  • Activity가 아닌 Application에서 호출하여야 함
  • Crash Report Dialog를 사용하기 위해서는 위 방법으로 초기화하여야만 동작함
@NeloConf(

    collectorUrl = "elsa-col.ncloud.com",      // NELO Collector URL   (required)

    serverPort = Nelo2Constants.SERVER_PORT_THRIFT,         // NELO Port Number     (required)

    projectName = "72356c50401b8e20_testproject",           // NELO Project ID      (required)

    mode = CrashReportMode.DIALOG,                          // NELO CrashReportMode (optional, Default : SLIENT)

    sendMode = NeloSendMode.ALL,                            // NELO SendMode        (optional, Default : ALL)

    debug = true,                                           // NELO Debug mode      (optional, Default : false)

    logSource = "elsa-android",   // NELO Log Source      (optional, Default : nelo2-android)

    logType = "development",            // NELO Log Type        (optional, Defalut : nelo2-log)

    resDialogText = R.string.crash_dialog_text,             // Crash Report Doalog Text     (required, if you set mode CrashReportMode.Dialog)

    resDialogTitle = R.string.crash_dialog_title            // Crash Report Doalog Title    (required, if you set mode CrashReportMode.Dialog)

)

public class MainApplication extends Application {

    .....

    @Override

    protected void onCreate() {

        .....

        NeloLog.init(this);

        .....

    }

}

.....

설명

  • NeloLog를 초기화하는 함수, @NeloConf 애너테이션과 같이 사용하여야 설정을 할 수 있음

System Field 설정 함수

static void setUserID(String userID)

static void setUserID(String instanceName, String userID)

Parameters

  • String userID: 사용자 아이디

Example

NeloLog.setUserID("test");

설명

  • 사용자 아이디를 설정하기 위하여 사용함. 설정된 값은 이후 보내는 모든 로그에서 동일하게 전달.

static void setLogSource(String logSource)

static void setLogSource(String instanceName, String logSource)

Parameters

  • String logSource: logSource 정보 설정

Example

NeloLog.setLogSource("NELO2 Android SDK LogSource");

설명

  • NELO2의 logSource 정보를 설정하는 API. 설정된 값은 이후 보내는 모든 로그에서 동일하게 전달.

static void setLogType(String logType)

static void setLogType(String instanceName, String logType)

Parameters

  • String logType: logType 정보 설정

Example

  • NeloLog.setLogType("NELO2 Android SDK LogType");

설명

  • Effective Log Search & Analytics의 logType 정보를 설정하는 API. 설정된 값은 이후 보내는 모든 로그에서 동일하게 전달.

로그 전송 함수

static void debug(String errorCode,String message,String location)

static void debug(String errorCode,String message)

static void info(String errorCode,String message,String location)

static void info(String errorCode,String message)

static void warn(String errorCode,String message,String location)

static void warn(String errorCode,String message)

static void error(String errorCode,String message,String location)

static void error(String errorCode,String message)

static void fatal(String errorCode,String message,String location)

static void fatal(String errorCode,String message)

Parameters

  • String errorCode: NELO2의 errorCode 필드에 매핑되는 값
  • String message: NELO2의 body에 매핑되는 값
  • String location: Log가 발생한 위치를 입력.

Example

NeloLog.error("test","테스트값","location");
NeloLog.debug("test 2","테스트값 ")

설명

  • Error Level별로 전송하는 함수가 제공됨

로그 전송 함수(Exception 포함)

static void debug(Throwable t, String errorCode,String message,String location)

static void debug(Throwable t, String errorCode,String message)

static void info(Throwable t, String errorCode,String message,String location)

static void info(Throwable t, String errorCode,String message)

static void warn(Throwable t, String errorCode,String message,String location)

static void warn(Throwable t, String errorCode,String message)

static void error(Throwable t, String errorCode,String message,String location)

static void error(Throwable t, String errorCode,String message)

static void fatal(Throwable t, String errorCode,String message,String location)

static void fatal(Throwable t, String errorCode,String message)

// 동적 인스턴스 로그 전송용
static void debugWithInstanceName(String instanceName, Throwable t, String errorCode, String message)

static void debugWithInstanceName(String instanceName, Throwable t, String errorCode, String message, String errorLocation)

static void infoWithInstanceName(String instanceName, Throwable t, String errorCode, String message)

static void infoWithInstanceName(String instanceName, Throwable t, String errorCode, String message, String errorLocation)

static void warnWithInstanceName(String instanceName, Throwable t, String errorCode, String message)

static void warnWithInstanceName(String instanceName, Throwable t, String errorCode, String message, String errorLocation)

static void errorWithInstanceName(String instanceName, Throwable t, String errorCode, String message)

static void errorWithInstanceName(String instanceName, Throwable t, String errorCode, String message, String errorLocation)

static void fatalWithInstanceName(String instanceName, Throwable t, String errorCode, String message)

static void fatalWithInstanceName(String instanceName, Throwable t, String errorCode, String message, String errorLocation)

Parameters

  • Throwable t: Exception 정보
  • String errorCode: Effective Log Search & Analytics의 errorCode 필드에 매핑되는 값
  • String message: Effective Log Search & Analytics의 body에 매핑되는 값
  • String location: Log가 발생한 위치를 입력

Example

try{

    int a = 10 / 0;

} catch (Exception e) {

    NeloLog.error(e,"Error_Code",e.getMessage());

}

설명

  • Error Level별로 전송하는 함수가 제공됨
  • location 정보를 설정하지 않으면, Throwable에서 에러가 발생한 위치를 location에 저장함
  • Throwable 정보를 설정 시 Cause라는 필드가 저장되며, getCause()한 값이 저장됨

static void crash(Throwable t, String errorCode,String message,String location)

static void crash(Throwable t, String errorCode,String message)

Parameters

  • Throwable t: Exception 정보
  • String errorCode: NELO2의 errorCode 필드에 매핑되는 값
  • String message: NELO2의 body에 매핑되는 값
  • String location: Log가 발생한 위치를 입력

Example

try{
    int a = 10 / 0;

} catch (Exception e) {

    NeloLog.crash(e,"Error_Code",e.getMessage());

}

설명

  • 사용자가 crash 함수를 호출하는 순간 crash 로그를 Nelo로 전송
  • Crash 로그와 동일하게 DmpData필드 전송
  • 앱의 성능을 위해서 필요한 경우가 아니면 잦은 호출은 피하는것이 좋음

크래시 콜백

static void setNeloCrashCallback(NeloCrashCallback neloCrashCallback)

Parameters

  • NeloCrashCallback neloCrashCallback: 크래시 발생 시 호출되는 함수
    • boolean beforeSendNeloCrash()
      • 크래시 발생 시 크래시 로그를 전송할지 말지 return값으로 결정
    • boolean beforeInstanceSendNeloCrash(String instanceName) (현재는 지원하지 않습니다.)
      • 여러 개의 인스턴스를 생성한 경우 특정 인스턴스만 로그를 전송하기 위한다면 instanceName값과 비교해서 return값으로 결정
      • NeloLog.init()로 초기화되는 경우의 이름은 "Nelo2Constants.NELO_DEFAULT_INSTANCE_NAME"으로 사용하면 됩니다.
    • void finishInstanceSendNeloCrash(String instanceName) (현재는 지원하지 않습니다.)
      • 특정 인스턴스의 로그 전송을 마치고 호출되는 함수
    • void finishSendNeloCrash()
      • 전체 크래시 전송을 마치고 호출되는 함수

Example

NeloLog.setNeloCrashCallback(new NeloCrashCallback() {
        @Override
        public boolean beforeSendNeloCrash() {
            Log.e("[AndroidApp]", "______________[[ beforeSendNeloCrash ]]__________________");
            return true;
        }

        @Override
        public boolean beforeInstanceSendNeloCrash(String instanceName) {
            Log.e("[AndroidApp]", "______________[[ beforeInstanceSendNeloCrash ]   " + instanceName + "]__________________");
            return Nelo2Constants.NELO_DEFAULT_INSTANCE_NAME.equalsIgnoreCase(instanceName);
        }

        @Override
        public void finishInstanceSendNeloCrash(String instanceName) {
            Log.e("[AndroidApp]", "______________[[ finishInstanceSendNeloCrash ]   " + instanceName + "]__________________");
        }

        @Override
        public void finishSendNeloCrash() {
            Log.e("[AndroidApp]", "______________[[ finishSendNeloCrash ]]__________________");
        }
    });

설명

  • 크래시 발생 시 크래시 전송하기 전에 사용자가 정의한 함수를 호출할 수 있는 콜백 함수

옵션 설정 함수

static boolean getNeloEnable()

static void setNeloEnable(boolean enabled)

Parameters

  • boolean enabled: Nelo의 사용 여부 설정

설명

  • false로 설정 시 모든 Nelo의 로그 전송이 중단됨
  • 파일로 저장되는 기능도 동작하지 않음

static boolean getDebug()

static void setDebug(boolean enabled)

Parameters

  • boolean enabled: Debug 모드의 사용 여부

설명

  • Debug모드 설정시 Logcat에 자세한 로그를 기록
  • 테스트 환경에서만 true로 설정하고, 운영 환경에서는 false로 설정

static CrashReportMode getCrashMode()

static void setCrashMode(CrashReportMode mode)

Parameters

  • CrashReportMode mode: 앱 크래시 발생 시 크래시를 전송하는 방법 설정

설명

  • AndroidManifest.xml 파일의 CrashReportDialog와 연관
  • CrashReportMode
    • CrashReportMode.NONE: 앱 크래시 발생 시 크래시를 전송하지 않음
    • CrashReportMode.SLIENT: 앱 크래시 발생 시 사용자에게 알리지 않고, NELO로 크래시 로그 전송
    • CrashReportMode.DIALOG: 앱 크래시 발생 시 사용자에게 Crash Report Dialog를 보여주고, 사용자가 OK를 선택한 경우만 크래시 전송
      • @NeloConf의 어노테이션의 다음 항목과 연관됨
        • resDialogTitle: Crash Report Dialog의 제목. res/values/string.xml에 정의된 String의 ID
        • resDialogText: Crash Report Dialog의 설명. res/values/string.xml에 정의된 String의 ID

static NeloSendMode getNeloSendMOde()

static void setNeloSendMOde(NeloSendMode mode)

Parameters

  • NeloSendMode mode: Nelo의 전송방법 설정

설명

네트워크 상태 ALL ONLY_WIFI_WITH_FILE_SAVE ONLY_WIFI_WITHOUT_FILE_SAVE
3g 전송 미전송, 파일저장 미전송, 파일저장 안함
Wi-FI 전송 전송 전송
Not Connected 미전송, 파일저장 미전송, 파일저장 미전송, 파일저장안함
  • AndroidManifest.xml 파일의 NetworkStatusReceiver와 연관

static int getMaxFileSize()

static void setMaxFileSize(int max_file_size)

static int getMaxFileSize(String instanceName)

static void setMaxFileSize(String instanceName, int max_file_size)

Parameters

  • int max_file_size: Nelo에서 저장할 파일의 최고 크기

설명

  • 기본값은 1Mb(1024 * 1024 byte)
  • 저장되는 값이 max_file_size보다 클 경우, 과거 데이터를 지운 후 저장

static void flush()

설명

  • 큐와 파일에 저장된 로그를 NELO 서버로 전송함

static long getAllNeloSaveLogFileSize()

설명

  • 현재 NeloLog가 사용중인 파일의 총 사이즈를 리턴함

static boolean clearSavedNeloLogFile(boolean flushFile)

Parameters

  • boolean flushFile: 이전 파일을 읽어서 서버로 전송할지 여부를 결정함

설명

  • 파일명은 InstanceName과 프로젝트명을 가지고 hash하여 생성된 이름으로 사용함
  • 프로젝트명/인스턴스명이 변경되어 기존파일이 삭제가 필요한 경우 위 함수를 호출하면 됨
  • flushFile값이 true이면 이전 파일을 삭제하기 전에 모든 내용을 읽어서 큐에 저장함
  • flushFile의 기본값은 true

static void setLogLevelFilter(Nelo2LogLevel loglevel)
static Nelo2LogLevel getLogLevelFilter()

Parameters

  • Nelo2LogLevel loglevel : loglevel 이상의 로그만 Nelo로 전송

설명

  • 기본값은 Nelo2LogLevel.DEBUG
  • crash 또는 flush 같이 사용자가 명시적으로 로그를 서버로 전송요청하는 경우는 LogLevel 필터의 값을 무시함

FAQ

1. Crash 발생 시 파일에 저장된 로그를 모두 Effective Log Search & Analytics 서버로 전송하고 싶다면?

CrashCallback 함수 중 finishSendNeloCrash() 함수에서 NeloLog.flush()을 호출하여 파일과 큐에 있는 모든 로그를 Nelo 서버로 전송하면 됩니다.

2. 보낸 적 없는 "New User install App" 로그가 전송됩니다.

"New User install App" 로그는 App이 최초 인스톨 된 시점에 한 번 전송됩니다.

3. proguard 적용 시 주의할 점

proguard 적용 시 ThriftConnector, HttpsConnector도 난독화하면 해당 Class를 찾을 수 없다며 로그 전송에 실패합니다. 이 Class들은 proguard 적용 시 제외 처리해야 합니다.

4. "Could not find class 'com.nhncorp.nelo2.android.HttpsConnector', referenced from method com.nhncorp.nelo2.android.Nelo2ConnectorFactory.getConnector" 에러가 발생합니다.

Effective Log Search & Analytics Android SDK 설치에서 SDK를 common, thrift, https 이렇게 3개로 나누어 사용한다고 하였는데, https 파트를 추가하지 않는경우 발생하는 경고 문구입니다. thrift로만 전송 시 무시해도 됩니다.

""에 대한 건이 검색되었습니다.

    ""에 대한 검색 결과가 없습니다.

    처리중...