Feature

Germain UX RUM JS comes with the following JavaScript APIs:

  • Run API

  • Custom Data API.

Run API

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 germainapm.js script, injected on the monitored website, has been downloaded and loaded therefore it doesn't need to be called in normal scenario. However, if User Monitoring has been stopped via germainApm.stop() call, it can be started by calling this method.

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

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

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

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

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

[clearSessionState] If true, clears also monitoring state from the browser’s storage and removes the entire monitoring metadata. If false, keeps monitoring state in 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 custom UX event data point. This API call will generate data for Browser Event KPI.

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

name An event name.

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

Create Metric

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

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

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

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

name A transaction name.

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

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

The following code sample shows how to use the createTransaction method.

const txnStart = Date.now();
...
const txnDuration = Date.now() - txnStart;
germainApm.api.createTransaction('login-txn', txnDuration);
JS

Calculated Duration

Start transaction marker.

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

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.

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

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.

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

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.

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

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.

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

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

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

Component: RUM JS

Feature Availability: 2022.2 or later