Using the Android SDK v1

Available in Classic and VPC

Overview

This chapter describes how to use Effective Log Search & Analytics NELO Android SDK.
NELO is the project code name for Effective Log Search & Analytics.
Android SDK for ESLA supports Android OS 2.3.3 or later(API 10 or later).

Download

• Android SDK Download

API list

// Initialization functions
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 setting functions
static void void setUserID(String userID)
static void void setLogType(String logType)
static void void setLogSource(String logSource)

// Log transfer functions
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)

// Log transfer functions (Including exceptions)
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)

// Option setting functions
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)

Install Effective Log Search & Analytics Android SDK

Save the downloaded Effective Log Search & Analytics Android SDK on the libs folder of your Android project.

Starting from NELO SDK 0.9.0 version, the library files added to the libs folder vary based on the protocol.

NELO SDK Required Additions nelo2-android-sdk-common-version name.jar
--> If using Thrift protocol, nelo2-android-sdk-thrift-version name.jar
--> If using HTTPS protocol, nelo2-android-sdk-https-version name.jar

[Figure – libs-stored NELO2 Android SDK]

Effective Log Search & Analytics NELO Android SDK settings

Initialize Effective Log Search & Analytics NELO Android SDK

There are two ways to initialize Effective Log Search & Analytics Android SDK.

1. Initialization method using the init method

   • When an app crash occurs in the same way as before, it transmits without creating a crash dialog.
   • It is better to be called from Application rather than Activity.

2. Used with @NeloConf annotation in Application Class

   • When an app crash occurs, it outputs a dialog that transfers crash logs according to user’s setting.

• How to initialize in Main Activity

public class MainActivity extends Activity {

    .....

    @Override

    protected void onCreate(Bundle savedInstanceState) {

        .....

        NeloLog.init(getApplication(), "elsa-col.ncloud.com", 10006, "__Project_ID__", "__Projectversion__");

        .....

    }

}

• How to initialize in 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 = "Effective Log Search & Analytics-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);
        .....
    }
}
.....

In addition, you need to add permissions to AndroidManifest.xml file. These privileges are required to get information such as network status, device information, mobile carrier, Logcat, etc.

.....
/** AndroidManifest.xml **/
    <!-- Internet access permission for Nelo log transfer (required) -->
    <uses-permission android:name="android.permission.INTERNET"/>

    <!-- Permission to access phone information such as Platform and Carrier (required) -->
    <uses-permission android:name="android.permission.READ_PHONE_STATE" />

    <!-- Permission to access network access status (required) -->
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

    <!-- Permission to save data on a file if the network is not accessed -->
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

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

      <!-- If you created an application to use Crash Report Dialog, you must set a name.-->
       <application ..... android:name="ApplicationName">
.....

       <!-- Receiver to be added to check network status and send logs only in WiFi mode -->
    <!-- If you use SendMode as All, you do not need to add it. -->
    <receiver android:name="com.nhncorp.nelo2.android.util.NetworkStatusReceiver">
        <intent-filter>
               <action android:name="android.net.conn.CONNECTIVITY_CHANGE"/>
        </intent-filter>
    </receiver>
.....

<!-- Activity to use Crash Report Dialog -->
<!-- You do not need to add CrashReportMode.DIALOG unless you use it. -->
<activity android:name="com.nhncorp.nelo2.android.CrashReportDialog"
    android:theme="@android:style/Theme.Dialog"
    android:launchMode="singleInstance"
    android:excludeFromRecents="true"
    android:finishOnTaskLaunch="true" />
.....

Use Effective Log Search & Analytics NELO2 Android SDK

This is the actual code sample using 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(),"Effective Log Search & Analytics-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
    }
.....

Details on NELO2 Android SDK API

It describes the details of each API provided by Effective Log Search & Analytics NELO Android SDK.

