diff options
Diffstat (limited to 'doc/operations/error_tracking.md')
| -rw-r--r-- | doc/operations/error_tracking.md | 398 |
1 files changed, 125 insertions, 273 deletions
diff --git a/doc/operations/error_tracking.md b/doc/operations/error_tracking.md index db68abf0778..a2d50e43a80 100644 --- a/doc/operations/error_tracking.md +++ b/doc/operations/error_tracking.md @@ -6,353 +6,205 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Error Tracking **(FREE)** -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. +Error Tracking allows developers to discover and view errors generated by their application. Because error information is surfaced where the code is developed, this increases efficiency and awareness. Users can choose between [GitLab Integrated error tracking](#integrated-error-tracking) and [Sentry based](#sentry-error-tracking) backends. ## How error tracking works -For error tracking to work, you need two pieces: +For error tracking to work, you need: -- **Your application with Sentry SDK:** when the error happens, Sentry SDK captures information +- **Your application configured with the 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 + you 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) + Whatever 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 so users can 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 a 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 go to the error details page by selecting the title of any error. - -This page includes: - -- 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 in the error detail section. - -## Taking action on errors - -You can take action on Sentry Errors in the GitLab UI. Marking errors as ignored or resolved requires at least Developer role. - -### Ignoring errors - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/39665) in GitLab 12.7. - -In the [Error Details](#error-details) page you can ignore a Sentry error by selecting **Ignore** 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 in Sentry. - -### Resolving errors - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/39825) in GitLab 12.7. - -In the [Error Details](#error-details) page you can resolve a Sentry error by -selecting **Resolve** 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. +This guide provides you with basics of setting up error tracking for your project, using examples from different languages. -NOTE: -Available only on GitLab.com. This feature is in [Open Beta](https://about.gitlab.com/handbook/product/gitlab-the-product/#open-beta). +Error tracking provided by GitLab Observability is based on [Sentry SDK](https://docs.sentry.io/). Check the [Sentry SDK documentation](https://docs.sentry.io/platforms/) for more thorough examples of how you can use Sentry SDK in your application. -### Known limitations +According to the Sentry [data model](https://develop.sentry.dev/sdk/envelopes/#data-model), the item types are: -Only basic support is provided with `capture_exception` as the holding method. -Additional features requests (see this [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/340178)) are added on a case-by-case basis. +- [Event](https://develop.sentry.dev/sdk/event-payloads/) +- [Transactions](https://develop.sentry.dev/sdk/event-payloads/transaction/) +- [Attachments](https://develop.sentry.dev/sdk/envelopes/#attachment) +- [Session](https://develop.sentry.dev/sdk/envelopes/#session) +- [Sessions](https://develop.sentry.dev/sdk/envelopes/#sessions) +- [User feedback](https://develop.sentry.dev/sdk/envelopes/#user-feedback) (also known as user report) +- [Client report](https://develop.sentry.dev/sdk/client-reports/) -### Debugging issues +### Enable error tracking for a project -The majority of languages are supported by Sentry expose `debug` option as part of initialization. -It is also possible to output JSON before it is sent to the API. -See the [Go example](#go) below for a suggested solution. +Regardless of the programming language you use, you first need to enable error tracking for your GitLab project. -### Enabling error tracking +The `GitLab.com` instance is used in this guide. -Regardless of the programming language, you need to enable error tracking for your project. This doc assumes you already have a project for which you want to enable error tracking. -This example uses the `gitlab.com` instance. +Prerequisites: -To enable error tracking, follow these steps: +- You have a project for which you want to enable error tracking. To learn how to create a new one, see [Create a project](../user/project/index.md). -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Monitor**. -1. Expand the **Error Tracking** tab. +To enable error tracking with GitLab as the backend: + +1. In your project, go to **Settings > Monitor**. +1. Expand **Error Tracking**. 1. Under **Enable error tracking**, select the **Active** checkbox. 1. Under **Error tracking backend**, select **GitLab**. 1. Select **Save changes**. -1. Copy the DSN string to use later. -### Listing captured errors +1. Copy the Data Source Name (DSN) string. You need it for configuring your SDK implementation. -Once your application has emitted errors to the Error Tracking API through the Sentry SDK, they should be available under **Monitor > Error Tracking** tab/section. +## Error tracking list -For more details, refer to the [GitLab error tracking documentation](https://gitlab.com/help/operations/error_tracking#error-tracking-list). +After your application has emitted errors to the Error Tracking API through the Sentry SDK, +they should be available under the **Monitor > Error Tracking** tab/section. -This process assumes the GDK feature flag `integrated_error_tracking` is enabled. If you are running GDK locally and you do not see the option for error tracking, you can enable it by running the following commands: + -```linux -cd <PATH_TO_GDK> -gdk rails console -Feature.enable(:integrated_error_tracking) -``` +## Error tracking details -### Emitting errors +In the Error Details view you can see more details of the exception, including number of occurrences, +users affected, first seen, and last seen dates. -#### Supported Sentry types +You can also review the stack trace. -According to the [data model](https://develop.sentry.dev/sdk/envelopes/#data-model), the available item types are: + -- [Event](https://develop.sentry.dev/sdk/event-payloads/) -- [Transactions](https://develop.sentry.dev/sdk/event-payloads/transaction/) -- Attachment -- [Session](https://develop.sentry.dev/sdk/sessions/) -- [Sessions](https://develop.sentry.dev/sdk/sessions/) -- [User feedback](https://develop.sentry.dev/sdk/envelopes/#user-feedback) (also known as user report) -- [Client report](https://develop.sentry.dev/sdk/client-reports/) - -Items of various types can be sent to the error tracking app, using either the Store endpoint, the envelope endpoint, or both. The following table lists all event types available through Sentry SDK. It also explains which endpoint can be used for ingestion and whether it is supported by GitLab Observability Backend. +## Emit errors -Event item types can contain various interfaces, such as exception, message, stack trace, and template. You can read more about the core data interfaces in [Sentry documentation](https://develop.sentry.dev/sdk/event-payloads/#core-interfaces). +### Supported language SDKs & Sentry types -| Item type | Interface | Can be sent through the Store endpoint | Can be sent through the Envelope endpoint | Supported | -| --------------- | ----------- | -------------------------------------- | ----------------------------------------- | ---------------------- | -| `event` | exception | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | -| `event` | message | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | -| `event` | stack trace | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | -| `event` | template | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | -| `transaction` | N/A | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | -| `attachment` | N/A | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | -| `session` | N/A | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | -| `sessions` | N/A | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | -| `user_report` | N/A | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | -| `client_report` | N/A | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | +In the following table, you can see a list of all event types available through Sentry SDK, and whether they are supported by GitLab Error Tracking. -#### Supported languages +| Language | Tested SDK client and version | Endpoint | Supported item types | +| -------- | ------------------------------- | ---------- | --------------------------------- | +| Go | `sentry-go/0.20.0` | `store` | `exception`, `message` | +| Java | `sentry.java:6.18.1` | `envelope` | `exception`, `message` | +| NodeJS | `sentry.javascript.node:7.38.0` | `envelope` | `exception`, `message` | +| PHP | `sentry.php/3.18.0` | `store` | `exception`, `message` | +| Python | `sentry.python/1.21.0` | `envelope` | `exception`, `message`, `session` | +| Ruby | `sentry.ruby:5.9.0` | `envelope` | `exception`, `message` | +| Rust | `sentry.rust/0.31.0` | `envelope` | `exception`, `message`, `session` | -Each language shows a basic example of how to capture exceptions with the respective SDK. -For more in-depth documentation, see [documentation for Sentry SDK](https://docs.sentry.io/). You can also find information for additional programming languages. +For a detailed version of this table, see [this issue](https://gitlab.com/gitlab-org/opstrace/opstrace/-/issues/1737). -Only a subset of languages is supported. +## Usage examples -The following table lists them: +You can also find working samples for all [supported language SDKs](https://gitlab.com/gitlab-org/opstrace/opstrace/-/tree/main/test/sentry-sdk/testdata/supported-sdk-clients). +Each listed program shows a basic example of how to capture exceptions, events, +or messages with the respective SDK. -| Sentry SDK | Supported? | -| ----------- | ----------- | -| Ruby | Yes | -| Go | Yes | -| JavaScript | Yes | -| Java | Yes | -| Python | Yes | -| PHP | Yes | -| .NET | Not tested | -| Android | Not tested | -| Apple | Not tested | -| Perl | Not tested | +For more in-depth documentation, +see [Sentry SDK's documentation](https://docs.sentry.io/) specific to the used language. -A more up-to-date version of [this matrix can be found in this doc](https://gitlab.com/gitlab-org/opstrace/opstrace/-/issues/1737). +## Rotate generated DSN -#### Go - -1. `chdir` into folder `docs/guides/user/error_tracking_examples/go/` -1. Install the dependencies with the following command: - - ```shell - go mod tidy - ``` +The Sentry Data Source Name, or DSN, (client key) is a secret and it should not be exposed to the public. +In case of a leak, rotate the Sentry DSN by following these steps: -1. Run the following command: +1. [Create an access token](../user/profile/personal_access_tokens.md#create-a-personal-access-token) + by selecting your profile picture in GitLab.com. + Then select Preferences, and then Access Token. Make sure you add API scope. +1. Using the [error tracking API](../api/error_tracking.md), + create a new Sentry DSN: ```shell - export SENTRY_DSN="<DSN string>" - go run main.go <DSN string> + curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" + --header "Content-Type: application/json" \ + "https://gitlab.example.com/api/v4/projects/<your_project_number>/error_tracking/client_keys" ``` -After you've run this program, there should be an error visible in the Error tracking tab from `Listing captured errors` section of this document. - -#### Ruby - -1. `chdir` into folder `docs/guides/user/error_tracking_examples/ruby/` -1. Install the dependencies with the following command: +1. Get the available client keys (Sentry DSNs). + Ensure that the newly created Sentry DSN is in place. + Then note down the key ID of the old client key: ```shell - gem install bundler - bundle install + curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/<your_project_number>/error_tracking/client_keys" ``` -1. Execute the example with the following command: +1. Delete the old client key. ```shell - export SENTRY_DSN="<DSN string>" - ruby app.rb + curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/<your_project_number>/error_tracking/client_keys/<key_id>" ``` -After you've run this program, there should be an error visible in the Error tracking tab from `Listing captured errors` section of this document. +## Debug SDK issues -#### PHP +The majority of languages supported by Sentry expose `debug` option as part of initialization. +This can be helpful when debugging issues with sending errors. Otherwise, +there are options that could allow outputting JSON before it is sent to the API. -1. `chdir` into folder `docs/guides/user/error_tracking_examples/php/` +## Sentry error tracking -1. Build and run the Docker container with the following commands: +[Sentry](https://sentry.io/) is an open source error tracking system. GitLab allows +administrators to connect Sentry to GitLab +so users can view a list of Sentry errors in GitLab. -```shell -export SENTRY_DSN="<DSN string>" -docker build -t sentry-php . -docker run -e SENTRY_DSN --rm sentry-php -``` +### Deploying Sentry -After you've run this program, there should be an error visible in the Error tracking tab from `Listing captured errors` section of this document. +You can sign up to the cloud-hosted [Sentry](https://sentry.io) or deploy your own +[on-premise instance](https://github.com/getsentry/onpremise/). -#### Python +### Enable Sentry integration for a project -1. `chdir` into folder `docs/guides/user/error_tracking_examples/python/` +GitLab provides a way to connect Sentry to your project. -1. Install the dependencies with the following commands: +Prerequisites: - ```shell - virtualenv env - source env/bin/activate - pip install -r requirements.txt - ``` +- You must have at least the Developer role for the project. -1. Run the following commands: +To enable the Sentry integration: -```shell -export SENTRY_DSN="<DSN string>" -python send_exception.py -``` +1. Sign up to Sentry.io or [deploy your own](#deploying-sentry) Sentry instance. +1. [Create a new Sentry project](https://docs.sentry.io/product/sentry-basics/guides/integrate-frontend/create-new-project/). + For each GitLab project that you want to integrate, you should 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/). + You should give the token at least the following scopes: `project:read`, + `event:read`, and + `event:write` (for resolving events). +1. In GitLab, enable and configure Error Tracking: + 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. + 1. Select **Monitor > Error Tracking**. + 1. Under **Enable error tracking**, select the **Active** checkbox. + 1. Under **Error tracking backend**, select **Sentry**. + 1. Under **Sentry API URL**, enter your Sentry hostname. For example, + enter `https://sentry.example.com`. + For the SaaS version of Sentry, the hostname is `https://sentry.io`. + 1. Under **Auth Token**, 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. + +### Sentry's GitLab integration + +You might also want to enable Sentry's GitLab integration by following the steps +in the [Sentry documentation](https://docs.sentry.io/product/integrations/gitlab/). -After you've run this program, there should be an error visible in the Error tracking tab from `Listing captured errors` section of this document. +### Enable GitLab Runner -#### Java +To configure GitLab Runner with Sentry, you must add the value for `sentry_dsn` +to your runner's `config.toml` configuration file, as referenced in +[Advanced configuration](https://docs.gitlab.com/runner/configuration/advanced-configuration.html). -1. `chdir` into folder `docs/guides/user/error_tracking_examples/python/` +If you're asked for the project type while setting up Sentry, select **Go**. -1. Run the following command: +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**. -```shell -export SENTRY_DSN="<DSN string>" -./gradlew run +```plaintext +ERROR: Sentry failure builds=0 error=raven: dsn missing private key ``` - -#### Node.js - -1. `chdir` into folder `docs/guides/user/error_tracking_examples/nodejs/` - -1. Install the dependencies with the following command: - - ```shell - npm install --save @sentry/node @sentry/tracing - ``` - -1. Run the following command: - - ```shell - export SENTRY_DSN="<DSN string>" - node ./test.js - ``` - -After you've run this program, there should be an error visible in the Error tracking tab from `Listing captured errors` section of this document. - -### Rotating Sentry DSN - -The Sentry DSN (client key) is a secret and it should not be exposed to the public. If it's leaked, you can rotate the Sentry DSN with the following steps: - -1. [Create an access token](../user/profile/personal_access_tokens.md#create-a-personal-access-token) by clicking your profile picture in GitLab.com. Then choose Preferences,then Access Token. Make sure you add the API scope. -1. Using the [error tracking API](../api/error_tracking.md), create a new Sentry DSN with the following command: - - ```shell - curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" \ - "https://gitlab.example.com/api/v4/projects/<your_project_number>/error_tracking/client_keys" - ``` - -1. Get the available client keys (Sentry DSNs). Ensure that the newly created Sentry DSN is in place. Then note down the key ID of the old client key: - - ```shell - curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/<your_project_number>/error_tracking/client_keys" - ``` - -1. Delete the old client key with the following command: - - ```shell - curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/<your_project_number>/error_tracking/client_keys/<key_id>" - ``` |