All events have a fingerprint. Events with the same fingerprint are grouped together into an issue.
By default, Sentry will run one of our built-in grouping algorithms to generate a fingerprint based on information available within the event such as
message. To extend the default grouping behavior or change it completely, you can use a combination of the following options:
- In your SDK, using SDK Fingerprinting
- In your project, using Fingerprint Rules
- In your project, using Stack Trace Rules
Stack trace rules can work as a combination of both SDK and project settings. As a result, we maintain the documentation in one location.
Each time default grouping behavior is modified, Sentry releases it as a new version. As a result, modifications to the default behavior do not affect the grouping of existing issues.
When you create a Sentry project, the most recent version of the grouping algorithm is automatically selected. This ensures that grouping behavior is consistent within a project.
To upgrade an existing project to a new grouping algorithm version, navigate to Settings > Projects > [project] > Issue Grouping > Upgrade Grouping. After upgrading to a new grouping algorithm, you will very likely see new groups being created.
All versions consider the
When Sentry detects a stack trace in the event data (either directly or as part of an exception), the grouping is effectively based entirely on the stack trace.
The first and most crucial part is that Sentry only groups by stack trace frames that the SDK reports and associates with your application. Not all SDKs report this, but when that information is provided, it’s used for grouping. This means that if two stack traces differ only in parts of the stack that are unrelated to the application, those stack traces will still be grouped together.
Depending on the information available, the following data can be used for each stack trace frame:
- Module name
- Normalized filename (with revision hashes, and so forth, removed)
- Normalized context line (essentially a cleaned up version of the source code of the affected line, if provided)
This grouping usually works well, but two specific situations can throw it off:
- Modifying your stack trace by introducing a new level through decorators changes your stack trace, so the grouping will also change. To handle this, many SDKs support hiding irrelevant stack trace frames. For example, the Python SDK will skip all stack frames with a local variable called
__traceback_hide__set to True.
If the stack trace is not available, but exception information is, then the grouping will consider the
value of the exception if both pieces of data are present on the event. This grouping is a lot less reliable because of changing error messages.
Grouping falls back to messages if the stack trace,
value are not available. When this happens, the grouping algorithm will try to use the message without any parameters. If that is not available, the grouping algorithm will use the full message attribute.
For more details, see Grouping Issues Best Practices.