Snappoints.md

Snapshot Debugger snappoint collection plans

To provide more granular control over what exceptions are getting collected or excluded from processing, snapshot debugger provides an option for user to specify a configuration file with list of snappoint collection plans.

Snappoint collection plan is a collection of matching conditions user can specify to capture specific exceptions. In addition to matching options, plan also defines what to do with the exception once the conditions are met, whether it should be collected or completely ignored (skipped).

For any exceptions that are collected plan has an option to configure what type of snappoint action to perform.

Snappoint plan's match options can be combined, for instance we can capture any exceptions with specific HResult and certain exception type and message details. We can filter on exception type and callstack details (throwing type, method).

Configure Snapshot Debugger snappoint collection plans

1. Add two new properties in ApplicationInsights.config properties under SnapshotCollectorTelemetryProcessor settings :
   • IsExceptionSnappointsEnabled - it should be set to true to enable snappoints support
   • ExceptionSnappointSettingsFile – full path to json configuration file that contains snappoints. Path can contain environment variables.

<TelemetryProcessors>
    <Add Type="Microsoft.ApplicationInsights.SnapshotCollector.SnapshotCollectorTelemetryProcessor, Microsoft.ApplicationInsights.SnapshotCollector">
    <!-- The default is true, but you can disable Snapshot Debugging by setting it to false -->
    <IsEnabled>true</IsEnabled>
     <!-- configuration flag to enable or disable filtering of exceptions, this is feature is disabled by default, set it to true to enable -->
    <IsExceptionSnappointsEnabled>true</IsExceptionSnappointsEnabled>
     <!-- Specifies json config file with exception snappoint setting-->
    <ExceptionSnappointSettingsFile>%appdata%\snappoints.json</ExceptionSnappointSettingsFile>

    ...
    </Add>
</TelemetryProcessors>

2. Create json file following an example enclosed below:

{
  "exceptionSnappoints": [
    {
      "action": "CaptureFullDump",
      "id": "efe1fc1d-c232-464b-85a3-1b7614fb9f42",
      "name": "[Name of snappoint collection plan]",
      "snappointType": "Collect",
      "callstackInfo": null,
      "exceptionInfo": {
        "exceptionCode": 0,
        "message": "Invalid User",
        "messageMatch": "Contains",
        "typeMatch": "Contains",
        "typeName": "AccessDenied"
      },
      "matchOptions": "MatchOnExceptionType, MatchOnExceptionMessage",
      "maxSnapshotsLimit": 5,
      "problemId": null
    },
    {
      "action": "CaptureFullDump",
      "id": "ade5af6b-3ea9-4c17-b747-7452bfba3ae4",
      "name": "[Name of snappoint collection plan 2]",
      "snappointType": "Skip",
      "callstackInfo": {
        "callstackDepthLimit": 1,
        "methodSignature": "Login",
        "methodSignatureMatch": "Contains",
        "typeSignature": "Namespace.",
        "typeSignatureMatch": "Contains"
      },
      "exceptionInfo": null,
      "matchOptions": "MatchOnCallstack",
      "maxSnapshotsLimit": 2,
      "problemId": null
    }
  ],
  "version": "1.0.0"
}

Required properties

version = "1.0.0" – current version of the exception snappoint settings

For each exception snappoint collection plan block :

id - should be unique guid for collection plan

maxSnapshotsLimit - explicit number of snapshots to capture for the collection plan, if nothing is specified it would be set to value of MaximumSnapshotsRequired from snapshot configuration settings.

All other properties and properties blocks (callstackInfo and exceptionInfo) are optional and can be specified only when matchingOptions would include matching options that require it.

For example :

• problemId should be specified when matchOptions would include MatchOnProblemId as one of matching options, otherwise it can be completely ignored or set to null.
• callstackInfo should be included when matchOptions would include MatchOnCallstack
• exceptionInfo should be included when matchOptions would include any or all matching options MatchOnExceptionType, MatchOnExceptionCode, MatchOnExceptionMessage .

Configuration options

Matching Options

matchOptions – is a flags property which defines what matching options can be applied on the processed exception. User can combine multiple matching options in the same exception snappoint block. All of the specified options should match in order for collection process to proceed with collection plan actions. Exceptions that didnt meet all the matching options of any plans would be processed as exceptions without explicit snappoint collection plan. Matching options should be listed a comma delimited list as shown in next examples:

• To match on problemId and callstack method, user should set:

  "matchOptions" = "MatchOnProblemId, MatchOnCallstack"

• To match on exception type and exception message, user can set:

  "matchOptions" = "MatchOnExceptionType, MatchOnExceptionMessage"

Value	Notes
MatchOnProblemId	Match on problem Id , it can be obtained from Failures / Exception Blade
MatchOnExceptionType	Match on exception object CLR Type
MatchOnExceptionMessage	Exception object message properties will be compared with provided value based on the Match Type Operator.
MatchOnExceptionCode	Exception error code will be compared with specified error code
MatchOnCallstack	Exception callstack will be evaluated to match throwing object CLR type and method name based on Match Type Operator
CaptureAll	(Default) Matches all incoming exceptions ,if user doesnt specify matchingOptions in snappoint collection plan block, it would capture all exceptions regardless what other properties were defined in the plan json block

Snappoint Type

snappointType - property defines what should be done with the exception once the matching conditions have been identified.

Value	Notes
Collect	(Default) It is a default behavior of the exception snappoint. It would perform collection of exception details based on the specified snappoint action type.
Skip	Skip snappoint type is used in case user would like to exclude the exception from collection and uploading

Match Type

Match type defines what kind of string comparison should be applied on the targeted string value

