> ## Documentation Index
> Fetch the complete documentation index at: https://docs.germainux.com/llms.txt
> Use this file to discover all available pages before exploring further.

# APIs of User Monitoring and Session Replay

> GermainUX RUM JS provides JavaScript APIs that let developers control User Monitoring and generate custom monitoring data from a monitored web application.

Components
[`RUM JS`](https://docs.germainux.com/main/germain-ux-rum-js)
[`RUM Ext`](https://docs.germainux.com/main/germain-ux-rum-extension)
[`RUM Windows`](https://docs.germainux.com/main/germainux-rum-windows)

Availability
2017.1 or later

> **[Run API](#run-api)**
>
> Control RUM JS lifecycle

> **[Custom Data API](#custom-data-api)**
>
> Create app-specific monitoring data

> **[Create a Transaction](#create-a-transaction)**
>
> Time custom user activities

> **[Create a Log](#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()`.

```typescript theme={null}
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

```text theme={null}
germainApm.start(settings);
```

### Stop Monitoring

Use `stop()` to immediately stop User Monitoring.

```typescript theme={null}
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

```text theme={null}
germainApm.stop();
```

### Uninstall Monitoring

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

```typescript theme={null}
germainApm.uninstall(clearSessionState?: boolean, onAllTabs?: boolean) => void;
```

Internally, `uninstall()` calls:

```text theme={null}
germainApm.stop(onAllTabs);
```

A custom logout-event generator should use:

```text theme={null}
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.

```typescript theme={null}
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

```text theme={null}
germainApm.api.createEvent('Checkout Started', {
    cartItems: 3,
    checkoutType: 'guest'
});
```

## Create a Metric

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

```typescript theme={null}
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

```text theme={null}
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:

```typescript theme={null}
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

```text theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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

```text theme={null}
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.

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

Logs can be accessed from the monitored window through:

```text theme={null}
germainApm.rootWindow.state.debugLog
```

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

```text theme={null}
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:

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

### Log Trace Information

For example:

```text theme={null}
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:

```text theme={null}
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:

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

## Additional Resources

* Troubleshoot User Monitoring and Session Replay
* [AI](https://docs.germainux.com/main/ai-driven-insights.md) Insights & Recommendations
* More [Analytics](https://docs.germainux.com/main/analytics.md) Features
* More [Automation](https://docs.germainux.com/main/automation.md) Features
* [Dashboard](https://docs.germainux.com/main/dashboard-and-report.md) & [Reports](https://docs.germainux.com/main/reporting-automatic.md)
* [Management](https://docs.germainux.com/main/management.md) Features.

## Get Help

> **[Contact GermainUX Support](https://docs.germainux.com/main/support.md)**
>
> 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.