APIs for User Monitoring and Replay

Feature

Germain UX RUM JS provides developers with the flexibility to interact with its functionality through the following JavaScript APIs:

Run API
Custom Data API.

Run API

The Germain UX RUM JS comes with the following JavaScript APIs:

Start/Stop/Uninstall

The Germain Client API allows developers to start, stop, or uninstall the injected RUM JS monitoring directly via JavaScript.

Start Monitoring

User Monitoring starts automatically once the germainapm.js script, injected on the monitored website, has been downloaded and loaded. Therefore, it doesn't need to be called in a normal scenario. However, if User Monitoring has been stopped via germainApm.stop() call, it can be started by calling this method.

JS

germainApm.start(settings: MonitoringSettings, onAllTabs?: boolean) => void;

settings: Monitoring settings.

[onAllTabs]: If true, start monitoring on all opened tabs only if BroadcastChannel is supported by your browser. If false, start monitoring only on the active tab. Default: false.

Stop Monitoring

Stop User Monitoring. It uninstalls all monitoring instrumentation but it doesn't remove germainApm code from the monitored page. It stops the monitoring immediately and doesn't trigger any data flush at that point. Monitoring will restart on the next full page load (server-side load must occur, e.g., hard page navigation or full page refresh via F5).

JS

germainApm.stop(onAllTabs?: boolean) => void;

[onAllTabs]: If true, stop monitoring on all monitored tabs only if BroadcastChannel is supported by your browser. If false, stop monitoring only on the active tab and keep it active on other tabs. Default: true.

Uninstall Monitoring

Stop User Monitoring, flush all data available in the browser’s cache, and, optionally, remove any available state. Internally it makes a call to germainApm.stop(onAllTabs). Custom logout event generator should call germainApm.uninstall(true, true). Monitoring will restart on the next full page load (server-side load must occur, e.g., hard page navigation or full page refresh via F5).

JS

germainApm.uninstall(clearSessionState?: boolean, onAllTabs?: boolean) => void;

[clearSessionState]: If true, clears also monitoring state from the browser’s storage and removes the entire monitoring metadata. If false, keeps monitoring state in the browser’s storage. Default: false.

[onAllTabs]: If true, stop monitoring on all monitored tabs only if BroadcastChannel is supported by your browser. If false, stop monitoring only on the active tab and keep it active on other tabs. Default: false.

Custom Data API

The Germain Client API allows developers to generate custom data points via JavaScript API or, in other words, you can create your own UX Event, Log, Metric, and/or Transaction.

Create Event

Create a custom UX event data point. This API call will generate data for Browser Event KPI.

JS

germainApm.api.createEvent(name: string, details?: Record<string, any>) => void;

name: An event name.

[details]: An optional JavaScript object containing additional information about this event.

Create Metric

Create a custom UX metric data point with a numeric value. This API call will generate data for Browser Metric KPI.

CODE

germainApm.api.createMetric(name: string, value: number, details?: Record<string, any>) => void;

name: A metric name.

value: A metric numeric value.

[details]: An optional JavaScript object containing additional information about this metric.

Create Transaction

Create custom UX transaction data point with a duration. There are two ways of creating a transaction, either duration is known and provided at the moment of creating a data point or duration is not known and has to be calculated between start and end markers. This API call will generate data for Browser Transaction KPI.

Provided Duration

CODE

germainApm.api.createTransaction(name: string, duration: number, details?: Record<string, any>) => void;

name: A transaction name.

duration: A transaction duration. To keep consistent with other transactions, use seconds as the unit.

[details]: An optional JavaScript object containing additional information about this transaction.

Calculated Duration

Start transaction marker.

CODE

germainApm.api.startTransaction(name: string, details?: Record<string, any>) => void;

name: A transaction unique name. It will identify this transaction and must be used to close it.

[details] An optional JavaScript object containing additional information about this transaction.

End transaction marker.

CODE

germainApm.api.endTransaction(name: string, details?: Record<string, any>) => void;

name A transaction name to close. Must be one of the transaction name that has been started beforehand.

[details] An optional JavaScript object containing additional information about this transaction.

The following code sample shows how to create a transaction using startTransaction and endTransaction methods.

JS

germainApm.api.startTransaction('login-txn');
...
germainApm.api.endTransaction('login-txn');

Create Log

Create custom internal monitoring log event. Logs can be accessed by calling germainApm.rootWindow.state.debugLog on the monitored window.

Configure MonitoringSettings.constants.logLevelToEmitAsFacts and MonitoringSettings.constants.logLevel in your Init Script to collect logs. This API call will generate data for Germain Agent Debug KPI.

JS

germainApm.log(level: 'TRACE'|'INFO'|'WARN'|'ERROR'|'NONE', message: string, obj?: Object) => void;

level Log level type.

message Log main content message.

[details] An optional JavaScript object containing additional information about this log.

The following code sample shows how to create a log in a caught exception.

JS

try {
  ...
} catch(ex) {
  germainApm.log('ERROR', 'My function ABC failed.', ex);
}

The following code sample shows how to create a log with trace information.

JS

germainApm.log('TRACE', 'My trace information', {timestamp: Date.now(), details: 'Additional content'});

Component: RUM JS

Feature Availability: 2022.2 or later