APIs of User Monitoring and Session Replay

ComponentsRUM JSRUM ExtRUM Windows

Availability2017.1 or later

Run API

Control RUM JS lifecycle

Custom Data API

Create app-specific monitoring data

Create a Transaction

Time custom user activities

Create a Log

Write custom monitoring logs

User Monitoring & Session Replay APIs

Overview

GermainUX RUM JS provides JavaScript APIs that allow developers to control User Monitoring and generate custom monitoring data directly from a monitored web application. The APIs are organized into two main groups:

API Group	Description
Run API	start, stop, or uninstall User Monitoring.
Custom Data API	create custom UX Events, Metrics, Transactions, and Logs.

These APIs are useful when an application requires monitoring behavior or business context beyond the standard RUM JS configuration.

Run API

The Run API allows an application to control the RUM JS monitoring lifecycle. Available operations include:

Start Monitoring
Stop Monitoring
Uninstall Monitoring

Start Monitoring

User Monitoring normally starts automatically after the germainapm.js script has been downloaded and loaded by the monitored application. Therefore, start() does not normally need to be called explicitly. Use it when monitoring has previously been stopped using germainApm.stop().

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

Parameters

Parameter	Description
`settings`	RUM JS monitoring settings.
`onAllTabs`	Optional. If `true`, starts monitoring on all open tabs when `BroadcastChannel` is supported. If `false`, starts monitoring only on the active tab. Default: `false`.

Example

germainApm.start(settings);

Stop Monitoring

Use stop() to immediately stop User Monitoring.

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

Stopping monitoring:

Uninstalls the active monitoring instrumentation.
Does not remove the germainApm code from the monitored page.
Does not immediately flush collected data.
Allows monitoring to restart following the next full server-side page load, such as a hard navigation or browser refresh.

Parameters

Parameter	Description
`onAllTabs`	Optional. If `true`, stops monitoring on all monitored tabs when `BroadcastChannel` is supported. If `false`, stops monitoring only on the active tab. Default: `true`.

Example

germainApm.stop();

Uninstall Monitoring

Use uninstall() to stop monitoring, flush available data from the browser cache, and optionally clear the monitoring state.

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

Internally, uninstall() calls:

germainApm.stop(onAllTabs);

A custom logout-event generator should use:

germainApm.uninstall(true, true);

Monitoring can restart on the next full server-side page load.

Parameters

Parameter	Description
`clearSessionState`	Optional. If `true`, clears monitoring state from browser storage and removes monitoring metadata. If `false`, the monitoring state remains in browser storage. Default: `false`.
`onAllTabs`	Optional. If `true`, stops monitoring on all monitored tabs when `BroadcastChannel` is supported. If `false`, affects only the active tab. Default: `false`.

Custom Data API

The Custom Data API allows developers to generate organization- or application-specific monitoring data. Custom data can be created as:

UX Events
Metrics
Transactions
Logs

This makes it possible to add application-specific and business-specific context to the data automatically captured by GermainUX. For example, an application could generate custom data for:

Login activity
Checkout steps
Add-to-cart actions
Search activity
Workflow milestones
Business errors

Show all 9

Application states
Processing durations
Custom performance measurements

Create an Event

Use createEvent() to create a custom UX Event.

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

The generated data is associated with the Browser Event KPI.

Parameters

Parameter	Description
`name`	Event name.
`details`	Optional JavaScript object containing additional information about the event.

Example

germainApm.api.createEvent('Checkout Started', {
    cartItems: 3,
    checkoutType: 'guest'
});

Create a Metric

Use createMetric() to create a custom UX Metric with a numeric value.

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

The generated data is associated with the Browser Metric KPI.

Parameters

Parameter	Description
`name`	Metric name.
`value`	Numeric value of the metric.
`details`	Optional JavaScript object containing additional information about the metric.

Example

germainApm.api.createMetric('Search Results', 27, {
    searchType: 'product'
});

Create a Transaction

Use a custom Transaction when you want to measure a user or application activity that has a duration. The generated data is associated with the Browser Transaction KPI. GermainUX supports two approaches:

Provide the duration directly.
Allow GermainUX to calculate the duration between start and end markers.

Transaction with a Known Duration

When the duration is already known, use:

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

Parameters

Parameter	Description
`name`	Transaction name.
`duration`	Transaction duration. Use seconds to remain consistent with other transactions.
`details`	Optional JavaScript object containing additional information about the transaction.

Example

germainApm.api.createTransaction(
    'Order Submission',
    2.4,
    {
        orderType: 'standard'
    }
);

Transaction with a Calculated Duration

When the duration is not known in advance, use startTransaction() and endTransaction().

Start Transaction

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

