Browser

The HyperDX browser SDK allows you to instrument your frontend application to send events to HyperDX. This allows you to see frontend network requests and exceptions alongside backend events in a single timeline.

Additionally, it'll automatically capture and correlate session replay data, so you can visually step through and debug what a user was seeing while using your application.

This Guide Integrates:

Getting Started

Install via NPM (Recommended)

Use the following command to install the HyperDX Browser package (opens in a new tab).

npm install @hyperdx/browser

Initialize HyperDX

import HyperDX from '@hyperdx/browser';
 
HyperDX.init({
  apiKey: '<YOUR_API_KEY_HERE>',
  service: 'my-frontend-app',
  tracePropagationTargets: [/api.myapp.domain/i], // Set to link traces from frontend to backend requests
  consoleCapture: true, // Capture console logs (default false)
  advancedNetworkCapture: true, // Capture full HTTP request/response headers and bodies (default false)
});

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).

(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.

HyperDX.setGlobalAttributes({
  userId: user.id,
  userEmail: user.email,
  userName: user.name,
  teamName: user.team.name,
  // Other custom properties...
});

(Optional) 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:

HyperDX.addAction('Form-Completed', {
  formId: 'signup-form',
  formName: 'Signup Form',
  formType: 'signup',
});

(Optional) Enable Network Capture Dynamically

To enable or disable network capture dynamically, simply invoke the enableAdvancedNetworkCapture or disableAdvancedNetworkCapture function as needed.

HyperDX.enableAdvancedNetworkCapture();

Install via Script Tag (Alternative)

You can also include and install the script via a script tag as opposed to installing via NPM. This will expose the HyperDX global variable and can be used in the same way as the NPM package.

This is recommended if your site is not currently built using a bundler.

<script src="//www.unpkg.com/@hyperdx/browser@0.18.4/build/index.js"></script>
<script>
  window.HyperDX.init({
    apiKey: '<YOUR_API_KEY_HERE>',
    service: 'my-frontend-app',
    tracePropagationTargets: [/api.myapp.domain/i], // Set to link traces from frontend to backend requests
  });
</script>

(Optional) 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 (opens in a new tab) 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 (opens in a new tab).

If you're using express with cors packages, you can use the following snippet to enable the header:

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());

Source (opens in a new tab)