Setup & Configuration

⚙️ GermainUX-Agent Setup and Configuration

📖 Overview

This guide explains how to install, configure, validate, and troubleshoot GermainUX-Agent on a Windows workstation or server.

It is intended for administrators responsible for deploying GermainUX real-user monitoring, Session Replay, and code-level observability for native Windows applications.

No changes to the monitored application’s source code are required. GermainUX-Agent detects configured applications and automatically activates the required monitoring components.

🗂️ Architecture

The standard GermainUX-Agent installation contains three coordinated components:

The components are installed together and must remain in the same installation directory.

⚙️ How It Works

1. GermainUX-Agent starts automatically when an authorized Windows administrator signs in.

2. It connects to the configured GermainUX Enterprise environment.

3. It retrieves the monitoring rules assigned to the machine and environment.

4. It watches for the executable defined in each rule.

5. When a monitored application starts, the Agent activates:

   • RUM Windows for user-interface monitoring and Session Replay

   • Code Profiler for supported .NET runtime monitoring

   • Both components when user experience and code-level observability are required

6. The collected telemetry is transmitted to GermainUX Enterprise for analysis, dashboards, alerting, reporting, correlation, and Session Replay.

📋 Before You Begin

Confirm that the target machine meets these requirements:

The Agent must run with elevated privileges to detect application processes. It also runs within the interactive Windows session to capture authorized user-interface activity.

📦 Select the Appropriate Installer

Two packages are available:

Install Setup64 unless you specifically need to profile a 32-bit .NET application or GermainUX Support has instructed you otherwise.

Both packages can be installed on the same machine when monitoring both 64-bit and 32-bit applications.

💻 Install GermainUX-Agent

1. Download the appropriate installer.

2. Run Setup64.msi with administrator privileges.

3. Enter the base URL of your GermainUX Enterprise environment.

4. Accept the default installation folder or select another location.

5. Complete the installation.

6. Sign out and sign back in using an authorized local administrator account.

A Windows restart is not normally required.

The Agent does not start immediately after installation. A Windows Scheduled Task launches it with elevated privileges the next time an authorized administrator signs in.

See Agent Installation for detailed installation, upgrade, repair, and uninstallation instructions.

🔗 Configure the GermainUX Connection

The installer stores the GermainUX Enterprise URL in the following machine-wide Windows Registry location:

HKLM\SOFTWARE\Germain Software\Germain Agent

The URL may point to either:

Additional registry settings control the environment, log levels, polling frequency, mouse and keyboard hooks, worker behavior, and local monitoring rules.

Registry changes take effect only after the affected process is restarted.

See Agent Settings for the complete configuration reference.

🔧 Configure Application Monitoring

🌐 Centrally Managed Configuration

For production deployments, configure the monitored applications and their rules centrally in GermainUX Enterprise.

The Agent periodically retrieves:

Central configuration makes it possible to manage monitoring consistently across multiple users, machines, applications, and environments.

🏠 Local Configuration

Monitoring rules can also be defined locally when central configuration is unavailable or inappropriate.

Typical uses include:

A local rule is defined under:

HKLM\SOFTWARE\Germain Software\Germain Agent\Targets\{executableName.exe}

The rule references a local JSON configuration file containing the monitoring settings.

A local rule takes precedence over a centrally provided rule for the same executable.

See:

• Agent Settings – Local Monitoring Rules

• Monitoring Configuration Reference

🏁 Validate the Deployment

After signing in and starting the monitored application:

1. Confirm that the GermainUX-Agent icon appears in the Windows system tray.

2. Right-click the icon and verify that Monitoring Enabled is selected.

3. Select Refresh Config to retrieve the latest configuration immediately.

4. Open Configurations and confirm that the expected application rule is listed.

5. Review the resolved configuration to verify:

6. Start or restart the monitored application.

7. Confirm that telemetry appears in GermainUX Workspace.

8. If enabled, validate that Session Replay is being generated.

9. Confirm that sensitive data is excluded, masked, or anonymized as expected.

📌 System-Tray Controls

Right-click the GermainUX-Agent tray icon to access the following controls:

The Configurations view is the fastest way to confirm which settings are actually being applied to a monitored application.

Troubleshooting

If the Agent does not start, retrieve its configuration, detect an application, or send telemetry:

1. Confirm that the signed-in user is a local administrator.

2. Verify that the GermainUX-Agent tray icon is present.

3. Confirm that the GermainUX Enterprise URL is correct.

4. Validate network and proxy access to the GermainUX environment.

5. Select Refresh Config from the tray menu.

6. Confirm that the expected monitoring rule is listed.

7. Verify that the rule uses the correct executable name.

8. Restart the monitored application after configuration changes.

9. Review the Agent, RUM Windows, and Code Profiler logs.

10. Temporarily increase the appropriate log level when additional diagnostic detail is required.

See Agent Troubleshooting for log locations and solutions to common deployment problems.

🔗 Related Documentation