Initialization functions

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 information. In general, getApplication() is used.
• String reportServer: Effective Log Search & Analytics collector server addresses

  • If using Thrift protocol

    • Effective Log Search & Analytics collector server: elsa-col.ncloud.com

  • If using HTTPS protocol

    • Effective Log Search & Analytics collector server: https://elsa-col.ncloud.com/_store
• int serverPort: Port information of collector servers
  • Thrift: 10006
  • Https: 443
• String appId: Project ID registered in Effective Log Search & Analytics
• String appVersion: Version information of an app to be transferred
• String userId: User ID to be sent (optional)

Example

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

Description

• Functions to initialize NeloLog. NeloLog must be initialized before using NeloLog to be run normally. Initialization is required only once.
• You cannot use Crash Report Dialog when initialized by the above method in Activity.

boolean init (Application application)

Parameters

• Application application: Android application information. In general, getApplication() is used.

Example

• Set other metrics using @NeloConf annotation as shown below.
• It must be called from Application, not in Activity.
• In order to use Crash Report Dialog, it must be initialized by the above method.

@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);

        .....

    }

}

.....

Description

• Functions to initialize NeloLog. It must be used with @NeloConf annotation to make settings.

System Field setting functions

static void setUserID(String userID)

static void setUserID(String instanceName, String userID)

Parameters

• String userID: User ID

Example

NeloLog.setUserID("test");

Description

• It is used to set a user ID. The set value is transferred in the same way in all subsequent logs.

static void setLogSource(String logSource)

static void setLogSource(String instanceName, String logSource)

Parameters

• String logSource: logSource information settings

Example

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

Description

• API to set NELO2 logSource information. The set value is transferred in the same way in all subsequent logs.

static void setLogType(String logType)

static void setLogType(String instanceName, String logType)

Parameters

• String logType: logType information settings

Example

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

Description

• API to set Effective Log Search & Analytics logType information. The set value is transferred in the same way in all subsequent logs.

Log transfer functions

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: A value mapped to NELO2 errorCode field
• String message: A value mapped to NELO2 body
• String location: Enter a location for a log to occur.

Example

NeloLog.error("test","Test value","location");
NeloLog.debug("test 2","Test value ")

Description

• Functions provided to be transferred by each error level.

Log transfer functions (Including exceptions)

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)

// For dynamic instance log transfer
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 Information
• String errorCode: A value mapped to Effective Log Search & Analytics errorCode field
• String message: A value mapped to Effective Log Search & Analytics body
• String location: Enter a location for a log to occur.

Example

try{

    int a = 10 / 0;

} catch (Exception e) {

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

}

Description

• Functions provided to be transferred by each error level.
• If no location information is set, Throwable will save the location of error occurrence as the location.
• When setting Throwable information, a field called Cause is stored, and a value of getCause() is saved.

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

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

Parameters

• Throwable t: Exception Information
• String errorCode: A value mapped to NELO2 errorCode field
• String message: A value mapped to NELO2 body
• String location: Enter a location for a log to occur.

Example

try{
    int a = 10 / 0;

} catch (Exception e) {

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

}

Description

• As soon as a user calls a crash function, a crash log is sent to Nelo.
• DmpData field delivered that is the same as crash logs.
• Avoid frequent calls unless necessary for app performance.

Crash callback

static void setNeloCrashCallback(NeloCrashCallback neloCrashCallback)

Parameters

• NeloCrashCallback neloCrashCallback: Function called when a crash occurs
  • boolean beforeSendNeloCrash()
    • Determine whether to send a crash log when a crash occurs as a return value.
  • boolean beforeInstanceSendNeloCrash(String instanceName) (Currently not supported.)
    • If you have created multiple instances and want only specific instances to send logs, compare with the instanceName value to determine the return value.
    • If it is initialized with NeloLog.init(), you can name it “Nelo2Constants.NELO_DEFAULT_INSTANCE_NAME”.
  • void finishInstanceSendNeloCrash(String instanceName) (Currently not supported.)
    • Function called after the log transfer of a specific instance
  • void finishSendNeloCrash()
    • Function called after the all crash transfers

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 ]]__________________");
        }
    });

