Developer Zone

Exception Tracking

Revulytics 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, Revulytics 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.

RUIRESULT ruiTrackException(RUIINSTANCE* ruiInstance, RUIEXCEPTIONEVENT exceptionData, const char* sessionID)

Logs an exception event with the supplied data. NOTE: Different than V4 of the RUI (Trackerbird) SDK, ruiTrackException() accepts a sessionID parameter. The usage requirements of the sessionID parameter are the following:

* multiSessionEnabled = false - sessionID must be empty.
* multiSessionEnabled = true  - sessionID must be a current valid value used in ruiStartSession(), or it can be empty.
                                This is different than normal event tracking APIs, whereby an empty value is not allowed.

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 at most 128 UTF-8 characters.
  • Validation: Cannot be empty.

ruiTrackException() can be called between ruiStartSDK() and ruiStopSDK(), and can be called zero or more times.

ruiTrackException() can be called while a New Registration is being performed (ruiCreateConfig(), ruiStartSDK()). 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.

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

The RUIExecptionEvent class contains the following fields:

  • const char* className;
  • const char* methodName;
  • const char* exceptionMessage;
  • const char* stackTrace;

Parameters:

ruiInstance (RUIINSTANCE*) - Pointer to the RUI instance created via ruiCreateInstance()

event (RUIExecptionEvent) - A struct containing the exception event data to be logged.

sessionID (const char*) - An optional session ID complying with above usage (content conditioning and validation rules in ruiStartSession()). Empty if not used.

Returns:One of the return status constants below.
* RUI_OK - Synchronous functionality successful.
* RUI_INVALID_SDK_OBJECT - SDK Instance parameter is NULL or invalid.
* RUI_SDK_INTERNAL_ERROR_FATAL - Irrecoverable internal fatal error.  No further API calls should be made.
* RUI_SDK_ABORTED - A required New Registration has failed, and hence the SDK is aborted.  ruiStopSDK and ruiDestroyInstance are possible.
* RUI_SDK_SUSPENDED - The RUI Server has instructed a temporary back-off.
* RUI_SDK_PERMANENTLY_DISABLED - The RUI Server has instructed a permanent disable.
* RUI_SDK_OPTED_OUT - Instance has been instructed by the application to opt-out.
* RUI_CONFIG_NOT_CREATED - Configuration has not been successfully created.
* RUI_SDK_NOT_STARTED - SDK has not been successfully started.
* RUI_SDK_ALREADY_STOPPED - SDK has already been successfully stopped.
* RUI_INVALID_SESSION_ID_EXPECTED_EMPTY - The sessionID is expected to be empty, and it was not.
* RUI_INVALID_SESSION_ID_TOO_SHORT - The sessionID violates its allowable minimum length.
* RUI_INVALID_SESSION_ID_TOO_LONG - The sessionID violates its allowable maximum length.
* RUI_INVALID_SESSION_ID_NOT_ACTIVE - The sessionID is not currently in use.
* RUI_INVALID_PARAMETER_EXPECTED_NON_EMPTY - Some API parameter is expected to be non-empty, and is not.