feat(wasm): Add initial docs for WASM (#2737)

Author: mitsuhiko

src/docs/contributing/approach/write-data-management.mdx

@@ -51,7 +51,7 @@ This file is `/sensitive-data/index.mdx`. It explains how to scrub or filter dat
 
 For data scrubbing that the SDK DOES NOT support, add the name of the SDK to the `PlatformSection notSupported` statement, which ensures the content won't display. For example:
 
-`<PlatformSection notSupported={["flutter", "apple", "perl", "native.breakpad", "native.crashpad", "native.minidumps", "native.ue4", "go", "ruby", "native", "elixir"]}>`
+`<PlatformSection notSupported={["flutter", "apple", "perl", "native.breakpad", "native.crashpad", "native.minidumps", "native.wasm", "native.ue4", "go", "ruby", "native", "elixir"]}>`
 
 Add the code sample to these directories:
 

src/includes/upload-dif/native.mdx

@@ -0,0 +1,11 @@
+```bash
+sentry-cli upload-dif -o <org> -p <project> /path/to/myfile.debug.wasm
+
+> Found 2 debug information files
+> Prepared debug information files for upload
+> Uploaded 2 missing debug information files
+> File processing complete:
+
+  PENDING 1ddb3423-950a-3646-b17b-d4360e6acfc9 (MyApp; x86_64 executable)
+  PENDING 1ddb3423-950a-3646-b17b-d4360e6acfc9 (MyApp; x86_64 debug companion)
+```

src/includes/upload-dif/native.wasm.mdx

@@ -0,0 +1,11 @@
+```bash
+wasm-split /path/to/myfile.wasm -d /path/to/myfile.debug.wasm --strip
+sentry-cli upload-dif -o <org> -p <project> /path/to/files
+
+> Found 1 debug information files
+> Prepared debug information files for upload
+> Uploaded 1 missing debug information files
+> File processing complete:
+
+  PENDING 1ddb3423-950a-3646-b17b-d4360e6acfc9 (mylib; wasm debug companion)
+```

src/platforms/common/configuration/index.mdx

@@ -1,7 +1,7 @@
 ---
 title: Configuration
 notSupported:
-  ["native.ue4", "native.breakpad", "native.crashpad", "native.minidumps"]
+  ["native.ue4", "native.breakpad", "native.crashpad", "native.minidumps", "native.wasm"]
 description: "Additional configuration options for the SDK."
 sidebar_order: 5
 ---

src/platforms/common/data-management/debug-files.mdx

@@ -16,6 +16,8 @@ in debug files includes original function names, paths to source files and line
 numbers, source code context, or the placement of variables in memory. Sentry
 can use some of this information and display it on the issue details page.
 
+<PlatformSection notSupported={["native.wasm"]}>
+
 Each major platform uses different debug information files. We currently support
 the following formats:
 
@@ -26,9 +28,12 @@ the following formats:
 - [_PDB files_](#pe-and-pdb) for Windows
 - [_Breakpad symbols_](#breakpad-symbols) for all
   platforms
+- [_WASM files_](#wasm) for WebAssembly
 - [_ProGuard mappings_](#proguard-mappings) for
   Java and Android
 
+</PlatformSection>
+
 <Note>
 
 Source maps, while also being debug information files, are handled
@@ -49,13 +54,6 @@ servers for automatic downloads.
 
 Sentry differentiates in four kinds of debug information:
 
-- **Unwind Information:** Enables Sentry to extract stack traces from Minidumps
-  and other binary crash formats of optimized builds. This process is referred
-  to as "stack unwinding" or "stack walking". Since this is also required when
-  throwing exceptions in C++, this information is often included in the
-  executable or library. If an uploaded file contains this information, it shows
-  the `unwind` tag.
-
 - **Debug Information:** Provides function names, paths to source files, line
   numbers and inline frames. The process of resolving this information from
   instruction addresses is called "symbolication". This information is
@@ -75,6 +73,15 @@ Sentry differentiates in four kinds of debug information:
   upload it to display source context in stack traces in Sentry. These bundles
   show up with the `sources` tag.
 
+- **Unwind Information:** Enables Sentry to extract stack traces from Minidumps
+  and other binary crash formats of optimized builds. This process is referred
+  to as "stack unwinding" or "stack walking". Since this is also required when
+  throwing exceptions in C++, this information is often included in the
+  executable or library. If an uploaded file contains this information, it shows
+  the `unwind` tag. Note that on some platforms no actual unwinding takes place.
+  For instance, WebAssembly currently does not have the equivalent of minidumps
+  which means we do not require that type of information in such cases.
+
 Compilers place the above debug information in different files passed on the
 target platform, architecture, build flags or optimization level. Consequently,
 Sentry might not need all of the above information to process crash reports.
@@ -83,6 +90,8 @@ Still, it is always a good idea to provide all available debug information.
 `sentry-cli` can be used to list properties of supported debug files and
 validate their contents. See [_Debug Information Files in sentry-cli_](/product/cli/dif/) for more information.
 
+<PlatformSection notSupported={["native.wasm"]}>
+
 The remainder of this section describes the file formats in detail.
 
 ### MachO and dSYM
@@ -211,13 +220,29 @@ that is not required to process minidumps. Most notably, inline functions are
 not declared, such that Sentry is not able to display inline frames in stack
 traces.
 
+### WASM
+
+</PlatformSection>
+
+For WebAssembly, we support [DWARF in WASM containers](https://yurydelendik.github.io/webassembly-dwarf/).
+Note that we do not support source maps, which are also a format used for WASM
+debugging, but have shortcomings that make them impractical for a crash reporting
+tool like Sentry.
+
+Since WASM does not specify debug/build IDs yet, we provide a separate tool to
+add build IDs and split files called [wasm-split](https://github.com/getsentry/symbolicator/tree/master/wasm-split)
+to help you create a debug companion file ready for uploading to Sentry
+while removing all debug information from the release binary.
+
+<PlatformSection notSupported={["native.wasm"]}>
+
 ### ProGuard Mappings
 
 <PlatformSection supported={["android", "flutter", "react-native"]}>
 
 <Note>
 
-  The recommended method for [Android users is to use the Gradle plugin](/platforms/android/proguard/).
+The recommended method for [Android users is to use the Gradle plugin](/platforms/android/proguard/).
 
 </Note>
 
@@ -227,6 +252,8 @@ ProGuard mapping files allow Sentry to resolve obfuscated Java classpaths and
 method names into their original form. In that sense, they act as debug
 information files for Java and Android applications.
 
+</PlatformSection>
+
 ## Debug Identifiers
 
 Each debug information file specifies a unique identifier. Crash reports declare
@@ -236,7 +263,8 @@ correct files. Sentry distinguishes two kinds of identifiers:
 - **Code Identifier**: The unique identifier of the executable or dynamic
   library -- the code file. The contents of this identifier are
   platform-dependent: MachO files use a UUID, ELF files a SHA hash, PE files use
-  a concatenation of certain header attributes.
+  a concatenation of certain header attributes. For WebAssembly we use an
+  embedded UUID in the `build_id` section of the file.
 
 - **Debug Identifier**: The unique identifier of the debug companion file. In
   contrast to the code identifier, Sentry enforces the same structure on all
@@ -265,6 +293,8 @@ files that match it in the _Debug Files_ settings screen.
 `sentry-cli` can help to print properties of debug information files like their
 debug identifier. See [_Checking Debug Information Files_](/product/cli/dif/#checking-files) for more information.
 
+<PlatformSection notSupported={["native.wasm"]}>
+
 ### GNU Build Identifiers
 
 For ELF files on Linux, Sentry uses the GNU build identifier to compute the
@@ -304,6 +334,21 @@ files are uploaded in the same invocation of the upload command. Otherwise, the
 identifiers diverge and Sentry might not be able to resolve the correct file
 for symbolication.
 
+</PlatformSection>
+
+### WASM Build IDs
+
+WebAssembly does not yet support build IDs. The option proposed to
+implement build IDs for WebAssembly ([Build ID Section for WASM](https://github.com/WebAssembly/tool-conventions/issues/133))
+has not yet found widespread adoption. Instead, we use a custom
+extension to WebAssembly.
+
+Our recommendation is to embed a UUID in the `build_id` custom section as
+raw binary. Our [`wasm-split`](https://github.com/getsentry/symbolicator/tree/master/wasm-split)
+tool can do this for you automatically.
+
+<PlatformSection notSupported={["native.wasm"]}>
+
 ### ProGuard UUIDs
 
 Unlike other debug information files, ProGuard files do not have an intrinsic
@@ -324,6 +369,8 @@ def get_proguard_uuid(filename):
         return uuid.uuid5(NAMESPACE, f.read())
 ```
 
+</PlatformSection>
+
 ## Uploading Files
 
 The most straightforward way to provide Sentry with debug information file is
@@ -336,17 +383,7 @@ application:
 Files can be uploaded using the `upload-dif` command. This command will scan a
 given folder recursively for files and upload them to Sentry:
 
-```bash
-sentry-cli upload-dif -o <org> -p <project> /path/to/files
-
-> Found 2 debug information files
-> Prepared debug information files for upload
-> Uploaded 2 missing debug information files
-> File processing complete:
-
-  PENDING 1ddb3423-950a-3646-b17b-d4360e6acfc9 (MyApp; x86_64 executable)
-  PENDING 1ddb3423-950a-3646-b17b-d4360e6acfc9 (MyApp; x86_64 debug companion)
-```
+<PlatformContent includePath="upload-dif" />
 
 For all available options and more information refer to [_Uploading Debug
 Information_](/product/cli/dif/#uploading-files).

src/platforms/common/data-management/event-grouping/index.mdx

@@ -11,7 +11,7 @@ All events have a fingerprint. Events with the same fingerprint are grouped toge
 
 By default, Sentry will run one of our built-in grouping algorithms to generate a fingerprint based on information available within the event such as `stacktrace`, `exception`, and `message`. To extend the default grouping behavior or change it completely, you can use a combination of the following options:
 
-1. In your SDK, using [SDK Fingerprinting](./sdk-fingerprinting/)
+1. In your SDK<PlatformSection notSupported={["native.wasm", "native.minidumps"]}>, using [SDK Fingerprinting](./sdk-fingerprinting/)</PlatformSection>
 2. In your project, using [Fingerprint Rules](./fingerprint-rules/)
 3. In your project, using [Stack Trace Rules](./stack-trace-rules/)
 

src/platforms/common/data-management/event-grouping/sdk-fingerprinting.mdx

@@ -4,6 +4,8 @@ sidebar_order: 0
 redirect_from:
   - ../../../enriching-events/context/fingerprint-override/
 description: "Learn about overriding default fingerprinting in your SDK."
+notSupported:
+  ["native.wasm", "native.minidump"]
 ---
 
 In supported SDKs, you can override Sentry's default grouping that passes the fingerprint attribute as an array of strings. The length of a fingerprint's array is not restricted. This works similarly to the [fingerprint rules functionality](../fingerprint-rules/), which is always available and can achieve similar results.

src/platforms/common/data-management/sensitive-data/index.mdx

@@ -15,23 +15,23 @@ There are two great examples for data scrubbing that every company should think
 - Authentication credentials, like your AWS password or key.
 - Confidential IP (Intellectual Property), such as your favorite color, or your upcoming plans for world domination.
 
-## Personally Identifiable Information (PII)
+<PlatformSection notSupported={["apple", "perl", "native.breakpad", "native.crashpad", "native.minidumps", "native.wasm", "native.ue4", "go", "ruby", "native", "elixir", "dart", "flutter"]}>
 
-<PlatformSection notSupported={["apple", "perl", "native.breakpad", "native.crashpad", "native.minidumps", "native.ue4", "go", "ruby", "native", "elixir", "dart", "flutter"]}>
+## Personally Identifiable Information (PII)
 
 Our newer SDKs do not purposefully send PII to stay on the safe side. This behavior is controlled by an option called [`send-default-pii`](../../configuration/options/#send-default-pii).
 
 Turning this option on is required for certain features in Sentry to work, but also means you will need to be even more careful about what data is being sent to Sentry (using the options below).
 
 </PlatformSection>
 
-<PlatformSection notSupported={["native.breakpad", "native.crashpad", "native.minidumps", "native.ue4"]}>
+<PlatformSection notSupported={["native.breakpad", "native.crashpad", "native.minidumps", "native.wasm", "native.ue4"]}>
 
 If you _do not_ wish to use the default PII behavior, you can also choose to identify users in a more controlled manner, using our [user identity context](../../enriching-events/identify-user/).
 
 </PlatformSection>
 
-<PlatformSection notSupported={["perl", "native.ue4", "native.breakpad", "native.crashpad", "native.minidumps"]}>
+<PlatformSection notSupported={["perl", "native.ue4", "native.breakpad", "native.crashpad", "native.minidumps", "native.wasm"]}>
 
 ## Scrubbing Data
 

src/platforms/common/enriching-events/breadcrumbs.mdx

@@ -6,6 +6,7 @@ notSupported:
   - native.breakpad
   - native.crashpad
   - native.minidumps
+  - native.wasm
   - native.ue4
 ---
 

src/platforms/common/enriching-events/context.mdx

@@ -5,6 +5,7 @@ notSupported:
   - native.breakpad
   - native.crashpad
   - native.minidumps
+  - native.wasm
   - native.ue4
 description: "Custom contexts allow you to attach arbitrary data (strings, lists, dictionaries) to an event."
 ---

src/platforms/common/enriching-events/identify-user.mdx

@@ -5,6 +5,7 @@ notSupported:
   - native.breakpad
   - native.crashpad
   - native.minidumps
+  - native.wasm
   - native.ue4
 description: "Learn how to configure the SDK to capture the user and gain critical pieces of information that construct a unique identity in Sentry."
 ---

src/platforms/common/enriching-events/index.mdx

@@ -6,6 +6,7 @@ notSupported:
   - native.breakpad
   - native.crashpad
   - native.minidumps
+  - native.wasm
 ---
 
 <PageGrid />

src/platforms/common/enriching-events/scopes.mdx

@@ -9,6 +9,7 @@ notSupported:
   - native.crashpad
   - native.minidumps
   - native.ue4
+  - native.wasm
 ---
 
 When an event is captured and sent to Sentry, SDKs will merge that event data with extra

src/platforms/common/enriching-events/tags.mdx

@@ -12,7 +12,7 @@ description: "Tags power UI features such as filters and tag-distribution maps.
 
 We’ll automatically index all tags for an event, as well as the frequency and the last time that Sentry has seen a tag. We also keep track of the number of distinct tags and can assist you in determining hotspots for various issues.
 
-<PlatformSection notSupported={["native.minidumps"]}>
+<PlatformSection notSupported={["native.minidumps", "native.wasm"]}>
 
 Defining tags is easy, and will bind them to the [current scope](../scopes/) ensuring all future events within scope contain the same tags:
 

src/platforms/common/enriching-events/user-feedback.mdx

@@ -17,6 +17,7 @@ notSupported:
   - native.breakpad
   - native.crashpad
   - native.minidumps
+  - native.wasm
   - native.ue4
   - dart
   - flutter

src/platforms/common/usage/index.mdx

@@ -7,6 +7,7 @@ notSupported:
   - native.breakpad
   - native.crashpad
   - native.minidumps
+  - native.wasm
   - native.ue4
 ---
 

src/platforms/native/common/debug-information.mdx

@@ -14,11 +14,31 @@ libraries. If you are not sure which files are required, go to _Project
 Settings > Processing Issues_, which shows a list of all the necessary files and
 instructions to retrieve them.
 
+<PlatformSection notSupported={["native.wasm"]}>
+
 In addition to Debug Information Files, Sentry needs _Call Frame Information_
 (CFI) to extract accurate stack traces from minidumps of optimized release
 builds. CFI is usually part of the executables and not copied to debug symbols.
 Unless you are uploading Breakpad symbols, be sure to also include the binaries
 when uploading files to Sentry.
+</PlatformSection>
+
+<PlatformSection supported={["native.wasm"]}>
+
+For WASM, you need to provide both the debug information and the original code
+in the same debug information file. To do this, we provide a custom
+tool called [wasm-split](https://github.com/getsentry/symbolicator/tree/master/wasm-split)
+that can do the splitting for you:
+
+```shell
+wasm-split /path/to/file.wasm -d /path/to/file.debug.wasm --strip
+```
+
+This command modifies the `file.wasm` in place to add the `build_id`, then removes all
+debug information. The debug information is put in a `file.debug.wasm` which
+then needs to be uploaded to Sentry.
+
+</PlatformSection>
 
 For more information on uploading debug information and their supported formats,
-see [Debug Information Files](/workflow/debug-files/).
+see [Debug Information Files](../data-management/debug-files/).