Skip to content

GitLab

Error Tracking (FREE)

Introduced in GitLab 11.8.

Error Tracking allows developers to easily discover and view the errors that their application may be generating. By surfacing error information where the code is being developed, efficiency and awareness can be increased.

Sentry error tracking

Sentry is an open source error tracking system. GitLab allows administrators to connect Sentry to GitLab, to allow users to view a list of Sentry errors in GitLab.

Deploying Sentry

You can sign up to the cloud hosted Sentry, deploy your own on-premise instance, or use GitLab to install Sentry to a Kubernetes cluster. To make this easier, we are considering shipping Sentry with GitLab.

Enabling Sentry

GitLab provides an easy way to connect Sentry to your project. You need at least Maintainer permissions to enable the Sentry integration.

  1. Sign up to Sentry.io or deploy your own Sentry instance.
  2. Create a new Sentry project. For each GitLab project that you want to integrate, we recommend that you create a new Sentry project.
  3. Find or generate a Sentry auth token for your Sentry project. Make sure to give the token at least the following scopes: event:read, project:read, and event:write (for resolving events).
  4. In GitLab, enable error tracking:
    1. On the top bar, select Menu > Projects and find your project.
    2. On the left sidebar, select Monitor > Error Tracking.
    3. Select Enable error tracking.
  5. In GitLab, ensure error tracking is active.
    1. On the left sidebar, select Settings > Monitor.
    2. Expand Error Tracking.
    3. Ensure the Active checkbox is selected.
  6. In the Sentry API URL box, enter your Sentry hostname. For example, enter https://sentry.example.com. For the SaaS version of Sentry, the hostname is https://sentry.io.
  7. In the Auth Token box, enter the token you previously generated.
  8. To test the connection to Sentry and populate the Project dropdown, select Connect.
  9. From the Project list, choose a Sentry project to link to your GitLab project.
  10. Select Save changes.

You can now visit Monitor > Error Tracking in your project's sidebar to view a list of Sentry errors.

Enabling GitLab issues links

You may also want to enable Sentry's GitLab integration by following the steps in the Sentry documentation

Enable GitLab Runner

To configure GitLab Runner with Sentry, you must add the value for sentry_dsn to your GitLab Runner's config.toml configuration file, as referenced in GitLab Runner Advanced Configuration. While setting up Sentry, select Go if you're asked for the project type.

If you see the following error in your GitLab Runner logs, then you should specify the deprecated DSN in Sentry.io > Project Settings > Client Keys (DSN) > Show deprecated DSN.

ERROR: Sentry failure builds=0 error=raven: dsn missing private key

Error Tracking List

Users with at least Reporter permissions can find the Error Tracking list at Monitor > Error Tracking in your project's sidebar. Here, you can filter errors by title or by status (one of Ignored , Resolved, or Unresolved) and sort in descending order by Frequency, First Seen, or Last Seen. By default, the error list is ordered by Last Seen and filtered to Unresolved errors.

Error Tracking list

Error Details

From error list, users can navigate to the error details page by clicking the title of any error.

This page has:

  • A link to the Sentry issue.
  • A link to the GitLab commit if the Sentry release ID/version on the Sentry Issue's first release matches a commit SHA in your GitLab hosted project.
  • Other details about the issue, including a full stack trace.
  • In GitLab 12.7 and newer, language and urgency are displayed.

By default, a Create issue button is displayed:

Error Details without Issue Link

If you create a GitLab issue from the error, the Create issue button changes to a View issue button and a link to the GitLab issue displays within the error detail section.

Taking Action on errors

You can take action on Sentry Errors from within the GitLab UI.

Ignoring errors

Introduced in GitLab 12.7.

From within the Error Details page you can ignore a Sentry error by clicking the Ignore button near the top of the page.

Ignoring an error prevents it from appearing in the Error Tracking List, and silences notifications that were set up within Sentry.

Resolving errors

Introduced in GitLab 12.7.

From within the Error Details page you can resolve a Sentry error by clicking the Resolve button near the top of the page.

Marking an error as resolved indicates that the error has stopped firing events. If a GitLab issue is linked to the error, then the issue closes.

If another event occurs, the error reverts to unresolved.

Integrated error tracking

Introduced in GitLab 14.3.

Integrated error tracking is a lightweight alternative to Sentry backend. You still use Sentry SDK with your application. But you don't need to deploy Sentry or set up for cloud-hosted Sentry. Instead, you use GitLab as a backend for it.

Sentry backend automatically assigns a Data Source Name (DSN) for every project you create. GitLab does the same. You should be able to find a DSN for your project in the GitLab error tracking settings. By using a GitLab-provided DSN, your application connects to GitLab to report an error. Those errors are stored in the GitLab database and rendered by the GitLab UI, in the same way as Sentry integration.

Project settings

The feature should be enabled on the project level. However, there is no UI to enable this feature yet. You must use the GitLab API to enable it.

How to enable

  1. Select GitLab as the error tracking backend for your project:

    Error Tracking Settings

  2. Create a client key (DSN) to use with Sentry SDK in your application. Make sure to save the response, as it contains a DSN:

    curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
    "https://gitlab.example.com/api/v4/projects/PROJECT_ID/error_tracking/client_keys"

  3. Take the DSN from the previous step and configure your Sentry SDK with it. Errors are now reported to the GitLab collector and are visible in the GitLab UI.

How to disable

To disable the feature, run this command. This is the same command as the one that enables the feature, but with a false value instead:

curl --request PATCH --header "PRIVATE-TOKEN: <your_access_token>" \
    "https://gitlab.example.com/api/v4/projects/PROJECT_ID/error_tracking/settings?active=false&integrated=false"

Limitations

The Integrated Error Tracking feature was built and tested with Sentry SDK for Ruby. Other languages and frameworks are not tested and might not work. Check the compatibility issue for more information.