1 files changed, 86 insertions, 0 deletions
diff --git a/doc/development/fe_guide/logging.md b/doc/development/fe_guide/logging.md
new file mode 100644
index 00000000000..26633eade43
--- /dev/null
+++ b/doc/development/fe_guide/logging.md
@@ -0,0 +1,86 @@
+---
+stage: none
+group: unassigned
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
+---
+
+# Client-side logging for frontend development
+
+This guide contains the best practices for client-side logging for GitLab
+frontend development.
+
+## When to log to the browser console
+
+We do not want to log unnecessarily to the browser console, as excessively
+noisy console logs are not easy to read, parse, or process. We **do** want to
+give visibility to unintended events in the system. If a possible but unexpected
+exception occurs during runtime, we want to log the details of this exception.
+These logs can give significantly helpful context to end users creating issues, or
+contributors diagnosing problems.
+
+Whenever a `catch(e)` exists, and `e` is something unexpected, log the details.
+
+### What makes an error unexpected?
+
+Sometimes a caught exception can be part of normal operations. For instance, third-party
+libraries might throw an exception based on certain inputs. If we can gracefully
+handle these exceptions, then they are expected. Don't log them noisily.
+For example:
+
+```javascript
+try {
+  // Here, we call a method based on some user input.
+  // `doAThing` will throw an exception if the input is invalid.
+  const userInput = getUserInput();
+  doAThing(userInput);
+} catch (e) {
+  if (e instanceof FooSyntaxError) {
+    // To handle a `FooSyntaxError`, we just need to instruct the user to change their input.
+    // This isn't unexpected, and is part of normal operations.
+    setUserMessage(`Try writing better code. ${e.message}`);
+  } else {
+    // We're not sure what `e` is, so something unexpected and bad happened...
+    logError(e);
+    setUserMessage('Something unexpected happened...');
+  }
+}
+```
+
+## How to log an error
+
+We have a helpful `~/lib/logger` module which encapsulates how we can
+consistently log runtime errors in GitLab. Import `logError` from this
+module, and use it as you normally would `console.error`. Pass the actual `Error`
+object, so the stack trace and other details can be captured in the log:
+
+```javascript
+// 1. Import the logger module.
+import { logError } from '~/lib/logger';
+
+export const doThing = () => {
+  return foo()
+    .then(() => {
+      // ...
+    })
+    .catch(e => {
+      // 2. Use `logError` like you would `console.error`.
+      logError('An unexpected error occurred while doing the thing', e);
+
+      // We may or may not want to present that something bad happened to the end user.
+      showThingFailed();
+    });
+};
+```
+
+## Relation to frontend observability
+
+Client-side logging is strongly related to
+[Frontend observability](https://about.gitlab.com/company/team/structure/working-groups/frontend-observability/).
+We want unexpected errors to be observed by our monitoring systems, so
+we can quickly react to user-facing issues. For a number of reasons, it is
+unfeasible to send every log to the monitoring system. Don't shy away from using
+`~/lib/logger`, but consider controlling which messages passed to `~/lib/logger`
+are actually sent to the monitoring systems.
+
+A cohesive logging module helps us control these side effects consistently
+across the various entry points.