Exception Tracking

Usage Intelligence is able to collect runtime exceptions from your application and then produce reports on the exceptions that were collected. Once an exception is tracked, Usage Intelligence will also save a snapshot of the current machine architecture so that you can later (through the on-line exception browser within the Usage Intelligence dashboard) investigate the exception details and pinpoint any specific OS or architecture related information that are the cause of common exceptions. Collection of exception data is done through the trackException() method.

The trackException() function logs an exception event with the supplied data.

trackException() can be called between startSDK() and stopSDK(), and can be called zero or more times.

trackException() can be called while a New Registration is being performed (createConfig(), startSDK()). However, the event data is not written to the log file until the New Registration completes, and if the New Registration fails, the data will be lost.

trackException() is an asynchronous function, returning immediately with further functionality executed on separate thread(s).

trackException()

RUIResult trackException(RUIExceptionEvent exceptionData)¶

RUIResult trackException(RUIExceptionEvent exceptionData, String sessionID)

Parameters

The trackException() function has the following parameters.

trackException() Parameters

Parameter	Description
exceptionData (RUIExceptionEvent)	The exception data to log: • className—Class catching exception. • methodName—Method catching exception. • exceptionMessage—Exception message. No content restrictions, but trimmed to a maximum length determined by the Server. • stackTrace—Exception stack trace. No content restrictions, but trimmed to a maximum length determined by the Server. The content of exceptionData.className and exceptionData.methodName are conditioned and validated (after conditioning) with the following rules: • Conditioning—All leading white space is removed. • Conditioning—All trailing white space is removed. • Conditioning—All internal white spaces other than space characters (‘ ‘) are removed. • Conditioning—Trimmed to a maximum of 128 UTF-8 characters. • Validation—Cannot be empty.
sessionID (String)	An optional session ID. If not used, use method without sessionID. Different than V4 of the Usage Intelligence (Trackerbird) SDK, trackException() accepts a sessionID parameter. The usage requirements of the sessionID parameter are the following: • If multiple user sessions are supported within the application (multiSessionEnabled = true), sessionID must be a current valid value used in startSession(), or it can be empty. This is different than normal event tracking APIs, whereby an empty value is not allowed. • If the application supports only a single session (multiSessionEnabled = false), then sessionID must be empty.

Returns

The trackException() function returns one of the following RUIState enum values:

trackException() Returns

Return	Description
OK	Synchronous functionality successful.
SDK_INTERNAL_ERROR_FATAL	Irrecoverable internal fatal error. No further API calls should be made.
SDK_ABORTED	A required New Registration has failed, and hence the SDK is aborted. stopSDK() is possible.
SDK_PERMANENTLY_DISABLED	The Server has instructed a permanent disable.
SDK_SUSPENDED	The Server has instructed a temporary back-off.
SDK_OPTED_OUT	Instance has been instructed by the application to opt-out.
CONFIG_NOT_CREATED	Configuration has not been successfully created.
SDK_ALREADY_STOPPED	SDK has already been successfully stopped.
SDK_NOT_STARTED	SDK has not been successfully started.
FUNCTION_NOT_AVAIL	Function is not available.
INVALID_SESSION_ID_EXPECTED_NON_EMPTY	The sessionID is expected to be empty, and it was not.
INVALID_SESSION_ID_TOO_SHORT	The sessionID violates its allowable minimum length.
INVALID_SESSION_ID_TOO_LONG	The sessionID violates its allowable maximum length.
INVALID_SESSION_ID_NOT_ACTIVE	The sessionID is not currently in use.

Code Example

The following is an example of placing ExceptionTrack inside of a try catch statement so that Usage Intelligence can record it.

// Create instance

boolean registerDefaultReachOut = false;  // No default ReachOut handler for Java SDK

mySDK = new SDKImpl(registerDefaultReachOut);

// Other initialization.....

 

private void btnSave_Click()

{

    try

    {

        //Save Button Logic

    }

    catch (Exception ex)

    {

        RUIExceptionEvent myRUIExceptionData = new RUIExceptionEvent("MyApplication", "btnSave_Click", ex.getMessage(), ex.getStackTrace().toString());

        mySDK.trackException(myRUIExceptionData);

    }

}