Customizing Deduplication Rules
Backtrace provides a programmable callstack based fingerprinting system, more commonly called our deduplication system. You can find more detailed information about our deduplication system here.
In summary, this system allows Backtrace to group errors where root cause can be extrapolated from the contents of one or more faulting callstacks. A callstack may have differences for the same bug due to reasons like non-determinism, optimizations and recursion. To account for this, Backtrace built a programmable rules based system that can efficiently evaluate each frame in a callstack to decide if it needs removal or transformation to be normalized for more accurate grouping. We have developed a set of rules that are provided out of the box from common frameworks and platforms. (We call this the Backtrace Ruleset).
Backtrace customers on the Enterprise plan can now easily add their own rulesets and rules to best fit their individual use cases and environments. Features include:
- Manage rulesets for a project. A ruleset is evaluated for an incoming callstack to a specified project, and consists of a set of rules for evaluation and an optional language or OS that the rules apply to.
- Manage rules in a ruleset: A rule consists of a reg-ex that can be evaluated on a given frame in a callstack, and a set of actions that should occur if the expression evaluates to true. The actions are extensive, including ability to rename functions, skip frames in current object file, ignore current frame, terminate after frame, add attribute to signature values, and more. The point is that you can create rules to normalize for various optimizations and code paths for a given callstack, optionally limiting to specific language or operating systems.
- Test rulesets to preview actions they would take on an incoming callstack.
Deduplication rules can be access under Project Settings.
Deduplication Settings for a Project
Under Project Settings, you'll see a Deduplication section. This section will list for you the named rulesets that are associated with the project, in order of their execution. You will see a default and un-editable ruleset, called the Backtrace Ruleset. These are rules we automatically process for all incoming callstacks (Note you can't view or manage this - it's part of our secret sauce!). You can add and manage additional custom rulesets for the project. See a screenshot below for an out of the box view of project with no custom deduplication rules.
Create a Custom Ruleset
Click Add new ruleset to create a new ruleset.
As you can see, each ruleset consists of a name, an optional set or languages or OS that the rules within should apply to, an enable/disable toggle, and the ability to add a set of rules that should be evaluated.
Manage Rules in Rulesets
A rule consists of a set of predicates (IF statements to evaluate matches against functions, objects or sources using regex), and a set of actions to take IF the statements evaluate TRUE. Click Add a rule to add a new rule.
More Examples of Rules
Below is an example of a more complex rule, with three predicates and a list of all available actions:
The second example shows two rules for a rule set. The first rule has 3 actions, including ignoring and skipping frames, and setting a new attribute. The second rule shows how to perform a replacement of a function name.
Enable and Disable
You can quickly enable or disable rules in the toggle menu.
After creating a ruleset, you can test the output of the deduplication engine with an existing crash report (or error) in the system. Just enter the Instance ID of the crash report in the Ruleset Testing field. (You can get an instance ID from the Debug view. You will see the Ruleset Testing field after you have saved a Ruleset).