Value	Notes
Exact	(Default) would perform case sensitive comparison of two strings for exact match
Contains	would check whether provided string value is a substring of targeted string
Regex	would use regular expression match to check whether provided expression has matches in the targeted string

Snappoint Action

action - element determines what type of collection activity should be executed on the exception with all matching conditions. The only supported option at the moment is "CaptureFullDump".

Value	Notes
CaptureFullDump	(Default) Capture full user dump for matching exception snappoint

Callstack Information Block

callstackInfo - is a collection of matching settings that will be applied on the exception callstack. User must to include a MatchOnCallstack as one of the matching options to allow matching on callstack details.

Property	Type	Default	Notes
callstackDepthLimit	int	0	Number of exception callstack frames to iterate to find the match
typeSignature	string		Value to match against full CLR type name of the object whose method threw an exception. It will be applied based on the typeSignatureMatch operator used
typeSignatureMatch	Match Type	Exact	String comparison operator. It would perform a comparison of throwing method declaring CLR object full type name against a value provided in the type signature property. It is case sensitive.
methodSignature	string		Value to match against method name that threw an exception. It will be applied based on the methodSignatureMatch operator used
methodSignatureMatch	Match Type	Exact	String comparison operator. It would perform comparison of throwing callstack method names against method signature value provided, starting from the top frame up to the frame with the match or until the callstack depth (callstackDepthLimit) limit is exceeded. It is case sensitive.

The example of the callstack information block below would capture all exceptions whose first 2 (0 and 1) frames of the callstack would contain a call from a type that contains (or starts with) "Namespace.AuthProviders" and "Authorize" method name.

 "callstackInfo": {
        "callstackDepthLimit": 1,
        "methodSignature": "Authorize",
        "methodSignatureMatch": "Exact",
        "typeSignature": "Namespace.AuthProviders",
        "typeSignatureMatch": "Contains"
      },

Exception Information Block

exceptionInfo - is a collection of matching settings that will be applied on exception type, message and error code. In order to use these settings user must to include any or all of the following matching options: MatchOnExceptionType , MatchOnExceptionMessage, MatchOnExceptionCode.

Property	Type	Default	Notes
typeName	string		Exception type name to compare against the thrown exception object type.
message	string		String value to compare against exception message property.
typeMatch	Match Type	Exact	Exception type name comparison operator. It would perform comparison of exception object full type against a value provided in the typeName property. It is case sensitive.
messageMatch	Match Type	Exact	Exception message comparison operator.
exceptionCode	int	0	Exception code (hresult) to compare against error code of the thrown exception

The exception infomation block below would capture any exceptions with type name "Microsoft.MetadirectoryServices.AccessDeniedException":

 "exceptionInfo": {
        "typeMatch": "Exact",
        "typeName": "Microsoft.MetadirectoryServices.AccessDeniedException"
      },

The next example would capture any exceptions of type that contains (or starts with) "CustomerNameSpace." and includes "[PII]:" in the message property:

 "exceptionInfo": {
        "message": "[PII]:",
        "messageMatch": "Contains",
        "typeMatch": "Contains",
        "typeName": "CustomerNameSpace."
      },

Examples of snappoint collection plan json blocks

• The exception snappoint collection plan defined below would capture any exception with Type name "System.AccessViolationException" and error code (hresult) 0x80070006

{
      "action": "CaptureFullDump", 
      "id": "efe1fc1d-c232-464b-85a3-1b7614fb9f42",
      "name": "Capture AccessDeniedException exceptions with error code  0x80070006",
      "snappointType": "Collect", 
      "exceptionInfo": {
        "exceptionCode": 0x80070006 , 
        "typeMatch": "Exact",
        "typeName": "System.AccessViolationException"
      },
      "matchOptions": "MatchOnExceptionType, MatchOnExceptionCode",
      "maxSnapshotsLimit": 5,
      "problemId": null
    },

• Following snappoint collection plan block would ignore or skip any exception that is thrown by a CLR object that contains Customer.Namespace. in the type name and throwing method that contains "Login" in its name. The check would be performed on two first frames of the exception callstack (0 & 1)

 {
     "action": "CaptureFullDump",
     "id": "ade5af6b-3ea9-4c17-b747-7452bfba3ae4",
     "name": "Skip any exceptions coming from namespace Customer.Namespace.* and method Login*",
     "snappointType": "Skip",
     "callstackInfo": {
       "callstackDepthLimit": 1,
       "methodSignature": "Login",
       "methodSignatureMatch": "Contains",
       "typeSignature": "Customer.Namespace.",
       "typeSignatureMatch": "Contains"
     },
     "matchOptions": "MatchOnExceptionType, MatchOnExceptionMessage"
 }

• Next snappoint collection plan block would capture exception of type System.AccessViolationException with error code 0x80070006 thrown by class & method = Customer.Namespace.UserAccount.ReadUserSettings. The check will be performed on top 2 frames of the calstack.

 {
     "action": "CaptureFullDump",
     "id": "ade5af6b-3ea9-4c17-b747-7452bfba3ae4",
     "name": "Skip any exceptions coming from namespace Customer.Namespace.* and any method that has Authorize in its name",
     "snappointType": "Collect",
     "exceptionInfo": {
       "exceptionCode": 0x80070006 , 
       "typeMatch": "Exact",
       "typeName": "System.AccessViolationException"
     },
     "callstackInfo": {
       "callstackDepthLimit": 1,
       "methodSignature": "ReadUserSettings",
       "methodSignatureMatch": "Exact",
       "typeSignature": "Customer.Namespace.UserAccount",
       "typeSignatureMatch": "Exact"
     },
     "matchOptions": "MatchOnExceptionType, MatchOnExceptionCode, MatchOnCallstack"
 }