This page explains what exceptions are, how exceptions are interpreted and processed by the Analytics service and how the received exceptions are determined to be similar.
You can track exceptions through the analytics monitor when you have integrated it into your application. The precise API method to call is platform specific but it typically allows you to pass in an exception that has occurred in your software. On some platforms, where the concept on an exception is less well defined, the API allows you to pass in details to make up the contents of an exception.
If you are unfamiliar with the term exception you can generally think of an exception as an error condition in your software.
An exception is defined to consist of the following properties, when tracked through the API:
- An Exception Type that defines the general type of the exception.
- An Exception Message that is typically a simple overall textual description of what happen that might be generated by your application platform.
- A Stacktrace that provides a line-by-line list of where the exception happened in your application.
- An optional Context Message that allows you to add a custom message on an individual exception to provide context on what and why the exception occurred. This is typically more verbose and elaborate than the more general Exception Message.
The central part of processing the incoming exceptions is grouping similar exceptions into exception cases to allow for a quicker overview of the different exceptions that might have occurred in your software. Without this grouping you would have to go through each individual exception being reported to identify if it is a new or an already reported exception. By grouping similar exceptions into exception cases you can obtain a quicker overview and by accessing information on the frequency of each exception case it becomes easy to e.g. prioritize exceptions by frequency.
The process of identifying similar exceptions are performed based on the reported properties of each exception. The similarity is determined from the following criteria:
- The Exception Types must match
- The Stacktraces must match
Note that you can configure if the inner, or nested, exceptions should be considered in the similarity algorithm by configuring the application settings
Once an incoming exception has been processed it either generates a new exception case or matches an exception case. The exception cases can be accessed in the exception report and you can view the individual exception occurrences in the Samples tab in the exception details report. You can also configure the system to send you an email whenever a new exception case is created in the application notifications.
On some platforms you can provide a custom Exception Type and Stacktrace in order to influence the similarity algorithm. Some APIs allow you to directly pass in a type and a stacktrace (such as the c++ API and the COM API) while other platforms only allow you to do this by having you pass in your own custom created exception types that override the stacktrace being returned (such as the .NET API and the Java and Android API).
Once exception cases are created, they each become part of the exception lifecycle which dictates how exceptions are handled and visualized in the client.