Description

• Callback function that can call a user-defined function before the crash transfer in case of crash occurred.

Option setting functions

static boolean getNeloEnable()

static void setNeloEnable(boolean enabled)

Parameters

• boolean enabled: Set whether to enable Nelo.

Description

• If set to false, all Nelo log transfers will be aborted.
• Saving as a file does not work either.

static boolean getDebug()

static void setDebug(boolean enabled)

Parameters

• boolean enabled: Set whether to use Debug mode.

Description

• When Debug mode is enabled, detailed logs are recorded on Logcat.
• Set it to true only in the test environment and false in the operating environment.

static CrashReportMode getCrashMode()

static void setCrashMode(CrashReportMode mode)

Parameters

• CrashReportMode mode: Set a way to send a crash when an app crash occurs.

Description

• Associated with CrashReportDialog in AndroidManifest.xml file.
• CrashReportMode
  • CrashReportMode.NONE: Do not send a crash when an app crash occurs.
  • CrashReportMode.SLIENT: Send a crash log to NELO without notifying a user when an app crash occurs.
  • CrashReportMode.DIALOG: Show Crash Report Dialog to a user and send a crash only if the user selects OK when an app crash occurs.
    • Associated with the following metrics of @NeloConf annotation.
      • resDialogTitle: Title of Crash Report Dialog. String ID defined in res/values/string.xml.
      • resDialogText: Description of Crash Report Dialog. String ID defined in res/values/string.xml.

static NeloSendMode getNeloSendMOde()

static void setNeloSendMOde(NeloSendMode mode)

Parameters

• NeloSendMode mode: Set Nelo transfer method.

Description

• Associated with NetworkStatusReceiver in AndroidManifest.xml file.

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: The maximum size of a file to be stored in Nelo

Description

• The default value is 1Mb (1024 * 1024 byte).
• If the stored value is greater than max_file_size, delete past data to save it.

static void flush()

Description

• Send logs stored in a queue and file to NELO server.

static long getAllNeloSaveLogFileSize()

Description

• The total size of a file being currently used by NeloLog returned.

static boolean clearSavedNeloLogFile(boolean flushFile)

Parameters

• boolean flushFile: Read an old file to determine whether to send it to a server.

Description

• Use a name generated by hash with InstanceName and a project name as a file name.
• If an existing file needs to be deleted due to the project name/instance name change, you can call the above function.
• If flushFile value is true, all contents should be read and saved in a queue before deleting the old file.
• The default value for flushFile is true.

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

Parameters

• Nelo2LogLevel loglevel : Send only logs with at least the loglevel to Nelo.

Description

• The default value is Nelo2LogLevel.DEBUG.
• LogLevel filter value ignored if a user explicitly requests to send a log to a server, such as crash or flush.

FAQ

1. What if I want to send all the logs stored in a file to Effective Log Search & Analytics server when a crash occurs?

You can call NeloLog.flush() from the finishSendNeloCrash() function out of CrashCallback functions to send all the logs in a file and queue to Nelo server.

2. A “New User Install App” log, which I never sent, was transmitted.

“New User Install App” log is sent once an app is first installed.

3. Note when proguard is enabled

If you obfuscate ThriftConnector or HttpsConnector when the proguard is enabled, the log transfer will fail as the corresponding class cannot be found. These classes should be excluded when enabling the proguard.

4. "Could not find class 'com.nhncorp.nelo2.android.HttpsConnector', referenced from method com.nhncorp.nelo2.android.Nelo2ConnectorFactory.getConnector" error has occurred.

In the Install Effective Log Search & Analytics Android SDK, we mentioned that SDK is divided into three parts: common, thrift, and https. This warning is generated when the https part is not added. You can ignore it when sending by thrift only.