Skip to main content

Collected telemetry

Data captured from controls

HTTP Monitoring Proxy

Intercept outbound HTTP traffic

Control Filter Fields

Match controls by properties

Validate the Applied Configuration

Confirm rules took effect

Overview

A monitoring rule is a JSON document that tells the GermainUX Agent which Windows application to monitor and what telemetry to collect.

Collected telemetry

  • Application and window activity
  • User clicks, searches, and keyboard commands
  • Process, CPU, memory, thread, and resource metrics
  • .NET exceptions, garbage collection, and CPU profiles
  • Application freezes
  • Outbound HTTP calls
  • User-facing errors
  • Click and mouse-movement heatmaps
  • Windows session-replay data
Most monitoring rules should be created and managed from the GermainUX administration interface. Direct JSON configuration is primarily intended for local testing, offline operation, advanced configuration, or troubleshooting.

How the Agent Receives a Monitoring Rule

The Agent resolves monitoring rules as follows:
  1. The Agent periodically retrieves the list of target applications and rule names from the GermainUX server.
  2. It retrieves each rule’s JSON configuration by name.
  3. If the server request fails, the Agent attempts to load: {Agent installation folder}\config\{ruleName}.json
  4. If a local Registry rule exists, the Agent loads the JSON file specified by: HKEY_LOCAL_MACHINE\SOFTWARE\Germain Software\Germain Agent\Targets\{executableName.exe}\ConfigFile
A local Registry rule takes priority over a server-provided rule for the same executable. It is also the only option that does not require access to a GermainUX server. For local-rule configuration, see GermainUX Agent Settings. Regardless of its origin, the resolved JSON uses the format described on this page. You can inspect the exact configuration currently applied to an application by right-clicking the GermainUX Agent tray icon and selecting Configurations.
Unless stated otherwise, configuration blocks and fields are optional. Omitting an optional feature generally leaves it disabled. The features object must be present, even when every feature inside it is disabled.

Top-Level Fields

Application Window Identification

Use monitorConfig to help the Agent identify and interpret the application’s primary window.

Data Queue and Delivery

The queue block controls how collected facts are buffered and sent to GermainUX.
Keep httpTimeoutMs shorter than the Agent’s Windows UI worker shutdown timeout. This allows a final upload to complete or fail cleanly before the Agent forcibly stops the worker.

HTTP Monitoring Proxy

The proxy block controls the local proxy used to intercept outbound HTTP traffic from the monitored application.

Diagnostic Options

The debug block enables detailed Windows UI worker diagnostics.
These options can log UI trees, sibling traversal, session-replay snapshots, and window-creation details. Keep every option set to false during normal production operation. Enable them only while working with Germain Software Support to diagnose a UI-capture issue, because they can generate significant log volume.

Logging Metadata

This block contains informational metadata associated with the rule. It does not control the actual logging level or destination used by the Windows UI worker or CLR Profiler. Actual component logging is controlled by these Registry values: You can omit the logging block or leave its default values unchanged. For the effective logging configuration, see GermainUX Agent Settings.

Global Context Variables

Global variables capture contextual information from the application’s UI and attach it to subsequently generated facts. For example, the following rule reads a displayed username, converts it to lowercase, and attaches it as username:
Typical global variables include: Global variables use the same structure as the context variables configured for userClicks.

Data Privacy, Masking, and Exclusions

Use maskAll and exclusions to control which values may leave the monitored computer.

Privacy Fields

Sanitization Types

Review privacy rules before enabling request bodies, response bodies, headers, UI values, thumbnails, or session replay in production.

Monitoring Features

All monitoring capabilities are configured under the required features object. Each feature has its own enabled setting and can be activated independently, subject to the dependencies described below.

Process Metrics

Process monitoring can collect:
  • CPU utilization
  • Working-set memory
  • Thread count and thread-level details
  • Process handle count
  • GDI and USER object counts
  • Disk-read and disk-write deltas
These metrics help identify resource leaks and performance degradation in long-running Windows applications.

.NET Garbage-Collection Metrics

