Merge pull request #253 from flashcatcloud/docs/electron-user-first-guide

docs(rum): simplify Electron SDK guides

Author: Fiona2016

docs.json

@@ -1736,7 +1736,9 @@
                       "zh/rum/sdk/electron/sdk-integration",
                       "zh/rum/sdk/electron/advanced-config",
                       "zh/rum/sdk/electron/compatible",
-                      "zh/rum/sdk/electron/data-collection"
+                      "zh/rum/sdk/electron/data-collection",
+                      "zh/rum/sdk/electron/error-symbolication",
+                      "zh/rum/sdk/electron/faq"
                     ]
                   },
                   {
@@ -3064,7 +3066,9 @@
                       "en/rum/sdk/electron/sdk-integration",
                       "en/rum/sdk/electron/advanced-config",
                       "en/rum/sdk/electron/compatible",
-                      "en/rum/sdk/electron/data-collection"
+                      "en/rum/sdk/electron/data-collection",
+                      "en/rum/sdk/electron/error-symbolication",
+                      "en/rum/sdk/electron/faq"
                     ]
                   },
                   {

en/rum/sdk/electron/advanced-config.mdx

@@ -0,0 +1,197 @@
+---
+title: "Electron error symbolication"
+description: "Upload JavaScript source maps and native crash symbols for an Electron application to restore production stack traces"
+keywords: ["RUM", "Electron", "source maps", "Breakpad", "native crash", "symbolication"]
+---
+
+Electron applications produce JavaScript errors and native crashes. Each stack type uses a different symbolication workflow:
+
+| Error type | Original stack | Upload required |
+|------------|----------------|-----------------|
+| Main-process and renderer JavaScript errors | Minified file name, line, and column | Build-generated source maps |
+| Electron or native module crash | Module name and memory address | Breakpad `.sym` files |
+
+## Symbolicate JavaScript errors
+
+By default, the SDK converts stack frames under the application directory to stable `app:///<relative path>` URLs. The same build produces the same path regardless of where a user installs the application.
+
+For example:
+
+```text
+Error: something went wrong
+  at handleClick @ app:///dist/renderer/index.js:97:15
+```
+
+Use only the URL path when uploading. The directory prefix for this example is `/dist/renderer`.
+
+### 1. Align service and version
+
+Flashduty matches a source map using:
+
+- Event `service`
+- Event `version`
+- Minified file path in the stack frame
+
+Use the same release version in both processes:
+
+```ts main.ts
+await init({
+  // Other options
+  service: 'my-electron-app',
+  version: '1.4.2',
+});
+```
+
+```ts renderer.ts
+flashcatRum.init({
+  // Other options
+  service: 'my-electron-app',
+  version: '1.4.2',
+});
+```
+
+The main-process `version` is not copied to renderer events, so both processes must set it.
+
+### 2. Generate source maps
+
+Enable source maps for main-process and renderer builds:
+
+<CodeGroup>
+```ts Vite
+export default defineConfig({
+  build: { sourcemap: true },
+});
+```
+
+```js Webpack
+module.exports = {
+  mode: 'production',
+  devtool: 'source-map',
+};
+```
+
+```ts esbuild
+await esbuild.build({
+  sourcemap: true,
+});
+```
+</CodeGroup>
+
+### 3. Upload main-process and renderer artifacts
+
+Install the [Flashduty CLI](https://github.com/flashcatcloud/flashcat-cli), then upload source maps for each process separately:
+
+```bash
+npm install --global @flashcatcloud/flashcat-cli
+```
+
+```bash
+# Main-process stack: app:///dist/main/index.js
+flashcat-cli sourcemaps upload ./out/main \
+  --service my-electron-app \
+  --release-version 1.4.2 \
+  --minified-path-prefix /dist/main \
+  --api-key <YOUR_API_KEY>
+
+# Renderer stack: app:///dist/renderer/index.js
+flashcat-cli sourcemaps upload ./out/renderer \
+  --service my-electron-app \
+  --release-version 1.4.2 \
+  --minified-path-prefix /dist/renderer \
+  --api-key <YOUR_API_KEY>
+```
+
+`--minified-path-prefix` must match the directory shown in the stack frame. Do not include `app:///` in the prefix.
+
+<Warning>
+Do not package `.map` files in the distributed application. Exclude them from the release artifact after upload and before creating the installer.
+</Warning>
+
+### Custom path mapping
+
+Most projects can use the default `app:///` paths. Set `normalizeStackPath` only when your build directory cannot be represented relative to the application root:
+
+```ts main.ts
+await init({
+  // Other options
+  normalizeStackPath: (absolutePath) => {
+    const normalized = absolutePath.replace(/\\/g, '/');
+    const match = /\/public(\/dist\/.+)$/.exec(normalized);
+    return match ? match[1] : undefined;
+  },
+});
+```
+
+This callback applies to main-process and bridged renderer stacks. Returning `undefined` lets the SDK apply its default rule.
+
+## Symbolicate native crashes
+
+Native crashes come from Electron `crashReporter` minidumps. Without symbols, the stack contains modules and addresses:
+
+```text
+0  Electron Framework  0x000000010ab12345
+1  libsystem_kernel    0x00007ff81a2b3c4d
+```
+
+After matching Breakpad symbols are uploaded, Flashduty can restore function names, file names, and line numbers.
+
+### 1. Prepare symbol files
+
+Download the symbol bundle from [Electron releases](https://github.com/electron/electron/releases) that exactly matches the Electron **version, operating system, and CPU architecture** you ship:
+
+```text
+electron-v<version>-<platform>-<arch>-symbols.zip
+```
+
+Most frames in a native crash are usually inside Electron modules, so upload the official Electron symbols first.
+
+If the application includes native modules or `.node` plugins, use [dump_syms](https://github.com/mozilla/dump_syms) to generate `.sym` files for them.
+
+### 2. Upload symbols
+
+Place the `.sym` files under one directory, then run:
+
+```bash
+flashcat-cli electron-symbols upload ./breakpad_symbols \
+  --service my-electron-app \
+  --release-version 1.4.2
+```
+
+Use `--dry-run` to preview the files before uploading.
+
+Native symbols match by module ID. `service` and `release-version` label the upload batch for discovery; they do not participate in symbol matching. This differs from JavaScript source maps.
+
+### 3. Publish symbols with each release
+
+Module IDs can change whenever Electron is upgraded or a native module is rebuilt. Upload symbols for every operating system and CPU architecture that you ship.
+
+Missing symbols do not prevent crash reporting. You can receive a crash with address-only frames and upload symbols later; historical crashes are symbolicated when viewed.
+
+## Verify symbolication
+
+### JavaScript errors
+
+1. Trigger an error with a stable stack in a test build.
+2. Confirm the event `service` and `version` in error details.
+3. Compare the stack frame path with `--minified-path-prefix`.
+4. Confirm that error details show the original file, function, and source location.
+
+### Native crashes
+
+1. Trigger a test crash using the same Electron build as the release.
+2. Restart the application so the SDK can report the minidump.
+3. Confirm that Electron module frames display function names and line numbers.
+
+If upload succeeds but the stack remains unresolved, see [Electron SDK troubleshooting](/en/rum/sdk/electron/faq#why-did-a-source-map-upload-succeed-without-restoring-the-stack).
+
+## Related pages
+
+<CardGroup cols={2}>
+<Card title="Advanced configuration" icon="sliders" href="/en/rum/sdk/electron/advanced-config">
+Configure versions, path mapping, and other advanced options.
+</Card>
+
+<Card title="Data collection" icon="database" href="/en/rum/sdk/electron/data-collection">
+Learn how JavaScript errors and native crashes are collected.
+</Card>
+</CardGroup>

en/rum/sdk/electron/compatible.mdx

@@ -0,0 +1,119 @@
+---
+title: "Electron SDK troubleshooting"
+description: "Troubleshoot missing Electron RUM data, process bridging, Session Replay, and stack symbolication"
+keywords: ["RUM", "Electron SDK", "troubleshooting", "Session Replay", "bridge", "source maps"]
+---
+
+Use the symptom you see in the application or Flashduty console to find the relevant checks.
+
+<AccordionGroup>
+<Accordion title="Why is there no data in the console?">
+Check the following in order:
+
+1. Confirm that main-process `init()` returns `true`, and check the main-process console for configuration errors.
+2. Confirm that `applicationId`, `clientToken`, and `service` are non-empty strings.
+3. Confirm that the application can reach `https://browser.flashcat.cloud/api/v2/rum` or your self-hosted endpoint.
+4. Wait for one upload cycle. Regular RUM events upload every 10 seconds by default.
+5. Filter with `source:electron OR container.source:electron` in the Explorer.
+
+During integration testing, set `batchSize: 'SMALL'` and `uploadFrequency: 'FREQUENT'` to shorten the wait.
+</Accordion>
+
+<Accordion title="Why do I only see main-process data?">
+If `source: electron` events appear but renderer views, actions, and resources do not, check that:
+
+1. The renderer installs and initializes `@flashcatcloud/browser-rum`.
+2. The main process finishes `init()` before creating a `BrowserWindow`.
+3. For an unbundled main process, `instrument` is imported before `electron`.
+4. For a bundled main process, the matching Vite, Webpack, or esbuild plugin is configured.
+
+After successful renderer integration, renderer events contain `container.source: electron`.
+</Accordion>
+
+<Accordion title="Why is container.source missing from renderer events?">
+A missing `container.source` means the Browser SDK did not use the Electron bridge and uploaded as a standalone web page.
+
+Common causes include:
+
+- The main process did not start instrumentation.
+- The bundle did not preserve the Electron SDK or its preload.
+- SDK initialization failed.
+
+First, verify the build setup under [Integration steps](/en/rum/sdk/electron/sdk-integration#integration-steps), then restart the application.
+
+The current window does not need `allowedWebViewHosts`. Use that option only for third-party pages in a `<webview>` or `BrowserView`.
+</Accordion>
+
+<Accordion title="Why is Session Replay missing?">
+Check each requirement:
+
+1. `@flashcatcloud/browser-rum` is version 0.0.7 or later.
+2. The renderer sets both `sessionReplaySampleRate` and `sessionReplayDirectUpload: true`.
+3. `sessionReplaySampleRate` is greater than 0 and the current session is sampled.
+4. The page CSP allows `worker-src blob:`.
+5. The CSP `connect-src` contains the actual replay upload endpoint.
+6. A self-hosted deployment sets `proxy` in the renderer.
+
+Open the renderer DevTools Console and Network panels. A blocked Worker produces a CSP error in Console. An invalid upload endpoint produces failed replay requests in Network.
+</Accordion>
+
+<Accordion title="Why is part of a replay missing or visually corrupted?">
+The renderer uploads replay segments directly and does not use the main-process disk buffer.
+
+When the device is truly offline, the Browser SDK places segments in an in-memory queue and retries after connectivity returns. If the device appears online but a request fails because of DNS, a proxy, gateway, security software, or an intake outage, the failed segment is not queued. Later segments may not contain the full snapshot needed to reconstruct the page, causing a gap or visual corruption.
+
+Check that:
+
+- Firewalls and endpoint security software allow the upload host.
+- DNS and proxy settings can reach the endpoint reliably.
+- The page CSP allows the actual replay endpoint.
+- Your self-hosted forwarding service remains available.
+
+A segment that was already dropped cannot be recovered from main-process storage.
+</Accordion>
+
+<Accordion title="Why does a self-hosted deployment receive regular events but no replay?">
+Regular RUM events and Session Replay use separate upload paths:
+
+- Regular events are bridged to the main process and use main-process `site` or `proxy`.
+- Replay segments upload directly from the renderer and use the renderer Browser SDK `proxy`.
+
+Configuring only the main process does not change the replay endpoint. Set `proxy` in `flashcatRum.init()` and add it to the page CSP `connect-src` directive.
+
+See [Custom upload endpoints](/en/rum/sdk/electron/advanced-config#custom-upload-endpoints) for a complete example.
+</Accordion>
+
+<Accordion title="Why did a source map upload succeed without restoring the stack?">
+Flashduty matches source maps using `service`, `version`, and the minified file path. Check that:
+
+1. `--service` matches the process that produced the error.
+2. `--release-version` matches that process's `version`.
+3. The renderer also sets `version`; the main-process version does not propagate to renderer events.
+4. `--minified-path-prefix` matches the directory in the stack frame shown in error details.
+5. Main-process and renderer artifacts were uploaded separately.
+
+For `app:///dist/renderer/index.js`, use `/dist/renderer` as the prefix. Do not include `app:///`.
+
+See [Electron error symbolication](/en/rum/sdk/electron/error-symbolication#symbolicate-javascript-errors) for the complete workflow.
+</Accordion>
+
+<Accordion title="Why do native crash stacks contain only addresses?">
+Native minidumps do not use JavaScript source maps. Upload Breakpad symbols that match the exact application release, operating system, and CPU architecture.
+
+Start with the official symbol bundle for your Electron version. If the application includes native modules or `.node` plugins, generate and upload `.sym` files for those modules as well.
+
+After upload, historical crashes can also be symbolicated when viewed. See [Symbolicate native crashes](/en/rum/sdk/electron/error-symbolication#symbolicate-native-crashes).
+</Accordion>
+</AccordionGroup>
+
+## If the issue continues
+
+When you contact support, include:
+
+- Electron, `@flashcatcloud/electron-sdk`, and `@flashcatcloud/browser-rum` versions
+- Bundler and module format
+- Main-process initialization options with the Client Token removed
+- Main-process and renderer console errors
+- Failed request URL, status code, and error type
+
+Do not send Client Tokens, server-side keys, or data that contains user-sensitive information.