Background

Backtrace provides a programmable call stack 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 call stacks. A call stack 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 call stack 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).

Feature Overview

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 call stack 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 call stack, 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 call stack, optionally limiting to specific language or operating systems.
• Test rulesets to preview actions they would take on an incoming call stack.

Feature Details

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 call stacks (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

Press the Add New Ruleset button 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. Press the Add a rule button 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:

2 Rules for a rules set. The first has 3 actions, including ignoring and skipping frames, and setting a new attribute. The second shows how to perform a replacement  of a function name.

Enable Disable

You can quickly enable or disable rules in the toggle menu.

Ruleset Testing

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).