APIs for User Monitoring and Replay

⚙️ 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:

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

🛠️ 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

🛠️ 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

✨ Custom Data API

The Custom Data API allows developers to generate organization- or application-specific monitoring data.

Custom data can be created as:

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:

☑️ 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

🛠️ 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

🛠️ 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:

1. Provide the duration directly.

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

🛠️ 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;

⏹️ End Transaction

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

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

‼️ 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

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:

1. Deploy the change in a test or non-production environment.

2. Start a monitored session.

3. Execute the application workflow that calls the API.

4. Confirm that the expected custom data reaches GermainUX.

5. Verify the associated KPI.

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

7. Open the associated user session when applicable.

8. Confirm that the custom data correlates with the expected user activity.

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

📚 Related Documentation

• User Monitoring & Session Replay

• Deploy User Monitoring & Session Replay

• Configure User Monitoring & Session Replay

• Session Replay Player

• User Monitoring & Session Replay KPIs

• GermainUX RUM JS

ℹ️ Get Help

The Germain Team can help you set this up. Contact GermainUX Support.