Monitoring Configuration Reference | Germain Documentation

🔎 Monitoring Configuration Reference

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

🖼️ Collected telemetry

Feature
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:

The Agent periodically retrieves the list of target applications and rule names from the GermainUX server.
It retrieves each rule’s JSON configuration by name.
If the server request fails, the Agent attempts to load:
```
{Agent installation folder}\config\{ruleName}.json
```

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": "My Application",
  "version": "2026.1",
  "agentName": "MyApplication-Prod",
  "profileName": "Default",
  "correlationId": ""
}

Field	Description
`application`	Application name attached to every fact generated by the rule.
`version`	Informational version assigned to the rule or Agent configuration.
`agentName`	Unique name identifying the monitoring-rule instance. The Agent also uses this name when retrieving the configuration from the GermainUX server.
`profileName`	Name of the associated monitoring profile. Used as informational and provenance metadata.
`correlationId`	Normally left empty. The Agent generates a correlation ID for each monitored process so that facts from the Agent, Windows UI worker, and CLR Profiler can be correlated.

🪟 Application Window Identification

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

"monitorConfig": {
  "winTitle": "My Application",
  "useImageSibling": false
}

Field	Description
`winTitle`	Partial title used to identify the application’s main window.
`useImageSibling`	When a click occurs on an image control, the Agent also examines a sibling control for a meaningful label. This is useful for icon-only buttons whose text is stored in a neighboring element.

📦 Data Queue and Delivery

The queue block controls how collected facts are buffered and sent to GermainUX.

"queue": {
  "pushInterval": 30,
  "bufferSize": 1000,
  "batchSize": 100,
  "outputPath": "",
  "prettyOutput": false,
  "httpTimeoutMs": 5000
}

Field	Default	Description
`pushInterval`	`30`	Number of seconds between data uploads.
`bufferSize`	`1000`	Maximum number of facts retained in memory. Older facts are discarded if the buffer reaches this limit.
`batchSize`	`100`	Maximum number of facts included in each HTTP request.
`outputPath`	Empty	When specified, writes facts to the local file instead of sending them through HTTP. Use only for offline capture or testing.
`prettyOutput`	`false`	Formats JSON written to `outputPath` with indentation.
`httpTimeoutMs`	`5000`	Timeout, in milliseconds, for each HTTP upload request.

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.

"proxy": {
  "url": "http://localhost:",
  "delayInit": false,
  "excludedPorts": [443, 4225, 4226],
  "minPort": 10000
}

Field	Description
`url`	Base URL used for the local interception proxy.
`delayInit`	Delays proxy initialization when set to `true`.
`excludedPorts`	Ports that the proxy must not intercept. Exclude GermainUX communication ports to prevent the Agent from monitoring its own uploads.
`minPort`	Lowest local port the proxy can use.

🔧 Diagnostic Options

The debug block enables detailed Windows UI worker diagnostics.

"debug": {
  "walkSiblings": false,
  "walkTree": false,
  "dumpTree": false,
  "dumpSnapshot": false,
  "printCreateWinInfo": false
}

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

"logging": {
  "level": "INFO",
  "name": "myapplication",
  "path": "C:/germainagent/"
}

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:

Registry Value	Description
`LogPath`	`LogPath`
`AgentLogLevel`	`AgentLogLevel`
`WorkerLogLevel`	`WorkerLogLevel`
`CLRLogLevel`	`CLRLogLevel`

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:

"globalVariables": [
  {
    "name": "username",
    "filter": {
      "type": "text",
      "name": "UsernameControlAutomationId"
    },
    "lowerCase": true
  }
]

Typical global variables include:

Variable	Description
Logged-in username	Logged-in username
User role	User role
Customer or account identifier	Customer or account identifier
Active business unit	Active business unit
Application region	Application region
Selected workspace	Selected workspace

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.

"maskAll": false,
"exclusions": [
  {
    "name": "Anonymize username",
    "fieldName": "user.name",
    "type": 1,
    "factType": "",
    "pattern": "",
    "preserveLength": true,
    "preserveWhitespace": false
  }
]

🛡️ Privacy Fields

Field	Description
`maskAll`	When `true`, text values are masked by default. Use this for applications in which sensitive information can appear throughout the interface.
`exclusions[].name`	Descriptive name used to identify the privacy rule.
`exclusions[].fieldName`	Dot-separated path of the fact field to sanitize, such as `user.name`.
`exclusions[].factType`	Optional fact type to which the rule applies. Leave empty to apply the rule to the field across all fact types.
`exclusions[].type`	Sanitization method: mask, anonymize, or exclude.
`exclusions[].pattern`	Optional regular expression. When specified, only the matching portion is sanitized. Otherwise, the entire value is sanitized.
`exclusions[].preserveLength`	For masking, replaces every character with `*`, preserving the original value’s length. Default: `true`.
`exclusions[].preserveWhitespace`	For masking, leaves whitespace visible so the masked value retains its word structure. Default: `false`.