When enabled, GermainUX reports:
  • Individual garbage-collection pauses
  • GC generation
  • Whether the collection was induced
  • Heap size before and after collection
  • Cumulative generation 0, 1, and 2 collection counts
interval controls how often cumulative collection counts are reported. This feature requires the CLR Profiler to be attached.

Application Freeze Detection

Freeze detection periodically sends a message to each monitored window to determine whether it remains responsive. When a frozen window becomes responsive again, GermainUX generates a fact containing the total duration of the freeze. Freeze detection uses a dedicated background thread and therefore has a small continuous resource cost. Enable it when detecting application freezes provides sufficient operational value.

.NET CPU Sampling

The CPU profiler periodically captures .NET call stacks. When both filter arrays are empty, the profiler includes all eligible code. This feature requires the CLR Profiler to be attached.

Outbound HTTP Monitoring

Outbound HTTP monitoring captures calls made by the target process and separates their timing into connection, wait, and download phases. Request bodies, response bodies, and headers can contain credentials, tokens, personal information, and other sensitive data. Configure privacy rules and exclusions before enabling them in production.

.NET Exception Monitoring

When enabled, GermainUX reports managed .NET exceptions as they are thrown, including their captured stack traces. This feature requires the CLR Profiler.

Core Windows UI Monitoring

The monitor feature is the foundation for Windows UI telemetry. The following features require monitor.enabled to be true:

Click and Mouse-Movement Heatmaps

clickMaps reports the control and screen position associated with each click, enabling click heatmaps. mouseMaps buffers mouse-movement coordinates and uploads them:
  • Every five minutes
  • When the active view changes
  • When monitoring stops
Both features associate their data with the view most recently identified by a userClicks selector.

Business-Level User Clicks

Unlike monitor.mouseEnabled, which reports every click, userClicks reports only clicks matching a configured selector. Use it to track meaningful business actions such as:
  • Submitting a form
  • Opening a customer record
  • Approving an order
  • Moving to the next workflow step
  • Selecting a product or account

User Search Monitoring

When the trigger control is clicked, GermainUX reads the current value from valueControl and reports it as the search term. This supports interfaces in which the search button and search-value field are separate controls.

User-Facing Error Detection

When a newly created window’s title matches a configured regular expression, GermainUX reports a user-facing error. This provides a lightweight way to detect error dialogs without identifying every control inside them.

Windows Session Replay

Session replay captures the Windows UI structure and its changes over time so that GermainUX can reconstruct the user’s experience. Leave self-healing disabled unless session-replay data has been observed to drift from the actual application UI.

Control Filter Fields

Filters identify Windows controls for:
You may specify any combination of fields. When multiple fields are present, every specified condition must match.

Context Variable Fields

Context variables can be defined under globalVariables or under a userClicks selector’s variables array.

Session-Replay Thumbnail Rules

Each entry in replay.thumbnailRules identifies controls for which GermainUX should capture a visual thumbnail. A rule contains: Example:

Thumbnail Criteria

All criteria specified in the same rule are combined with an AND condition.

Thumbnail Recapture Conditions

The recaptureOn array can contain:
  • label
  • visibility
  • bounds
  • value
  • selected
When any listed attribute changes, GermainUX captures a new thumbnail. Omit recaptureOn or use an empty array to capture the thumbnail only once.

Minimal Configuration Example

The following configuration identifies an application and enables basic process and window monitoring without CLR profiling, HTTP interception, or session replay:

Validate the Applied Configuration

After creating or changing a monitoring rule:
1

Refresh the configuration from the Agent tray menu or wait for the next polling interval

2

Restart the target application if required

3

Right-click the GermainUX Agent tray icon

4

Select Configurations

5

Select the applicable rule

6

Verify:

  • Target executable
  • Application and profile names
  • Local or server-provided origin
  • Windows UI worker status
  • CLR attachment status
  • Enabled monitoring features
  • Complete resolved JSON
If the expected rule does not appear or is not applied, see Agent Troubleshooting.

Additional Resources

Troubleshooting Tips

Read more

Management

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