Parameter	Description
`name`	Unique transaction name used to identify the transaction when it is ended.
`details`	Optional JavaScript object containing additional information about the transaction.

End Transaction

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

Parameter	Description
`name`	Name of a transaction that was previously started.
`details`	Optional JavaScript object containing additional information about the transaction.

The same transaction name must be used to start and end the transaction.

Example

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

// Application performs the login operation

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

This allows GermainUX to calculate the transaction duration automatically.

Create a Log

Use germainApm.log() to generate a custom internal monitoring log event.

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

Logs can be accessed from the monitored window through:

germainApm.rootWindow.state.debugLog

To collect logs, configure the following RUM JS settings in the Init Script:

MonitoringSettings.constants.logLevelToEmitAsFacts
MonitoringSettings.constants.logLevel

Collected log data is associated with the Germain Agent Debug KPI.

Parameters

Parameter	Description
`level`	Log level: `TRACE`, `INFO`, `WARN`, `ERROR`, or `NONE`.
`message`	Main log message.
`obj`	Optional JavaScript object containing additional information.

‼ Log an Error

For example:

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

Log Trace Information

For example:

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

Using Custom Data with Session Replay

Custom Events, Metrics, and Transactions provide additional application and business context for User Monitoring. For example: User starts checkout ↓ Application calls:

germainApm.api.createEvent('Checkout Started');

↓ GermainUX captures the event in the user’s monitoring context ↓ The event can be analyzed using the applicable KPI and correlated with the user session. This is useful when an important business action cannot be reliably identified from standard browser activity alone.

Choosing the Appropriate Custom Data Type

Data Type	Use When
Event	Something happened at a specific point in time.
Metric	You need to capture a numeric value.
Transaction	You need to measure an activity with a duration.
Log	You need application or diagnostic information for monitoring or troubleshooting.

For example: Customer clicked Place Order → Event Shopping cart contains 7 products → Metric Checkout took 4.8 seconds → Transaction Checkout JavaScript function threw an exception → Log

Validate Custom Data

After implementing an API:

Deploy the change in a test or non-production environment

Start a monitored session

Execute the application workflow that calls the API

Confirm that the expected custom data reaches GermainUX

Verify the associated KPI

Confirm the event, metric, or transaction contains the expected details

Open the associated user session when applicable

Confirm that the custom data correlates with the expected user activity

Validate that sensitive information is not included in custom details objects

Security & Privacy

Custom API calls can include application-specific information through their details objects. Do not send passwords, authentication tokens, secrets, payment information, or other sensitive information through custom monitoring data. Before production deployment:

Review the information included in custom data.
Minimize personally identifiable information.
Apply applicable masking and privacy requirements.
Validate access permissions.
Avoid exposing credentials or secrets in logs.
Test custom API calls with controlled sessions.

Additional Resources

Troubleshoot User Monitoring and Session Replay
AI Insights & Recommendations
More Analytics Features
More Automation Features
Dashboard & Reports
Management Features.

Get Help

Contact GermainUX Support

The Germain Team can help you set this up.

Can't find what you need?

Search all GermainUX docs with Ctrl + K, or use the feedback buttons at the bottom of this page to tell us what is missing.

The content of this document is proprietary to GERMAIN SOFTWARE.

Run API

Custom Data API

Create a Transaction

Create a Log

​User Monitoring & Session Replay APIs

​Overview

​Run API

​Start Monitoring

​Parameters

​Example

​Stop Monitoring

​Parameters

​Example

​Uninstall Monitoring

​Parameters

​Custom Data API

​Create an Event

​Parameters

​Example

​Create a Metric

​Parameters

​Example

​Create a Transaction

​Transaction with a Known Duration

​Parameters

​Example

​Transaction with a Calculated Duration

​Start Transaction

​End Transaction

​Example

​Create a Log

​Parameters

​‼ Log an Error

​Log Trace Information

​Using Custom Data with Session Replay

​Choosing the Appropriate Custom Data Type

​Validate Custom Data

​Security & Privacy

​Additional Resources

​Get Help

Contact GermainUX Support

Can't find what you need?

User Monitoring & Session Replay APIs

Overview

Run API

Start Monitoring

Parameters

Example

Stop Monitoring

Parameters

Example

Uninstall Monitoring

Parameters

Custom Data API

Create an Event

Parameters

Example

Create a Metric

Parameters

Example

Create a Transaction

Transaction with a Known Duration

Parameters

Example

Transaction with a Calculated Duration

Start Transaction

End Transaction

Example

Create a Log

Parameters

‼ Log an Error

Log Trace Information

Using Custom Data with Session Replay

Choosing the Appropriate Custom Data Type

Validate Custom Data

Security & Privacy

Additional Resources

Get Help