🔁 Sanitization Types

Value	Method	Result
`0`	Mask	Replaces the value, or matching portion, with `*` characters.
`1`	Anonymize	Replaces the value with an irreversible hash. Identical input values produce identical hashes, preserving equality-based analysis.
`2`	Exclude	Removes the value entirely.

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.

"features": {
}

💻 Process Metrics

"processMetrics": {
  "enabled": true,
  "interval": 60,
  "clrFallbackEnabled": false,
  "threadDetailEnabled": true,
  "threadPoolEnabled": false,
  "resourceCountersEnabled": false
}

Process monitoring can collect:

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

Field	Description
`enabled`	Enables process-metric collection.
`interval`	Collection interval in seconds.
`clrFallbackEnabled`	Allows the CLR Profiler to collect process metrics for a headless .NET process that has no Windows UI worker. Keep it disabled for normal WPF and WinForms applications.
`threadDetailEnabled`	Collects per-thread CPU and state information through WMI instead of reporting only the total thread count.
`threadPoolEnabled`	Reports a best-effort count of `.NET ThreadPool`-named threads. This is primarily meaningful for .NET 6 and later. Older runtimes may report `0`.
`resourceCountersEnabled`	Collects process handles, GDI objects, USER objects, and disk-read/write byte deltas.

♻️ .NET Garbage-Collection Metrics

"gcMetrics": {
  "enabled": false,
  "interval": 60
}

When enabled, GermainUX reports:

Item
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

"freezeDetection": {
  "enabled": false,
  "pollIntervalMs": 2000,
  "hangTimeoutMs": 2000
}

Freeze detection periodically sends a message to each monitored window to determine whether it remains responsive.

Field	Description
`enabled`	Enables freeze detection.
`pollIntervalMs`	Interval, in milliseconds, between responsiveness checks.
`hangTimeoutMs`	Maximum time to wait for a window response before considering it unresponsive.

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

"profiler": {
  "enabled": false,
  "interval": 1000,
  "inclusions": [],
  "exclusions": []
}

The CPU profiler periodically captures .NET call stacks.

Field	Description
`enabled`	Enables CPU stack sampling.
`interval`	Time, in milliseconds, between stack samples.
`inclusions`	Executable or module-name filters identifying code to include.
`exclusions`	Executable or module-name filters identifying code to exclude.

When both filter arrays are empty, the profiler includes all eligible code.

This feature requires the CLR Profiler to be attached.

🔗 Outbound HTTP Monitoring

"http": {
  "enabled": false,
  "sslEnabled": true,
  "sslPorts": [443],
  "excludedPorts": [4225, 4226],
  "collectRequestBody": true,
  "requestBodyExclusions": "",
  "collectResponseBody": true,
  "responseBodyExclusions": ".*(css|js|png|jpg|jpeg|gif|svg|mpg)",
  "collectHeaders": false
}

Outbound HTTP monitoring captures calls made by the target process and separates their timing into connection, wait, and download phases.

Field	Description
`enabled`	Enables outbound HTTP monitoring.
`sslEnabled`	Enables TLS interception for HTTPS traffic.
`sslPorts`	TLS ports to intercept, typically `443`.
`excludedPorts`	Ports that must never be monitored. Include GermainUX communication ports to avoid capturing Agent uploads.
`collectRequestBody`	Captures HTTP request bodies.
`requestBodyExclusions`	Regular expression identifying requests whose bodies must not be captured, such as binary uploads or sensitive endpoints.
`collectResponseBody`	Captures HTTP response bodies.
`responseBodyExclusions`	Regular expression identifying responses to exclude. The example excludes common static assets.
`collectHeaders`	Captures request and response headers, including parsed `Server-Timing` information.

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

"exception": {
  "enabled": false
}

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

"monitor": {
  "enabled": true,
  "windowEventsEnabled": true,
  "mouseEnabled": false,
  "changeEnabled": false,
  "keyboardEnabled": false
}

The monitor feature is the foundation for Windows UI telemetry.

The following features require monitor.enabled to be true:

Dependent feature	Feature name
clickMaps	`clickMaps`
mouseMaps	`mouseMaps`
userClicks	`userClicks`
userSearches	`userSearches`
userFacingErrors	`userFacingErrors`

