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 specifications that are the cause of common exceptions. Collection of exception data is done through the RUISDK.TrackException method.

RUIResult RUISDK.TrackException (RUIExceptionEvent exceptionData, String sessionID = “”)

Logs an exception event with the supplied data. NOTE: Different than V4 of the RUI (Trackerbird) SDK, TrackException() 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 StartSession, 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 is 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 UTF8 characters.
* Validation: Cannot be empty.

RUISDK.TrackException can be called between RUISDK.StartSDK and RUISDK.StopSDK, and can be called zero or more times.

RUISDK.TrackException can be called while a New Registration is being performed (RUISDK.CreateConfig, RUISDK.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.

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

Parameters:

exceptionData (RUIExceptionEvent) - The exception data to log:

className  - Class catching exception.  Content conditioning and validation rules above.
methodName - Method catching exception.  Content conditioning and validation rules above.
message    - Exception message.  No content restrictions, but trimmed to a maximum length determined by the RUI Server.
stackTrace - Exception stack trace.  No content restrictions, but trimmed to a maximum length determined by the RUI Server.

sessionID (String) - An optional session ID.

Return Type:

RUIState enum values below:

* ok                                     Synchronous functionality successful.
* sdkInternalErrorFatal                  Irrecoverable internal fatal error.  No further API calls should be made.
* sdkAborted                             A required New Registration has failed, and hence the SDK is aborted.  StopSDK and RUISDK destructor are possible.
* suspended                              Instance has been instructed by RUI Server to back-off.  Will return to Running once back-off cleared.
* permanentlyDisabled                    Instance has been instructed by RUI Server to disable.  This is permanent, irrecoverable state.
* sdkOptedOut                            Instance has been instructed by the application to opt-out.
* configNotCreated                       Configuration has not been successfully created.
* sdkNotStarted                          SDK has not been successfully started.
* sdkAlreadyStopped                      SDK has already been successfully stopped.
* invalidSessionIDExpectedEmpty          The sessionID is expected to be empty, and it was not.
* invalidSessionIDTooShort               The sessionID violates its allowable minimum length.
* invalidSessionIDTooLong                The sessionID violates its allowable maximum length.
* invalidSessionIDNotActive              The sessionID is not currently in use.
* invalidParameterExpectedNonEmpty       Some API parameter is expected to be non-empty, and is not.

Code Example:

Placing RUISDK.ExceptionTrack inside of a try catch statement so that Revulytics Usage Intelligence can record it

// Create instance
bool registerDefaultReachOut = true;
String ruiSDKDLLPath = "<path to Revulytics Usage Intelligence SDK .NET library>";
mySDK = new RUISDK(registerDefaultReachOut, ruiSDKDLLPath);
// Other initialization.....


private void btnSave_Click(object sender, EventArgs e)
{
    try
    {
        //Save Button Logic
    }
    catch (Exception ex)
    {
        RUIExceptionEvent myRUIExceptionData = new RUIExceptionEvent("Form1", ex.TargetSite, ex.Message, ex.StackTrace);
        mySDK.TrackException(myRUIExceptionData);
    }
}