Instance Data Collection Form

The Instance Data Collection form is used to define a set of rules that determines whether instance data should be collected for a specific instance. These rules are only used if instance data collection has been enabled in the session settings.

When collecting a snapshot, only the reference fields of an instance are needed in order to decide the relationship between instances, but, when viewing the details of an instance, the other fields of the instance may also contain useful information. To be able to present the values of all instance fields, all data of the instance must be collected. If all data are collected for all instances, then each snapshot will use as much memory as all the instances in the profiled process. To reduce the memory needed for instance data collection, a set of collection rules can be defined using this form.

The default instance collection setting is to collect instance data for all instances, as long as the size of each instance is less than 512 bytes. In many cases, this setting will provide a good balance between memory usage and available instance field values. In case this setting is not suitable, it is possible to change the rule or add additional rules. For example, if the profiled process contains a very large number of byte arrays, each less than 512 bytes, then adding a rule that excludes all byte arrays can significantly reduce the memory needed for the collected instance data.

Instance Collection Rules

A rule contains up to three parts:

•      The rule specification, which is one of the following.

o  Always collect instances of type:

o  Always collect instances of type, if size is less than:

o  Never collect instances of type:

o  Never collect instances of type, if size is greater than:

•      The instance size parameter. This part is only used if the specified rule needs an instance size.

•      The list of types to which this rule applies. Each entry can either be a type group or a specific type. A specific type is defined by the fully qualified type name and can optionally include all subclasses. A type group is one of the following:

o  <Any type>

This type group matches all types. If this group is part of the types list, there is no need to specify any other type.

o  <Array class>

This type group matches all array classes.

o  <Value type array class>

This type group matches all array classes containing value types.

o  <Reference array class>

This type group matches all array classes containing references.

Rule Evaluation

An instance matches a rule if:

1.   The type of the instance matches any type in the list of types in the rule.

2.   If the rule specification is “Always collect instances of type, if size is less than:” or “Never collect instances of type, if size is greater than:”, then the size parameter is compared with the size of the instance.

When deciding whether instance data should be collected for a specific instance, the instance is evaluated against the list of rules. Rules are evaluated one at a time, starting at the top rule. As soon as a rule matches the instance, the evaluation is stopped. If the instance was matched to a positive rule (“Always collect instances…”) then instance data will be collected for the instance. If a negative rule matched (“Never collect instances…”), then no instance data will be collected for the instance.

By using the fact that rule evaluation is stopped as soon as a rule is matched, it is possible to avoid the collection of instance data of certain types by adding a negative rule for these types. For example, consider the following rules:

 

Never collect instances of type, if size is greater than:

100 bytes

System.Byte[]

 

Always collect instances of type, if size is less than:

1000 bytes

<Any class>

These rules will cause instance data to be collected for all instances that have a size less than 1000 bytes, unless the instance is an array of bytes, in which case the instance has to be less than 100 bytes in order for instance data to be collected.

Editing Rules

To the left side of the form, the list of rules is presented. One of the rules is always selected, and the selected rule is indicated by a black border. A rule is selected by clicking on any of the controls in the rule.

The dropdown list of the rule can be used to select the rule’s specifications. If the rule needs a size parameter, a text box will also be included in the rule, allowing the size to be entered.

To the right side of the form, there is a list of available types and type groups, and above this list there is a text box in which type names can be entered. This list and the text box are used when adding types to a rule.

To add types to the rule, the types have to be specified using the list or by entering the type name manually in the text box above the list. It is possible to select more than one class in the list by using <Ctrl> and <Shift>. After specifying which types to add, click the “<=” button, and the types will be added to the selected rule. If the Include subtypes checkbox is checked, then all subclasses of the added type will also be included in the rule.

To remove types from a rule, select the rule and the types to remove, and then press the “=>” button.

It is possible to add and remove rules and to change the order of the rules by using the buttons at the bottom of the form:

•      Add rule

Adds a new rule below the selected rule.

•      Delete rule

Deletes the selected rule.

•      Move rule up

•      Moves the selected rule up in the list.

•      Move rule down

Moves the selected rule down in the list.