APIs for User Monitoring and Replay
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;
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;
[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;
[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;
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;
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;
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);
Calculated Duration
Start transaction marker.
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.
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.
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.
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.
try {
...
} catch(ex) {
germainApm.log('ERROR', 'My function ABC failed.', ex);
}
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'});
Component: RUM JS
Feature Availability: 2022.2 or later