Field	Description
`enabled`	Master switch for Windows UI monitoring facts.
`windowEventsEnabled`	Reports application startup and windows being created or destroyed.
`mouseEnabled`	Reports every mouse click on a control. Use `userClicks` instead when only specific business actions are required.
`changeEnabled`	Reports changes to input controls, including text edits, checkboxes, and radio buttons.
`keyboardEnabled`	Reports command-style keystrokes such as Enter, Escape, function keys, and Ctrl, Alt, or Windows key combinations. It does not capture ordinary text typed into fields.

🗺️ Click and Mouse-Movement Heatmaps

"clickMaps": {
  "enabled": false
},
"mouseMaps": {
  "enabled": false
}

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

"userClicks": {
  "enabled": false,
  "typeValue": "Native:User Click",
  "selectors": {
    "Button Click": {
      "prefix": "Click on",
      "filter": {
        "type": "button"
      },
      "variables": [
        {
          "name": "argument1",
          "contextScan": false,
          "filter": {
            "name": "hierarchy"
          },
          "childIndex": 0
        }
      ],
      "requireDoubleClick": false
    }
  }
}

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

Field	Description
`typeValue`	Fact type applied to every matching click, such as `Native:User Click`.
`selectors.{name}.filter`	Control-selection criteria.
`selectors.{name}.prefix`	Prefix used to construct the click description.
`selectors.{name}.labelExpression`	Optional regular expression applied to the control’s visible label.
`selectors.{name}.nameExpression`	Optional regular expression applied to the control’s name.
`selectors.{name}.requireDoubleClick`	When `true`, the selector matches only double-clicks.
`selectors.{name}.variables`	Additional contextual values captured from the UI and attached to the click fact.

🔍 User Search Monitoring

"userSearches": {
  "enabled": false,
  "selectors": {
    "Search Button": {
      "trigger": {
        "type": "button",
        "name": "SearchButton"
      },
      "valueControl": {
        "name": "SearchBox"
      }
    }
  }
}

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

"userFacingErrors": {
  "enabled": false,
  "rules": [
    {
      "label": "Error Dialog",
      "pattern": "[Ee]rror|[Ff]ailed|[Ee]xception"
    }
  ]
}

When a newly created window’s title matches a configured regular expression, GermainUX reports a user-facing error.

Field	Description
`enabled`	Enables error-window detection.
`rules[].label`	Name assigned to the generated fact.
`rules[].pattern`	Regular expression matched against newly created window titles.

This provides a lightweight way to detect error dialogs without identifying every control inside them.

🎦 Windows Session Replay

"replay": {
  "enabled": false,
  "pointerEnabled": true,
  "controlMutationEnabled": true,
  "structuralChangesEnabled": true,
  "windowLifecycleEnabled": true,
  "focusMonitoringEnabled": true,
  "scrollMonitoringEnabled": true,
  "scrollbarMonitoringEnabled": true,
  "fragmentMaxEvents": 1000,
  "fragmentMaxAge": 15,
  "snapshotInterval": 30,
  "iconWin32Enabled": false,
  "thumbnailRules": [],
  "colorSamplingEnabled": false,
  "colorSamplingTypes": [
    "pane",
    "window",
    "group",
    "button"
  ],
  "selfHealEnabled": false,
  "selfHealBurstThreshold": 3
}

Session replay captures the Windows UI structure and its changes over time so that GermainUX can reconstruct the user’s experience.

Field	Description
`enabled`	Master switch for session-replay collection.
`pointerEnabled`	Records mouse movement and clicks.
`controlMutationEnabled`	Records changes to control properties, including labels, bounds, and visibility.
`structuralChangesEnabled`	Records controls being added to or removed from the UI tree.
`windowLifecycleEnabled`	Records windows being created and destroyed.
`focusMonitoringEnabled`	Records focus changes between controls.
`scrollMonitoringEnabled`	Records scrolling and changes to scroll position or size.
`scrollbarMonitoringEnabled`	Records scrollbar thumb and track changes.
`fragmentMaxEvents`	Flushes the active replay fragment after it reaches this number of events.
`fragmentMaxAge`	Flushes the active replay fragment after this number of seconds.
`snapshotInterval`	Maximum interval, in seconds, between complete state snapshots. Set to `0` to disable periodic snapshots. An initial snapshot is still collected.
`iconWin32Enabled`	Captures monitored-window icons through `WM_GETICON` or the executable resource for display in replay.
`thumbnailRules`	Ordered rules identifying controls for which a visual thumbnail should be captured.
`colorSamplingEnabled`	Captures control background and border colors to improve replay fidelity without taking full screenshots.
`colorSamplingTypes`	UI Automation control types for which colors are sampled. An empty array includes every type.
`selfHealEnabled`	Periodically rescans the live UI tree to correct drift between the application and the worker’s in-memory representation.
`selfHealBurstThreshold`	Triggers a rescan after this number of consecutive forced or deadline-based fragment flushes.

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:

