Merging versus Custom Fingerprinting

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!

Rollbar’s Default Fingerprinting Algorithm

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:

• Combine the filenames and method names from all of the stack frames
• Append the exception class name
• Take the SHA1 hash of the result

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.

Custom Fingerprinting Rules

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:

• You want to combine all occurrences of a certain exception class into one item, regardless of the stack trace.
• For some (but not all) types of errors, you want to have more unique items created (e.g. include the exception message or the server hostname).

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:

• Custom fingerprinting rules only apply to future occurrences, not those which already exist in your project.
• Once occurrences are combined by a custom fingerprinting rule, they cannot be split into separate items.

Merging

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.

When to use custom fingerprinting rules vs. when to merge

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