192 lines
10 KiB
Markdown
192 lines
10 KiB
Markdown
---
|
|
stage: Monitor
|
|
group: Observability
|
|
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
|
|
---
|
|
|
|
# Error Tracking **(FREE)**
|
|
|
|
> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/389991) in GitLab 15.9.
|
|
|
|
WARNING:
|
|
This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/389991)
|
|
for use in GitLab 15.9, and is planned for removal in GitLab 16.0. We are replacing this feature with functionality in the [GitLab Observability UI](https://gitlab.com/gitlab-org/opstrace/opstrace-ui). Please also reference our direction for [Observability](https://about.gitlab.com/direction/monitor/observability/) and [data visualization](https://about.gitlab.com/direction/monitor/observability/data-visualization/).
|
|
|
|
Error Tracking allows developers to discover and view errors generated by their application. Because error information is surfaced where the code is being developed, efficiency and awareness are increased.
|
|
|
|
## How error tracking works
|
|
|
|
For error tracking to work, you need two pieces:
|
|
|
|
- **Your application with Sentry SDK:** when the error happens, Sentry SDK captures information
|
|
about it and sends it over the network to the backend. The backend stores information about all
|
|
errors.
|
|
|
|
- **Error tracking backend:** the backend can be either GitLab itself or Sentry. When it's GitLab,
|
|
we name it _integrated error tracking_ because you don't need to set up a separate backend. It's
|
|
already part of the product.
|
|
|
|
- To use the GitLab backend, see [integrated error tracking](#integrated-error-tracking).
|
|
- To use Sentry as the backend, see [Sentry error tracking](#sentry-error-tracking).
|
|
|
|
No matter what backend you choose, the [error tracking UI](#error-tracking-list)
|
|
is the same.
|
|
|
|
## Sentry error tracking
|
|
|
|
[Sentry](https://sentry.io/) 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](https://sentry.io) or deploy your own [on-premise instance](https://github.com/getsentry/onpremise/).
|
|
|
|
### Enabling Sentry
|
|
|
|
GitLab provides an easy way to connect Sentry to your project. You need at
|
|
least Maintainer [permissions](../user/permissions.md) to enable the Sentry integration.
|
|
|
|
1. Sign up to Sentry.io or [deploy your own](#deploying-sentry) Sentry instance.
|
|
1. [Create](https://docs.sentry.io/product/sentry-basics/guides/integrate-frontend/create-new-project/) a new Sentry project. For each GitLab project that you want to integrate, we recommend that you create a new Sentry project.
|
|
1. Find or generate a [Sentry auth token](https://docs.sentry.io/api/auth/#auth-tokens).
|
|
For the SaaS version of Sentry, you can find or generate the auth token at [https://sentry.io/api/](https://sentry.io/api/).
|
|
Make sure to give the token at least the following scopes: `project:read`, `event:read`, and
|
|
`event:write` (for resolving events).
|
|
1. In GitLab, enable error tracking:
|
|
1. On the top bar, select **Main menu > Projects** and find your project.
|
|
1. On the left sidebar, select **Monitor > Error Tracking**.
|
|
1. Select **Enable error tracking**.
|
|
1. In GitLab, ensure error tracking is active.
|
|
1. On the left sidebar, select **Settings > Monitor**.
|
|
1. Expand **Error Tracking**.
|
|
1. Ensure the **Active** checkbox is selected.
|
|
1. 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`.
|
|
1. In the **Auth Token** box, enter the token you previously generated.
|
|
1. To test the connection to Sentry and populate the **Project** dropdown list, select **Connect**.
|
|
1. From the **Project** list, choose a Sentry project to link to your GitLab project.
|
|
1. Select **Save changes**.
|
|
|
|
You can now visit **Monitor > Error Tracking** in your project's sidebar to [view a list](#error-tracking-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](https://docs.sentry.io/product/integrations/gitlab/)
|
|
|
|
### 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](https://docs.gitlab.com/runner/configuration/advanced-configuration.html).
|
|
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**.
|
|
|
|
```plaintext
|
|
ERROR: Sentry failure builds=0 error=raven: dsn missing private key
|
|
```
|
|
|
|
## Error Tracking List
|
|
|
|
Users with at least Reporter [permissions](../user/permissions.md)
|
|
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 Details
|
|
|
|
From error list, users can navigate to the error details page by selecting 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](https://docs.sentry.io/product/releases/?platform=javascript#configure-sdk) 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](https://gitlab.com/gitlab-org/gitlab/-/issues/36246), language and urgency are displayed.
|
|
|
|
By default, a **Create issue** button is displayed:
|
|
|
|
|
|
|
|
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. Marking errors ignored or resolved require at least Developer role.
|
|
|
|
### Ignoring errors
|
|
|
|
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/39665) in GitLab 12.7.
|
|
|
|
From within the [Error Details](#error-details) page you can ignore a Sentry error by selecting the **Ignore** button near the top of the page.
|
|
|
|
Ignoring an error prevents it from appearing in the [Error Tracking List](#error-tracking-list), and silences notifications that were set up within Sentry.
|
|
|
|
### Resolving errors
|
|
|
|
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/39825) in GitLab 12.7.
|
|
|
|
From within the [Error Details](#error-details) page you can resolve a Sentry error by
|
|
selecting 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 **(FREE SAAS)**
|
|
|
|
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/329596) in GitLab 14.4.
|
|
> - [Disabled](https://gitlab.com/gitlab-org/gitlab/-/issues/353639) in GitLab 14.9 [with a flag](../administration/feature_flags.md) named `integrated_error_tracking`. Disabled by default.
|
|
> - [Enabled on GitLab.com](https://gitlab.com/gitlab-com/gl-infra/production/-/issues/7586) in GitLab 15.6.
|
|
|
|
NOTE:
|
|
Available only on GitLab.com. This feature is currently in [Open Beta](https://about.gitlab.com/handbook/product/gitlab-the-product/#open-beta).
|
|
|
|
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.
|
|
|
|
In GitLab 15.6 and later, the integrated error tracking
|
|
uses a new backend based on the ClickHouse database that enables better scalability.
|
|
Integrated error tracking remains limited in comparison to the Sentry backend, as only a small subset of the
|
|
Sentry API is implemented.
|
|
|
|
Changing the GitLab error UI to use the GitLab Observability UI is tracked in epic [19](https://gitlab.com/groups/gitlab-org/opstrace/-/epics/32).
|
|
|
|
### Project settings
|
|
|
|
You can find the feature configuration at **Settings > Monitor > Error Tracking**.
|
|
|
|
#### How to enable
|
|
|
|
1. Select **GitLab** as the error tracking backend for your project:
|
|
|
|
|
|
|
|
1. Select **Save changes**. After page reload you should see a text field with the DSN string. Copy it.
|
|
|
|
|
|
|
|
1. 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](#error-tracking-list).
|
|
|
|
#### Managing DSN
|
|
|
|
When you enable the feature you receive a DSN. It includes a hash used for authentication. This hash
|
|
is a client key. GitLab uses client keys to authenticate error tracking requests from your
|
|
application to the GitLab backend.
|
|
|
|
In some situations, you may want to create a new client key and remove an existing one.
|
|
You can do so by managing client keys with the [error tracking API](../api/error_tracking.md).
|
|
|
|
#### Limitations
|
|
|
|
The Integrated Error Tracking feature was built and tested with Sentry SDK for Ruby on Rails.
|
|
Support for other languages and frameworks is not guaranteed. For up-to-date information, see the
|
|
[compatibility issue](https://gitlab.com/gitlab-org/gitlab/-/issues/340178).
|