feat: expose getSessionId + stopSessionRecorder + resumeSessionRecorder methods (#173)

1. expose `getSessionId` + `stopSessionRecorder` + `resumeSessionRecorder` methods 
2. add `recordCanvas` + `sampling` options

Author: wrn14897

.changeset/eighty-kiwis-press.md

@@ -0,0 +1,5 @@
+---
+'@hyperdx/browser': patch
+---
+
+feat: expose `getSessionId` + `stopSessionRecorder` + `resumeSessionRecorder` methods, add `recordCanvas` + `sampling` options

packages/browser/README.md

@@ -20,24 +20,71 @@ HyperDX.init({
 });
 ```
 
-### (Optional) Attach User Information or Metadata
-
-Attaching user information will allow you to search/filter sessions and events in HyperDX. This can be called at any point during the client session. The current client session and all events sent after the call will be associated with the user information.
-
-`userEmail`, `userName`, and `teamName` will populate the sessions UI with the corresponding values, but can be omitted. Any other additional values can be specified and used to search for events.
+#### Options
+
+- `apiKey` - Your HyperDX Ingestion API Key.
+- `service` - The service name events will show up as in HyperDX.
+- `tracePropagationTargets` - A list of regex patterns to match against HTTP
+  requests to link frontend and backend traces, it will add an additional
+  `traceparent` header to all requests matching any of the patterns. This should
+  be set to your backend API domain (ex. `api.yoursite.com`).
+- `consoleCapture` - (Optional) Capture all console logs (default `false`).
+- `advancedNetworkCapture` - (Optional) Capture full request/response headers
+  and bodies (default false).
+- `url` - (Optional) The OpenTelemetry collector URL, only needed for
+  self-hosted instances.
+- `maskAllInputs` - (Optional) Whether to mask all input fields in session
+  replay (default `false`).
+- `maskAllText` - (Optional) Whether to mask all text in session replay (default
+  `false`).
+- `disableIntercom` - (Optional) Whether to disable Intercom integration (default `false`)
+- `disableReplay` - (Optional) Whether to disable session replay (default `false`)
+- `recordCanvas` - (Optional) Whether to record canvas elements (default `false`)
+- `sampling` - (Optional) The sampling [config](https://github.com/rrweb-io/rrweb/blob/5fbb904edb653f3da17e6775ee438d81ef0bba83/docs/recipes/optimize-storage.md?plain=1#L22) in the session recording 
+
+## Additional Configuration
+
+### Attach User Information or Metadata
+
+Attaching user information will allow you to search/filter sessions and events
+in HyperDX. This can be called at any point during the client session. The
+current client session and all events sent after the call will be associated
+with the user information.
+
+`userEmail`, `userName`, and `teamName` will populate the sessions UI with the
+corresponding values, but can be omitted. Any other additional values can be
+specified and used to search for events.
 
 ```js
 HyperDX.setGlobalAttributes({
+  userId: user.id,
   userEmail: user.email,
   userName: user.name,
   teamName: user.team.name,
   // Other custom properties...
 });
 ```
 
-### (Optional) Send Custom Actions
+### Auto Capture React Error Boundary Errors
+
+If you're using React, you can automatically capture errors that occur within
+React error boundaries by passing your error boundary component 
+into the `attachToReactErrorBoundary` function.
 
-To explicitly track a specific application event (ex. sign up, submission, etc.), you can call the `addAction` function with an event name and optional event metadata.
+```js
+// Import your ErrorBoundary (we're using react-error-boundary as an example)
+import { ErrorBoundary } from 'react-error-boundary';
+
+// This will hook into the ErrorBoundary component and capture any errors that occur
+// within any instance of it.
+HyperDX.attachToReactErrorBoundary(ErrorBoundary);
+```
+
+### Send Custom Actions
+
+To explicitly track a specific application event (ex. sign up, submission,
+etc.), you can call the `addAction` function with an event name and optional
+event metadata.
 
 Example:
 
@@ -49,20 +96,61 @@ HyperDX.addAction('Form-Completed', {
 });
 ```
 
-### (Optional) Enable Network Capture Dynamically
+### Enable Network Capture Dynamically
 
-To enable or disable network capture dynamically, simply invoke the `enableAdvancedNetworkCapture` or `disableAdvancedNetworkCapture` function as needed.
+To enable or disable network capture dynamically, simply invoke the
+`enableAdvancedNetworkCapture` or `disableAdvancedNetworkCapture` function as
+needed.
 
 ```js
 HyperDX.enableAdvancedNetworkCapture();
 ```
 
-### (Optional) React ErrorBoundary Integration
+### Stop/Resume Session Recorder Dynamically
 
-To enable automatic error tracking with ErrorBoundary, simply attach the HyperDX error handler to the ErrorBoundary component.
+To stop or resume session recording dynamically, simply invoke the
+`resumeSessionRecorder` or `stopSessionRecorder` function as needed.
 
 ```js
-import ErrorBoundary from 'react-error-boundary';
+HyperDX.resumeSessionRecorder();
+```
 
-HyperDX.attachToReactErrorBoundary(ErrorBoundary);
+### Enable Resource Timing for CORS Requests
+
+If your frontend application makes API requests to a different domain, you can
+optionally enable the `Timing-Allow-Origin`
+[header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Timing-Allow-Origin)
+to be sent with the request. This will allow HyperDX to capture fine-grained
+resource timing information for the request such as DNS lookup, response
+download, etc. via
+[PerformanceResourceTiming](https://developer.mozilla.org/en-US/docs/Web/API/PerformanceResourceTiming).
+
+If you're using `express` with `cors` packages, you can use the following
+snippet to enable the header:
+
+```js
+var cors = require('cors');
+var onHeaders = require('on-headers');
+
+// ... all your stuff
+
+app.use(function (req, res, next) {
+  onHeaders(res, function () {
+    var allowOrigin = res.getHeader('Access-Control-Allow-Origin');
+    if (allowOrigin) {
+      res.setHeader('Timing-Allow-Origin', allowOrigin);
+    }
+  });
+  next();
+});
+app.use(cors());
 ```
+
+### Retrieve Session ID
+
+To retrieve the current session ID, you can call the `getSessionId` function.
+
+```js
+const sessionId = HyperDX.getSessionId();
+```
+

packages/browser/src/index.ts

@@ -1,6 +1,8 @@
 import type { RumOtelWebConfig } from '@hyperdx/otel-web';
 import Rum from '@hyperdx/otel-web';
-import SessionRecorder from '@hyperdx/otel-web-session-recorder';
+import SessionRecorder, {
+  RumRecorderConfig,
+} from '@hyperdx/otel-web-session-recorder';
 import opentelemetry, { Attributes } from '@opentelemetry/api';
 
 import { resolveAsyncGlobal } from './utils';
@@ -20,11 +22,13 @@ type BrowserSDKConfig = {
   disableIntercom?: boolean;
   disableReplay?: boolean;
   ignoreClass?: string;
-  instrumentations?: Instrumentations;
   ignoreUrls?: IgnoreUrls;
+  instrumentations?: Instrumentations;
   maskAllInputs?: boolean;
   maskAllText?: boolean;
   maskClass?: string;
+  recordCanvas?: boolean;
+  sampling?: RumRecorderConfig['sampling'];
   service: string;
   tracePropagationTargets?: (string | RegExp)[];
   url?: string;
@@ -50,11 +54,13 @@ class Browser {
     disableIntercom = false,
     disableReplay = false,
     ignoreClass,
-    instrumentations = {},
     ignoreUrls,
+    instrumentations = {},
     maskAllInputs = true,
     maskAllText = false,
     maskClass,
+    recordCanvas = false,
+    sampling,
     service,
     tracePropagationTargets,
     url,
@@ -111,14 +117,16 @@ class Browser {
 
     if (disableReplay !== true) {
       SessionRecorder.init({
-        debug,
-        url: `${urlBase}/v1/logs`,
         apiKey,
-        maskTextSelector: maskAllText ? '*' : undefined,
-        maskAllInputs: maskAllInputs,
         blockClass,
+        debug,
         ignoreClass,
+        maskAllInputs: maskAllInputs,
         maskTextClass: maskClass,
+        maskTextSelector: maskAllText ? '*' : undefined,
+        recordCanvas,
+        sampling,
+        url: `${urlBase}/v1/logs`,
       });
     }
 
@@ -154,6 +162,22 @@ class Browser {
     }
   }
 
+  stopSessionRecorder(): void {
+    if (!hasWindow()) {
+      return;
+    }
+
+    SessionRecorder.stop();
+  }
+
+  resumeSessionRecorder(): void {
+    if (!hasWindow()) {
+      return;
+    }
+
+    SessionRecorder.resume();
+  }
+
   addAction(name: string, attributes?: Attributes): void {
     if (!hasWindow()) {
       return;
@@ -191,6 +215,10 @@ class Browser {
     Rum.setGlobalAttributes(attributes);
   }
 
+  getSessionId(): string | undefined {
+    return Rum.getSessionId();
+  }
+
   getSessionUrl(): string | undefined {
     const now = Date.now();
     // A session can only last 4 hours, so we just need to give a time hint of