Purpose	Feature
userClicks	`userClicks`
userSearches	`userSearches`
globalVariables	`globalVariables`
Click-specific context variables	Click-specific context variables

"filter": {
  "type": "button",
  "name": "SubmitButton",
  "label": "Submit",
  "classname": "Button"
}

Field	Matches
`type`	UI Automation control type, expressed in lowercase. Examples include `button`, `edit`, `combo box`, `data grid`, `check box`, `list item`, `tab item`, `tree item`, `hyperlink`, `image`, and `menu item`.
`name`	UI Automation `AutomationId`.
`label`	Visible control label or name.
`classname`	Win32 window class name.

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.

Field	Description
`name`	Name under which the captured value is attached to the fact.
`filter`	Control from which the value should be read.
`childIndex`	When zero or greater, reads the value from the specified child of the matched control.
`siblingIndex`	When nonzero, reads the value from a sibling at the specified relative position.
`expression`	Optional regular expression applied to the raw value. Only the matching portion is retained.
`contextScan`	When `true`, actively searches the UI tree for the control. When `false`, checks only the control associated with the triggering event. Default: `true`.
`defaultOnFailure`	Uses a default value if `expression` does not match instead of omitting the variable.
`lowerCase`	Converts the captured value to lowercase.

🖼️ Session-Replay Thumbnail Rules

Each entry in replay.thumbnailRules identifies controls for which GermainUX should capture a visual thumbnail.

A rule contains:

Field	Purpose
`method`	`win32` or `screen`
`criteria`	Conditions that must match the control
`recaptureOn`	Changes that should cause GermainUX to update the thumbnail

Example:

"thumbnailRules": [
  {
    "method": "screen",
    "criteria": {
      "type": ["image"],
      "hasRect": true
    },
    "recaptureOn": [
      "visibility",
      "bounds",
      "value"
    ]
  }
]

📋 Thumbnail Criteria

Field	Description
`type`	UI Automation control types that may match.
`not_type`	UI Automation control types that must not match.
`aid`	Permitted Automation IDs.
`not_aid`	Excluded Automation IDs.
`classname`	Exact permitted Win32 class names.
`not_classname`	Exact excluded Win32 class names.
`classnameSplit`	Matches when any listed token occurs in the whitespace-separated class name.
`all_classnameSplit`	Matches only when every listed token occurs in the class name.
`not_classnameSplit`	Excludes controls containing any listed class-name token.
`label`	Permitted visible labels. Use an empty string to match an empty label.
`not_label`	Excluded visible labels. Use an empty string to exclude empty labels.
`hasChildren`	Requires the control to have or not have child controls.
`hasRect`	Requires the control to have or not have a nonzero bounding rectangle. A nonzero rectangle generally indicates that it is visible on screen.

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:

{
  "application": "My Application",
  "version": "2026.1",
  "agentName": "MyApplication-Prod",
  "profileName": "Default",
  "correlationId": "",
  "monitorConfig": {
    "winTitle": "My Application",
    "useImageSibling": false
  },
  "queue": {
    "pushInterval": 30,
    "bufferSize": 1000,
    "batchSize": 100,
    "outputPath": "",
    "prettyOutput": false,
    "httpTimeoutMs": 5000
  },
  "maskAll": false,
  "exclusions": [],
  "features": {
    "processMetrics": {
      "enabled": true,
      "interval": 60,
      "clrFallbackEnabled": false,
      "threadDetailEnabled": false,
      "threadPoolEnabled": false,
      "resourceCountersEnabled": false
    },
    "monitor": {
      "enabled": true,
      "windowEventsEnabled": true,
      "mouseEnabled": false,
      "changeEnabled": false,
      "keyboardEnabled": false
    },
    "replay": {
      "enabled": false
    }
  }
}

✅ Validate the Applied Configuration

After creating or changing a monitoring rule:

Refresh the configuration from the Agent tray menu or wait for the next polling interval.
Restart the target application if required.
Right-click the GermainUX Agent tray icon.
Select Configurations.
Select the applicable rule.
Verify:

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

ℹ️ Get Help

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

Component: Engine, JS Profiler, Mobile App, RPA Bot Recorder, RUM Windows, Agent

Feature Availability: 2026.2