June 23rd, 2017 • By Jesse Gibbs
With the recent announcement of support for manual merging, there are now multiple ways to combine occurrences of errors into a single item.
Before merging was an option, if the default fingerprinting algorithm didn’t combine occurrences the way you wanted, then you needed to define custom fingerprinting rules. Custom fingerprinting rules require you to learn our JSON-based rule syntax, and that could be a deterrent against setting them up.
Now that you can easily merge errors via the UI, is there still value in setting up custom fingerprinting rules? Absolutely, and this blog post will explain why!
To understand merging vs. custom fingerprinting rules, it helps to first look at how Rollbar combines occurrences of errors.
Minus a few tweaks we’ve made over the years to optimize results, our default algorithm works as follows:
The resulting SHA1 hash is what we call the ‘fingerprint’ of the error. All occurrences that have the same fingerprint will be combined into a single item.
The default behavior can be changed to include the exception message, or any other occurrence data, when calculating the fingerprint too. This will result in more unique errors in your Rollbar projects, so use it carefully.
The default fingerprinting algorithm is a good start and may be sufficient for many projects, but often you’ll want to tweak the behavior. Some of the most common reasons for creating custom fingerprinting rules include:
Custom fingerprinting rules allow you to specify precise logic for combining occurrences and generating fingerprints using a JSON-based syntax:
{% assign body = site.data.docs.custom-grouping.body %}
[
{"condition": {"path": "body.trace.exception.class", "eq": "TimeoutError"},
"fingerprint": "timeout-error"
},
{"condition": {"path": "body.trace.exception.class", "eq": "IndexError"},
"fingerprint": "index-error-{{body.trace.exception.message}}"
}
]
In the example above, all occurrences of TimeoutError
will be combined into a single item while occurrences of IndexError
will be combined only if they have the same exception message.
Custom fingerprinting rules allow for very sophisticated fingerprinting behavior, but also require a bit of learning to work with the JSON syntax. In addition to the learning curve, custom fingerprinting rules have the following limitations:
If there are errors in your project that were not combined by the default fingerprinting algorithm nor your custom fingerprinting rules, then you can manually merge them together.
In addition to the simplicity of merging via the UI, it also has the advantage of allowing you to un-merge in case you made a mistake or change your mind about how to organize your errors.
For more information about merging, check out our announcement blog post and our merging docs.
Now that you can merge errors in the UI, why go to the trouble of creating custom fingerprinting rules?
When errors are merged via the UI, all past and future occurrences that have the same fingerprint as one of the member items will be added to the resulting group item.
Suppose that you want all occurrences of OperationalError
to be tracked as a single item. If you just merge all the existing OperationalError items, then any future OperationalError that has a different stack trace is going to be treated as a different error because the default algorithm assigns a different fingerprint, and you’ll need to continually merge every new OperationalError with the old ones.
If you create a custom merging rule to assign the same fingerprint to all OperationalError occurrences, then you will not have to have to merge any future occurrences because the system will do it automatically.
Suppose you’ve already got several different OperationalErrors, and you want to track all past and future occurrences as a single item. The steps to do this are:
1. Merge all your existing OperationalErrors into one merge item.
2. Create a custom fingerprinting rule to combine the OperationalErrors and use the fingerprint of the group item (In this case #311
) created in the previous step.
[
{"condition": {"path": "body.trace.exception.class", "eq": "OperationalError"},
"fingerprint": "group-item-311"
}
]
Once this custom fingerprinting rule is saved, every occurrence of an OperationalError
will be added to item #311
This is just one among many use cases that illustrate why custom fingerprinting rules continue to be useful along with merging.
If you haven’t already, signup for a 14-day free trial of Rollbar and let us help you take control of your application error monitoring. :-)