From c8fb3e9f3b3d98f94cf66bf3a99751d1d163be7d Mon Sep 17 00:00:00 2001
From: Rachel Nabors <rnabors@fb.com>
Date: Wed, 29 Jul 2020 16:16:39 +0100
Subject: [PATCH] Adding Will Holen's doc on symbolication. Feels like this is
 a debugging technique and like we need a section on Debugging. For future IA
 discussions.

---
 docs/symbolication.md | 39 +++++++++++++++++++++++++++++++++++++++
 website/i18n/en.json  |  3 +++
 website/sidebars.json |  1 +
 3 files changed, 43 insertions(+)
 create mode 100644 docs/symbolication.md

diff --git a/docs/symbolication.md b/docs/symbolication.md
new file mode 100644
index 00000000000..f182d68193e
--- /dev/null
+++ b/docs/symbolication.md
@@ -0,0 +1,39 @@
+---
+id: symbolication
+title: Symbolicating a stack trace
+---
+
+If a React Native app throws an unhandled exception in a release build, the output may be obfuscated and hard to read:
+
+```sh
+07-15 10:58:25.820 18979 18998 E AndroidRuntime: FATAL EXCEPTION: mqt_native_modules
+07-15 10:58:25.820 18979 18998 E AndroidRuntime: Process: com.awesomeproject, PID: 18979 07-15 10:58:25.820 18979 18998 E AndroidRuntime: com.facebook.react.common.JavascriptException: Failed, js engine: hermes, stack:
+07-15 10:58:25.820 18979 18998 E AndroidRuntime: p@1:132161
+07-15 10:58:25.820 18979 18998 E AndroidRuntime: p@1:132084
+07-15 10:58:25.820 18979 18998 E AndroidRuntime: f@1:131854
+07-15 10:58:25.820 18979 18998 E AndroidRuntime: anonymous@1:131119
+```
+
+The sections like `p@1:132161` are minified function names and bytecode offsets. To debug the problem, you would instead want to translate it into file, line and function name: `AwesomeProject/App.js:54:initializeMap`. This is known as **symbolication.** You can symbolicate minified function names and bytecode like the above by passing `metro-symbolicate` a generated source map and the stack trace.
+
+> The `metro-symbolicate` package is installed by default in the React Native template project from [setting up your development environment](environment-setup).
+
+From a file containing the stacktrace:
+
+```sh
+npx metro-symbolicate android/app/build/generated/sourcemaps/react/release/index.android.bundle.map < stacktrace.txt
+```
+
+From `adb logcat`directly:
+
+```sh
+adb logcat -d | npx metro-symbolicate android/app/build/generated/sourcemaps/react/release/index.android.bundle.map
+```
+
+This will turn each minified function name and offset like `p@1:132161` into the actual file- and function name `AwesomeProject/App.js:54:initializeMap`.
+
+## Notes on Sourcemaps
+
+- Multiple source maps may be generated by the build process. Make sure to used the one in the location shown in the examples.
+- Make sure that the source map you use corresponds to the exact commit of the crashing app. Small changes in source code can cause large differences in offsets.
+- If `metro-symbolicate` exits immediately with success, make sure the input comes from a pipe or redirection and not from a terminal.
diff --git a/website/i18n/en.json b/website/i18n/en.json
index efff99c1df0..7bd5d1aaa5c 100644
--- a/website/i18n/en.json
+++ b/website/i18n/en.json
@@ -356,6 +356,9 @@
       "switch": {
         "title": "Switch"
       },
+      "symbolication": {
+        "title": "Symbolicating a stack trace"
+      },
       "systrace": {
         "title": "Systrace"
       },
diff --git a/website/sidebars.json b/website/sidebars.json
index 3ef92cf4ad4..226e27cacb7 100644
--- a/website/sidebars.json
+++ b/website/sidebars.json
@@ -21,6 +21,7 @@
       "running-on-device",
       "fast-refresh",
       "debugging",
+      "symbolication",
       "testing-overview",
       "libraries",
       "typescript",