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.