> ## 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 for Browser Monitoring

> GermainUX provides JavaScript APIs that let developers control browser monitoring and create custom events, metrics, transactions, and diagnostic logs.

Components
[`JS Profiler`](/main/germain-ux-js-profiler)
[`RUM JS`](/main/germain-ux-rum-js)
[`RUM Extension`](/main/germain-ux-rum-extension)

Availability
2021.1 or later

Browser support
only latest Chrome, Edge and Opera

> **[Component support](#component-support)**
>
> Supported browser components list

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

> **[Create a trace log](#create-a-trace-log)**
>
> Emit trace logs sparingly

> **[Deployment and configuration](#deployment-and-configuration)**
>
> Deploy and configure APIs

## Overview

GermainUX provides JavaScript APIs that allow developers to control browser monitoring and create application-specific events, metrics, transactions, and diagnostic logs.

Most browser monitoring is automatic and does not require API calls. Use these APIs when the application needs to control monitoring programmatically or send business and technical data that GermainUX cannot detect automatically.

## Component support

| Component | API role |
| - | - |
| [GermainUX RUM JS](/main/germain-ux-rum-js.md) | Provides the `germainApm` JavaScript APIs documented on this page. |
| [GermainUX RUM Extension](/main/germain-ux-rum-extension.md) | Deploys browser monitoring when RUM JS cannot be added directly. Availability of `germainApm` to application code depends on how the extension and application context are configured. |
| [GermainUX JS Profiler](/main/germain-ux-js-profiler.md) | Provides deeper browser and JavaScript diagnostics. It is not controlled through the RUM JS APIs documented on this page. |

## API categories

| Category | Purpose |
| - | - |
| Monitoring Control API | Start, stop, or uninstall browser monitoring. |
| Custom Data API | Create application-specific events, metrics, transactions, and logs. |

## Common use cases

Use the Browser Monitoring APIs to:

* Start or stop monitoring based on consent.
* Clear monitoring state when a user signs out.
* Record an application-specific event such as `Payment Failed`.
* Record a numeric measurement such as the number of search results.
* Measure the duration of a business operation.
* Add technical context for an error handled by the application.
* Create custom browser KPIs for application-specific behavior.
* Correlate business milestones with user sessions and technical evidence.

## Monitoring Control API

### Start monitoring

Browser monitoring normally starts automatically after `germainapm.js` is downloaded and initialized. Calling `start()` is unnecessary during a standard deployment.

Use it when monitoring was previously stopped or when the application must start monitoring programmatically:

```text theme={null}
germainApm.start(
  settings: MonitoringSettings,
  onAllTabs?: boolean
): void;
```

| Parameter | Description |
| - | - |
| `settings` | Monitoring configuration to apply. |
| `onAllTabs` | When `true`, starts monitoring in all open tabs if the browser supports `BroadcastChannel`. When `false`, starts only in the active tab. Default: `false`. |

Example:

```javascript theme={null}
const settings = germainApm.getDefaultSettings();

germainApm.start(settings);
```

### Stop monitoring

Use `stop()` to remove the active monitoring instrumentation:

```text theme={null}
germainApm.stop(onAllTabs?: boolean): void;
```

| Parameter | Description |
| - | - |
| `onAllTabs` | When `true`, stops monitoring in all monitored tabs if `BroadcastChannel` is supported. When `false`, stops only the active tab. Default: `true`. |

Example:

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

Calling `stop()`:

* Stops monitoring immediately.
* Removes the active monitoring instrumentation.
* Does not flush data still waiting in the browser.
* Does not remove the `germainApm` code from the page.
* Does not necessarily clear the stored monitoring state.
* Allows monitoring to start again after a full page load, hard navigation, or browser refresh.

Use `uninstall()` instead when pending data must be flushed or the stored monitoring state must be cleared.

### Uninstall monitoring

Use `uninstall()` to stop monitoring, flush data available in the browser cache, and optionally remove the stored monitoring state:

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

| Parameter | Description |
| - | - |
| `clearSessionState` | When `true`, removes monitoring state and metadata stored in the browser. Default: `false`. |
| `onAllTabs` | When `true`, uninstalls monitoring from all monitored tabs when `BroadcastChannel` is supported. Default: `false`. |

A custom logout handler should use:

```text theme={null}
germainApm.uninstall(true, true);
```

This helps prevent the next authenticated user from inheriting monitoring metadata associated with the previous user.

Monitoring can start again after a full page load, hard navigation, or browser refresh.

## Multi-tab behavior

The optional `onAllTabs` parameter uses the browser’s `BroadcastChannel` capability.

When supported:

* `start(..., true)` can start monitoring across open tabs.
* `stop(true)` can stop monitoring across monitored tabs.
* `uninstall(..., true)` can uninstall monitoring across monitored tabs.

When the browser does not support `BroadcastChannel`, the operation cannot be propagated to other tabs through this mechanism.

## Custom Data API

The Custom Data API captures application-specific information that GermainUX does not collect automatically.

| Custom data | GermainUX KPI |
| - | - |
| Event | Browser Event |
| Metric | Browser Metric |
| Transaction | Browser Transaction |
| Log | Germain Agent Debug |

## Create a custom event

Use `createEvent()` to record a discrete application or business event:

```text theme={null}
germainApm.api.createEvent(
  name: string,
  details?: Record<string, any>
): void;
```

| Parameter | Description |
| - | - |
| `name` | Event name. |
| `details` | Optional object containing additional context. |

Example:

```text theme={null}
germainApm.api.createEvent("Product Added to Wishlist", {
  productId: "SKU-123",
  category: "Shoes"
});
```

This creates a data point under the **Browser Event** KPI.

Other examples include:

* `Payment Failed`
* `Checkout Completed`
* `Search Returned No Results`
* `User Changed Subscription`
* `Document Uploaded`

Use stable event names so GermainUX can aggregate and analyze occurrences consistently.

## Create a custom metric

Use `createMetric()` to record a numeric measurement:

```text theme={null}
germainApm.api.createMetric(
  name: string,
  value: number,
  details?: Record<string, any>
): void;
```

| Parameter | Description |
| - | - |
| `name` | Metric name. |
| `value` | Numeric value to record. |
| `details` | Optional object containing additional context. |

Example:

```text theme={null}
germainApm.api.createMetric("Search Result Count", 12, {
  category: "Running Shoes"
});
```

This creates a data point under the **Browser Metric** KPI.

Other examples include:

* Number of search results.
* Cart value.
* Number of records displayed.
* Queue depth shown to a user.
* Number of validation failures.

Do not send numeric values as formatted strings.

## Create a transaction with a known duration

Use `createTransaction()` when the duration has already been calculated:

```text theme={null}
germainApm.api.createTransaction(
  name: string,
  duration: number,
  details?: Record<string, any>
): void;
```

| Parameter | Description |
| - | - |
| `name` | Transaction name. |
| `duration` | Transaction duration. Use seconds for consistency with GermainUX transactions. |
| `details` | Optional object containing additional context. |

Example:

```text theme={null}
germainApm.api.createTransaction("Quote Generated", 2.45, {
  quoteType: "Renewal"
});
```

This creates a data point under the **Browser Transaction** KPI.

## Measure a transaction between start and end

Use `startTransaction()` and `endTransaction()` when GermainUX should calculate the duration.

Start the transaction:

```text theme={null}
germainApm.api.startTransaction(
  name: string,
  details?: Record<string, any>
): void;
```

End the transaction:

```text theme={null}
germainApm.api.endTransaction(
  name: string,
  details?: Record<string, any>
): void;
```

Example:

```text theme={null}
germainApm.api.startTransaction("Generate Report", {
  reportType: "Weekly Sales"
});

// Application operation

germainApm.api.endTransaction("Generate Report", {
  outcome: "Completed"
});
```

The same transaction name must be used for the start and end calls. The resulting duration is recorded under the **Browser Transaction** KPI.

Suitable transactions include:

* Authentication.
* Search.
* Quote generation.
* Document upload.
* Checkout.
* Report generation.
* Record creation.
* Application-specific workflow steps.

Ensure that every started transaction can reach an end call, including failure paths when appropriate.

## Create a diagnostic log

Use `germainApm.log()` to add a custom internal monitoring log:

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

| Parameter | Description |
| - | - |
| `level` | Log severity. |
| `message` | Primary log message. |
| `obj` | Optional object containing additional context. |

Example:

```text theme={null}
germainApm.log("INFO", "Checkout step completed", {
  step: "Shipping"
});
```

Logs are available in the browser through:

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

To send selected logs to GermainUX as data points, configure:

* `MonitoringSettings.constants.logLevel`
* `MonitoringSettings.constants.logLevelToEmitAsFacts`

Collected logs are available under the **Germain Agent Debug** KPI.

## Log a handled exception

An exception handled by the application may not be visible to automatic unhandled-error monitoring. Use a custom log when the failure requires diagnostic visibility:

```text theme={null}
try {
  runApplicationOperation();
} catch (error) {
  germainApm.log(
    "ERROR",
    "Application operation failed",
    error
  );
}
```

Do not log an exception automatically if it may contain sensitive data that has not been reviewed or sanitized.

## Create a trace log

```text theme={null}
germainApm.log("TRACE", "Application state changed", {
  timestamp: Date.now(),
  state: "WaitingForApproval"
});
```

Trace logging can generate substantial data. Enable and emit it only when required for a defined diagnostic use case.

## From custom data to analytics

Custom events, metrics, and transactions become available for GermainUX analysis:

| API | KPI | Example analysis |
| - | - | - |
| `createEvent()` | Browser Event | Count users affected by `Payment Failed`. |
| `createMetric()` | Browser Metric | Analyze average search-result count by page or user role. |
| `createTransaction()` | Browser Transaction | Analyze checkout duration by browser. |
| `startTransaction()` and `endTransaction()` | Browser Transaction | Measure application-specific workflow duration. |
| `germainApm.log()` | Germain Agent Debug | Investigate application-specific technical conditions. |

These data points can be analyzed using measures, pivots, trends, drill-through, user-session context, and applicable custom insights.

A Custom Replay Insight can expose a selected event—such as **Payment Failed** or **Checkout Completed**—on the Session Replay timeline whenever it occurs in a user session.

A Watch can notify GermainUX users when an existing event, metric, transaction, or other insight meets conditions of interest. A Watch does not create the underlying insight.

## Naming recommendations

Use names that are:

* Stable across application releases.
* Specific enough to identify the business or technical condition.
* Consistent in capitalization and wording.
* Independent of dynamic values.
* Suitable for aggregation.

Recommended:

```text theme={null}
Payment Failed
Checkout Completed
Quote Generated
Search Result Count
```

Avoid:

```text theme={null}
Payment failed for user 18462 at 10:43:19
```

Place dynamic context in the `details` object instead of the name.

## Privacy and security

Custom API calls can send application data to GermainUX. Before adding custom details or logs:

* Do not collect passwords, access tokens, authentication cookies, secrets, or payment credentials.
* Avoid collecting personal information unless it is required and approved.
* Prefer internal or pseudonymous identifiers.
* Mask, hash, or remove sensitive values.
* Keep detail objects small and relevant.
* Avoid sending complete application objects, responses, or DOM elements.
* Apply the organization’s access-control and retention requirements.
* Validate custom data in a non-production environment before deployment.

The API accepts JavaScript objects, but that does not mean every property should be collected.

## Error handling

Custom monitoring must not interfere with the monitored application.

When integrating the API:

* Confirm that `germainApm` is available before calling it when monitoring may load asynchronously.
* Do not block the user workflow while waiting for a monitoring call.
* Avoid changing application behavior if monitoring is unavailable.
* Keep custom processing lightweight.
* Test consent, logout, multi-tab, and page-navigation behavior.

Example:

```javascript theme={null}
if (window.germainApm?.api) {
  window.germainApm.api.createEvent(
    "Checkout Completed"
  );
}
```

## Deployment and configuration

* Review [Browser Monitoring](/main/browser-monitoring.md).
* Review the [Browser Monitoring Deployment Overview](/main/deployment-for-browser-monitoring.md).
* Deploy [GermainUX RUM JS](/main/germain-ux-rum-js.md) to use the JavaScript APIs documented on this page.
* Deploy the [GermainUX RUM Extension](/main/germain-ux-rum-extension.md) when direct RUM JS deployment is unavailable; validate API accessibility in the required application context.
* Deploy the [GermainUX JS Profiler](/main/germain-ux-js-profiler.md) when deeper JavaScript and browser diagnostics are required.
* Review the available [Browser Monitoring configuration](/main/configuration-for-browser-monitoring.md).

> **Show all 10**
>
> * Review [Metadata Extractors](/main/metadata-extractors.md) for application-specific user and session context.
> * Review [Custom Insights](/main/custom-insights.md) for custom KPIs and Session Replay timeline insights.
> * Review the available KPIs for Browser Monitoring.
> * Review the complete [APIs for User Monitoring and Replay](/main/user-monitoring-and-replay-apis.md).

## Get Help

> **[Contact GermainUX Support](/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.