docs(rum): add Electron SDK integration docs (zh + en) - #222
Draft
Fiona2016 wants to merge 2 commits into
Draft
Conversation
Electron is the first RUM platform that requires a two-process
integration: `@flashcatcloud/electron-sdk` in the main process and
`@flashcatcloud/browser-rum` in renderers, bridged over IPC through the
`DatadogEventBridge` object that dd-trace injects via preload. Integrating
only one side is the failure mode these pages are written to prevent.
Adds four pages per language under `rum/sdk/electron/`, mirroring the
harmony/flutter page set, and registers the group in docs.json for both
languages:
- sdk-integration: install, the `instrument` entry point that must precede
`require('electron')`, bundler plugins (vite / webpack / esbuild), renderer
setup, and the `allowedWebViewHosts` allowlist that gates the bridge
- advanced-config: full init options, batching, proxy, manual reporting,
operation monitoring, source map upload
- compatible: support scope and v1 limits
- data-collection: per-process event types, fields, session rules, upload
behavior
Content is derived from the SDK source rather than upstream Datadog docs,
since the fork changed intake URL rules, the site allowlist, and dropped the
spans track.
v1 limits documented explicitly: no native crash symbolication (crashes are
stored and shown as raw addresses), no Session Replay, no APM/distributed
tracing, and no source map resolution for main-process stacks. The
`file://` install-path instability that breaks source map matching for
`loadFile()` builds is called out with the custom-protocol workaround.
Doc paths match the console's `utils/docs.ts` mapping for the electron
platform. Package versions are left unpinned, per npm platform convention.
Verified with `mint broken-links`.
Two factual errors from the first commit, both found by W1's staging smoke
test and confirmed against the source.
1. The bridge is not opt-in. The earlier text read `validateAllowedWebViewHosts()`
returning `[]` for `undefined` as "the bridge is disabled by default", but
that is the SDK-side config default, not the allowlist the browser SDK
actually sees. dd-trace's preload builds it as:
const allowedHosts = [...new Set([location.hostname, ...configuredHosts])]
The window's own hostname is always included, so a window's own page always
self-matches and the bridge works with no configuration. `file://` included:
`location.hostname` is `""` there, the allowlist becomes `[""]`, and
`canUseEventBridge("")` still matches. `allowedWebViewHosts` is for
additional third-party hosts in `<webview>` / `BrowserView`, not a switch.
2. Bridged renderer events keep `source: browser`. `Assembly.assembleRendererRumEvent()`
overrides only `session.id` and `application.id` and adds
`container.{source, view.id}` — the renderer's own `source` is preserved.
Main-process events are `source: electron` with
`view.url: electron://main-process`. Filtering on `source:electron` alone
therefore returns main-process events only; the correct filter is
`source:electron OR container.source:electron`.
Changes:
- Replace the "enable the bridge" sections with "the bridge needs no
configuration" plus a "what a broken bridge looks like" section, since the
real failure mode is a missing preload injection (main process not
integrated, or bundled without the plugin), diagnosable via a missing
`container.source`
- Add a source/container.source/view.url table to both the integration and
data-collection pages, and correct the verification steps to use the OR filter
- Drop `allowedWebViewHosts` from the basic init examples; it is not needed
- Decouple the `app://` custom-protocol recommendation from the bridge. It now
stands only on source map path stability, with an explicit note that the
bridge works fine under `file://`
- Mark the `file://` install-path limitation as affecting source map
resolution only, not collection
- Align the proxy section with the README: `site` stays required but is unused
for URL building once `proxy` is set, and name the self-hosted use case
Verified with `mint broken-links`.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds the Electron platform to the RUM SDK docs.
zh/rum/sdk/anden/rum/sdk/previously coveredweb / android / ios / flutter / harmony / wechat-miniprogram— there was noelectron.Four pages per language under
rum/sdk/electron/, mirroring the harmony/flutter page set, registered indocs.jsonfor both languages:sdk-integrationinstrumententry point, bundler plugins, renderer setup, bridge behavioradvanced-configcompatibledata-collectionWhy this platform needed more than a copy-paste
Electron is the first RUM platform with a genuinely two-process integration:
@flashcatcloud/electron-sdk, whose@flashcatcloud/electron-sdk/instrumententry point must be imported beforerequire('electron')— otherwise dd-trace cannot hookBrowserWindowand preload injection silently fails.@flashcatcloud/browser-rumand hand events to the main process over IPC through theDatadogEventBridgeobject that the dd-trace preload exposes. This requires no configuration — the preload always allows the window's own host.sdk-integrationanddata-collectionare written to prevent it.The two
sourcevaluesThis is the subtlest thing in these docs, and it is easy to get wrong.
Assembly.assembleRendererRumEvent()overrides onlysession.idandapplication.idon bridged renderer events and addscontainer— the renderer's ownsourceis preserved:sourcecontainer.sourceview.urlelectronelectron://main-processbrowserelectronFiltering on
source:electronalone returns main-process events only. The docs consistently usesource:electron OR container.source:electronfor whole-application queries.container.sourcedoubles as the diagnostic for a broken bridge: if renderer events lack it, the preload was never injected — the main process is not integrated, or it was bundled without the plugin.Sources
Content is derived from the SDK source (
sdk/fc-sdk-electron) rather than upstream Datadog docs — the fork changed intake URL rules, restricted thesiteallowlist, switched to an NDJSON body, and dropped the spans track. Console doc links inutils/docs.tsmap torum/sdk/electron/sdk-integrationandrum/sdk/electron/data-collection; both paths exist here.Package versions are left unpinned, following the convention used by the other npm-based platform docs.
v1 limits documented explicitly
defaultPrivacyLevelis forwarded but inert)file://source map matching depends on the runtime install path, which varies per machine. This affects source map resolution only — collection and the bridge are unaffectedReview note
The second commit corrects two factual errors in the first, both caught by the W1 staging smoke test: the bridge was described as opt-in via
allowedWebViewHosts(it is not — the preload always allows the window's own host,file://included), and bridged renderer events were described as carryingsource: electron(they keepsource: browserpluscontainer.source: electron). Reviewing the squashed diff is more useful than reviewing commit by commit.Verification
mint broken-linkspasses.🤖 Generated with Claude Code