@flashcatcloud/electron-sdk. The renderer uses the Browser SDK; see Web SDK advanced configuration for its general options.
Initialization options
main.ts
init() returns false when validation fails. The SDK prints the reason in the main-process console and does not start collection, but it does not prevent the application from starting.
Session sampling
Starting with Electron SDK 0.4.0, you can sample sessions.sessionSampleRate sets the share of sessions collected and defaults to 100 (every session):
main.ts
- Each session is drawn once, in the main process, and the result decides for the renderers too: renderer events reach the intake through the main process over the bridge, and the main process drops the events of sessions it did not select.
- The
sessionSampleRatein the renderer’sflashcatRum.init()does not apply to events sent over the bridge. Set it in the main process only. - A session resumed after the application restarts keeps the decision it was created with.
- Every RUM event carries the sample rate its session was drawn at (
_dd.configuration.session_sample_rate), which the platform uses to extrapolate totals.
On-error session capture
WithsessionOnError on, sessions the sample rate did not select are not dropped right away. Their events are held in memory and uploaded only if the session reports an error:
main.ts
- Events from the main process and the renderers alike are held, up to the 60 seconds before the error (also capped at 64 KiB of detail, 200 events, and 50 views). The buffer stays in memory and is never written to disk.
- At the session’s first error, what is held is uploaded together with the error within a few seconds. The session then reports like any sampled session.
- When the application may be about to exit (an uncaught main-process exception,
before-quit,will-quit, and the processexitevent), content already released by an error is written to disk first and uploaded on the next launch. For an uncaught main-process exception to count, register your ownuncaughtExceptionlistener afterawait init(...)completes. - A session that ends without an error is discarded whole, and nothing is uploaded at quit either.
- Only errors your application reports count: an error dropped by a renderer’s
beforeSend, or one the SDK reports about itself, does not. A native crash counts too, and is reported on the next launch together with the view it happened in.
0 and carries session.sampled_for_error: true on its views, so it is counted as itself rather than extrapolated by the sample rate. To filter these sessions, see session_sampled_for_error in the data query syntax guide.
Remote configuration
Starting with Electron SDK 0.4.0, the session sample rate, Capture additional sessions on error, and custom configuration keys can be adjusted online on the Application management → Remote Configuration tab in the console, without code changes or a new release. The feature is off by default; enable it when you initialize the main process:main.ts
- The main process requests the configuration at
init()and whenever a new session starts;init()does not wait for the request. A received configuration applies from the next new session, and running sessions are unaffected. The exception, as of SDK 0.5.3: setting the sample rate to0stops collection in the running session right away, and raising it from0resumes collection right away. - A value set in the console takes precedence over the initialization value. Values the console does not set, or every value while remote configuration is turned off in the console, fall back to the initialization options.
- The last accepted configuration is kept in the application’s
userDatadirectory, so new sessions after a cold start are drawn with it before the network answers, even offline. The cache applies only to the same intake, application,env, andversion. - Network failures, timeouts, and unrecognized responses keep the configuration in force; the SDK retries twice shortly afterward.
- The Electron SDK reads only the session sample rate, Capture additional sessions on error, and custom configuration keys. Session Replay is recorded and sampled by the renderer’s own Browser SDK, which remote configuration does not reach, so replay and trace options do not appear for Electron applications.
- The renderers need no remote configuration of their own; the main process owns the sessions and their sampling.
The configuration endpoint sits next to the intake at
/api/v2/rum/config: https://<site>/api/v2/rum/config when you set site. When you set proxy, the request also goes to proxy, with the target path /api/v2/rum/config carried in the ddforward parameter. For private deployments, make sure your forwarding service allows this path.getRemoteConfig(), which returns a copy, or undefined when remote configuration is off, no configuration has been received yet, or the console set none. Until the server answers, it reads from the cache on disk, so you can call it as soon as init() resolves:
main.ts
Custom upload endpoints
By default, the main process uploads regular RUM events to Flashduty SaaS. You do not need to setsite or proxy.
Use a self-hosted intake host
If your intake supports HTTPS and receives events at/api/v2/rum, set its host in site. Do not include https:// or a path:
main.ts
https://rum.example.internal/api/v2/rum.
Use a custom forwarding endpoint
Useproxy when:
- The intake only supports HTTP.
- The upload path is not
/api/v2/rum. - Clients must access the intake through a shared gateway.
main.ts
proxy is a RUM forwarding endpoint that you provide, not an operating-system or Electron network proxy. The main process adds the target path to the request. Your forwarding service must preserve the request body and DD-API-KEY header and send the request to the Flashduty intake.
After you set proxy, the main process no longer uses site to build the upload URL.
Configure a self-hosted session replay endpoint
Regular RUM events go through the main process, but the renderer uploads Session Replay directly. As a result, the main-processsite or proxy does not apply to replay segments.
For self-hosted Session Replay, set the Browser SDK proxy in the renderer:
renderer.ts
connect-src directive.
Upload batching and frequency
The main process writes regular RUM events to the application’suserData directory before uploading them in batches. A batch is deleted only after a successful upload.
During integration testing, use
batchSize: 'SMALL' and uploadFrequency: 'FREQUENT' to see events sooner. Keep the defaults for normal operation.
Disk buffering and retry apply only to regular RUM events. The renderer uploads Session Replay directly, so replay does not use the main-process disk buffer.
Collect third-party pages
The current window’s page can always use the bridge; you do not need to setallowedWebViewHosts for it. Add hosts only when you want to collect a third-party page loaded in a <webview> or BrowserView:
main.ts
example.com also allows app.example.com.
Identify the signed-in user
After sign-in, callsetUser() in the main process. Main-process events and bridged renderer events will carry the same user identity.
main.ts
When Session Replay is enabled, also call
flashcatRum.setUser() and flashcatRum.clearUser() in the renderer as part of the same sign-in and sign-out flow, because replay segments bypass the main process.
Report handled errors
An exception caught bytry/catch in the main process is not reported as an unhandled error. Call addError() to record it:
main.ts
context to filter and identify the business workflow.
End the current session
CallstopSession() when a user signs out or when you need to start a new session:
main.ts
Performance metrics for pre-created windows
Electron applications can create a hiddenBrowserWindow, load its page, and show it later. By default, the SDK rebases FCP and LCP on the first time the window becomes visible so the pre-warm delay is not counted as page performance.
To keep the raw document Paint Timing values, disable correction:
main.ts
BrowserWindow. It does not correct metrics from WebContentsView or <webview>.
Customize error stack paths
By default, the SDK rewrites stack paths under the application directory toapp:///<relative path>, allowing one source map upload to match installations on different machines. Most applications do not need to change this behavior.
If your build output layout does not match the application directory, use normalizeStackPath:
main.ts
undefined, the SDK applies its default normalization. See Electron error symbolication for upload instructions.
Related pages
SDK integration
Instrument the main and renderer processes.
Error symbolication
Upload JavaScript source maps and native crash symbols.
Data collection
Review collected data types and upload behavior.
Troubleshooting
Diagnose bridge, replay, and upload issues.