APIs for Browser Monitoring

ComponentsJS ProfilerRUM JSRUM Extension

Availability2021.1 or later

Browser supportonly latest Chrome, Edge and Opera

Component support

Supported browser components list

Custom Data API

Add app-specific telemetry

Create a trace log

Emit trace logs sparingly

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	Provides the `germainApm` JavaScript APIs documented on this page.
GermainUX RUM Extension	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	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:

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:

const settings = germainApm.getDefaultSettings();

germainApm.start(settings);

Stop monitoring

Use stop() to remove the active monitoring instrumentation:

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:

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:

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:

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:

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

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

Example:

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:

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:

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:

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:

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:

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

End the transaction:

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

Example:

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:

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:

germainApm.log("INFO", "Checkout step completed", {
  step: "Shipping"
});

Logs are available in the browser through:

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:

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

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:

Payment Failed
Checkout Completed
Quote Generated
Search Result Count

Avoid:

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:

if (window.germainApm?.api) {
  window.germainApm.api.createEvent(
    "Checkout Completed"
  );
}

Deployment and configuration

Review Browser Monitoring.
Review the Browser Monitoring Deployment Overview.
Deploy GermainUX RUM JS to use the JavaScript APIs documented on this page.
Deploy the GermainUX RUM Extension when direct RUM JS deployment is unavailable; validate API accessibility in the required application context.
Deploy the GermainUX JS Profiler when deeper JavaScript and browser diagnostics are required.
Review the available Browser Monitoring configuration.

Show all 10

Review Metadata Extractors for application-specific user and session context.
Review Custom Insights for custom KPIs and Session Replay timeline insights.
Review the available KPIs for Browser Monitoring.
Review the complete APIs for User Monitoring and Replay.

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

Component support

Custom Data API

Create a trace log

Deployment and configuration

​Overview

​Component support

​API categories

​Common use cases

​Monitoring Control API

​Start monitoring

​Stop monitoring

​Uninstall monitoring

​Multi-tab behavior

​Custom Data API

​Create a custom event

​Create a custom metric

​Create a transaction with a known duration

​Measure a transaction between start and end

​Create a diagnostic log

​Log a handled exception

​Create a trace log

​From custom data to analytics

​Naming recommendations

​Privacy and security

​Error handling

​Deployment and configuration

​Get Help

Contact GermainUX Support

Can't find what you need?

Overview

Component support

API categories

Common use cases

Monitoring Control API

Start monitoring

Stop monitoring

Uninstall monitoring

Multi-tab behavior

Custom Data API

Create a custom event

Create a custom metric

Create a transaction with a known duration

Measure a transaction between start and end

Create a diagnostic log

Log a handled exception

Create a trace log

From custom data to analytics

Naming recommendations

Privacy and security

Error handling

Deployment and configuration

Get Help