Suspect Commits

Learn how to enable suspect commits, which will help you find the root cause of issues faster.

This feature is only applicable for error issues with debug information files, excluding source maps. Other categories of issues (such as performance issues) do not support this feature.

Suspect commits show you the most recent commit to the code in your stack trace. In the suspect commit information, we include the author of the commit and the pull request in which the commit was made.

When you've enabled suspect commits, we can tie together issues with the commits made in your code repository, including the following information:

  • Files observed in the stack trace
  • Files touched by those commits
  • Authors of those files

Suspect commits and suggested assignees are then displayed on the Issue Details page in sentry.io, as shown below.

In order to see suspect commits, you have to first upload source maps, (or your platform-specific files for mapping transformed source code to the original source). Check out the docs for your specific platform) to learn more. Be aware that Sentry will not display suspect commits for issues that were created prior to your integration being set up.

Suspect commits can be enabled using the following integrations:

In sentry.io:

  1. Go to Settings > Integrations.
  2. Click the integration you’d like to use.
  3. Configure the integration if you haven’t already.
  4. Add the repository you'd like to use.

Sentry will automatically try to set up code mappings on Python, JavaScript, Node.js, Ruby, PHP, and Go projects for organizations with the GitHub integration installed. However, you can still manually add code mappings if you choose to do so. Support for other languages and other source code integrations are planned.

  1. Go to Settings > Integrations > [Integration] > Configurations.
  2. Click the "Configure" button.
  3. Click the "Code Mappings" tab.
  4. Set up a code mapping for each project for which you want to enable suspect commits. To create a new code mapping, click Add Mapping.
  5. Fill out the form, then click Save Changes. Each form field is described below.

  • Project (required) - The Sentry project.
  • Repo (required) - The GitHub or GitLab repository associated with the Sentry project above. If you have more than one repository being used per Sentry project, you'll need multiple code mappings.
  • Branch (required) - The default branch of your code we fall back to if you don't have commit tracking set up.
  • Stack Trace Root and Source Code Root (optional) - See below for information on determining these values.

The following information is only valid for platforms which use traditional file paths. Platforms with package names require additional steps. For Java, read more in the page on source context.

First, navigate to a stack trace that you wish to map. Find an In App frame, which is denoted by a bubble on the right side of the frame. The filename will be shown as the first piece of text at the left hand side of the frame header. In this example, it is src/main.py.

Highlighting where in the UI to find the file name in the stack trace

For certain native platforms, the stack trace will look different. In cases like these, you can find the absolute path by hovering over the filename.

Highlighting where in the UI to find the file path for native stack traces

If you aren’t sure, you can look at the event JSON by clicking on the {} button in the event header. Find the text in the frame's filename or abs_path.

Highlighting where in the UI to find the event JSON

Next, locate the file seen in the stack trace with your source code provider (e.g. GitHub). In this example, the path is flask/src/main.py (empower is ignored since it is the name of the repo).

An example of a file in source control

Compare the file path from the stack trace with the path found in your source repository. In this example, the src/ folder in the stack trace matches the flask/src/ folder in the source code. Using that information, set the Stack Trace Root to src/ and the Source Code Root to flask/src/. This tells Sentry to replace all file paths beginning in src/ with flask/src/ when searching for the source code.

For best results, we recommend always providing a non-empty value for the Stack Trace Root when possible.

The first frame in the stack trace is considered suspect when looking at them top-down. If the first frame is not in-app, the next frame is considered suspect.

Follow along with the interactive demo below to see how to integrate your GitHub account and repository.

When you have a GitHub/GitLab integration and valid code mappings, Sentry will look at the stack trace of an issue and collect all in-app frames. For each in-app frame, Sentry checks the blame info for the exact file and line number. If the most recent commit is less than 1 year old, we consider it a suspect commit.

You can send us your commit data manually if:

  • You don’t want Sentry to connect to your repository.
  • Your organization doesn't have a GitHub or Gitlab integration.
  • Your integration has gotten disconnected.

Sentry will attempt to find suspect commits via your GitHub or GitLab integration by default. If this fails and you've set up the manual process, Sentry will fall back to using the release commit data to find suspect commits.

There are a few reasons why an issue might not have suspect commits:

  • The issue doesn't have a stack trace or doesn't have any in-app frames.
  • The stack trace doesn't have any in-app frames that match the code mappings.
  • The stack trace doesn't have any in-app frames with recent commits (less than 1 year old).
  • The code mappings for the project are incorrect.
  • The issue was created prior to the integration being set up.

Once suspect commit authors are identified, they're applied in the following ways:

On the Issue Details page, you'll see suggested assignees based on ownership rules matching the event, and suspect commits. You can manually assign the issue to a suggested assignee by selecting one from the dropdown.

Avatar icons of suggested assignees and ability to click on them for assignment.

You can automatically assign issues to their suspect commit authors by enabling the "Auto-assign to suspect commits" setting in [Project] > Settings > Ownership Rules.

Select from dropdown to automatically assign issues to their suspect commit authors.

If an issue has already been assigned manually, new events will not change the current assignee. If an issue has not been assigned and a suspect commit is found, Sentry assigns it to the commit author.

  • If auto-assignment is enabled but the suspect commit author is not in your Sentry organization, we will not be able to auto-assign the issue to them.

  • Auto-assignment may be skipped if a project is creating too many new issues at a given time due to rate limits. We'll try to auto-assign it the next time an event comes in for those skipped issues. If you are encountering this limit with non-recurring issues, you may want to take a look at issue grouping strategies.

Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").