diff options
Diffstat (limited to 'doc/development/fe_guide/sentry.md')
-rw-r--r-- | doc/development/fe_guide/sentry.md | 97 |
1 files changed, 80 insertions, 17 deletions
diff --git a/doc/development/fe_guide/sentry.md b/doc/development/fe_guide/sentry.md index af4a006c7ea..929de1499c7 100644 --- a/doc/development/fe_guide/sentry.md +++ b/doc/development/fe_guide/sentry.md @@ -4,31 +4,94 @@ group: unassigned 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 --- -# Sentry +# Sentry monitoring in the frontend development of GitLab -As part of the [Frontend Observability Working Group](https://google.com) we're looking to provide documentation on how to use Sentry effectively. -If left unchecked, Sentry can get noisy and become unreliable. -This page aims to help guide us toward more sensible Sentry usage. +The GitLab Frontend team uses Sentry as an observability tool to monitor how the UI performs for +users on `gitlab.com`. -## Which errors we should report to Sentry explicitly and which should be only shown to users (e.g. as alerts) +GitLab.com is configured to report to our Sentry instance at **Admin > Metrics and profiling > Sentry**. -If we send all errors to Sentry, it gets very noisy, very quickly. -We want to filter out the errors that we either don't care about, or have no control over. -For example, if a user fills out a form incorrectly, this is not something we want to send to Sentry. -If that form fails because it's hitting a dead endpoint, this is an error we want Sentry to know about. +We monitor two kinds of data: **Errors** and **Performance**. -## How to catch errors correctly so Sentry can display them reliably +NOTE: +The [Frontend Observability Working Group](https://handbook.gitlab.com/handbook/company/working-groups/frontend-observability/) is looking to improve how we use Sentry. GitLab team members can provide feedback at +[issue #427402](https://gitlab.com/gitlab-org/gitlab/-/issues/427402). -TBD +## Start using Sentry -## How to catch special cases you want to track (like we did with the pipeline graph) +Our Sentry instance is located at [https://new-sentry.gitlab.net/](https://new-sentry.gitlab.net/). +Only GitLab team members can access Sentry. -TBD +After your first log-in you can join the `#gitlab` team by selecting **Join a team**. Confirm that +`#gitlab` appears under `YOUR TEAMS` in the [teams page](https://new-sentry.gitlab.net/settings/gitlab/teams/). -## How to navigate Sentry and find errors +## Error reporting -TBD +Errors, also known as "events" in the Sentry UI, are instances of abnormal or unexpected runtime +behavior that users experience in their browser. -## How to debug Sentry errors effectively +GitLab uses the [Sentry Browser SDK](https://docs.sentry.io/platforms/javascript/) to report errors +to our Sentry instance under the project +[`gitlabcom-clientside`](https://new-sentry.gitlab.net/organizations/gitlab/projects/gitlabcom-clientside/?project=4). -TBD +### Reporting known errors + +The most common way to report errors to Sentry is to call `captureException(error)`, for example: + +```javascript +import * as Sentry from '@sentry/browser'; + +try { + // Code that may fail in runtime +} catch (error) { + Sentry.captureException(error) +} +``` + +**When should you report an error?** We want to avoid reporting errors that we either don't care +about, or have no control over. For example, we shouldn't report validation errors when a user fills +out a form incorrectly. However, if that form submission fails because or a server error, +this is an error we want Sentry to know about. + +### Unhandled/unknown errors + +Additionally, we capture unhandled errors automatically in all of our pages. + +## Error Monitoring + +Once errors are captured, they appear in Sentry. For example you can see the +[errors reported in the last 24 hours in canary and production](https://new-sentry.gitlab.net/organizations/gitlab/issues/?environment=gprd-cny&environment=gprd&project=4&query=&referrer=issue-list&sort=freq&statsPeriod=24h). + +In the list, select any error to see more details... and ideally propose a solution for it! + +NOTE: +We suggest filtering errors by the environments `gprd` and `gprd-cny`, as there is some spam in our +environment data. + +### Exploring error data + +Team members can use Sentry's [Discover page](https://new-sentry.gitlab.net/organizations/gitlab/discover/homepage/?environment=gprd-cny&environment=gprd&field=title&field=event.type&field=project&field=user.display&field=timestamp&field=replayId&name=All+Events&project=4&query=&sort=-timestamp&statsPeriod=14d&yAxis=count%28%29) to find unexpected issues. + +Additionally, we have created [a dashboard](https://new-sentry.gitlab.net/organizations/gitlab/dashboard/3/?environment=gprd&environment=gprd-cny&project=4&statsPeriod=24h) to report which feature categories and pages produce +most errors, among other data. + +Engineering team members are encouraged to explore error data and find ways to reduce errors on our +user interface. Sentry also provides alerts for folks interested in getting notified when errors occur. + +### Filtering errors + +We receive several thousands of reports per day, so team members can filter errors based on their +work area. + +We mark errors with two additional custom `tags` to help identify their source: + +- `feature_category`: The feature area of the page. (For example, `code_review_workflow` or `continuous_integration`.) **Source:** `gon.feature_category` +- `page`: Identifier of method called in the controller to render the page. (For example, `projects:merge_requests:index` or `projects:pipelines:index`.) **Source:** [`body_data_page`](https://gitlab.com/gitlab-org/gitlab/blob/b2ea95b8b1f15228a2fd5fa3fbd316857d5676b8/app/helpers/application_helper.rb#L144). + +Frontend engineering team members can filter errors relevant to their group and/or page. + +## Performance Monitoring + +We use [BrowserTracing](https://docs.sentry.io/platforms/javascript/performance/) to report performance metrics to Sentry. + +You can visit [our performance data of the last 24 hours](https://new-sentry.gitlab.net/organizations/gitlab/performance/?environment=gprd-cny&environment=gprd&project=4&statsPeriod=24h) and use the filters to drill down and learn more. |