Skip to content

Instantly share code, notes, and snippets.

@alexaloni
Created November 12, 2018 17:22
Show Gist options
  • Save alexaloni/5b4d069d17de0dabe384ea30e3f21dfe to your computer and use it in GitHub Desktop.
Save alexaloni/5b4d069d17de0dabe384ea30e3f21dfe to your computer and use it in GitHub Desktop.

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>
  1. 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"
 }
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment