Troubleshooting

⚙️ GermainUX Agent Troubleshooting

Use this guide to diagnose installation, startup, configuration, Windows UI monitoring, data-upload, and .NET Profiler issues affecting the GermainUX Agent.

🔍 Initial checks

For most problems, start by confirming:

📄 Component Logs

The GermainUX Agent, Windows UI worker, and .NET Code Profiler use independent log levels.

Supported levels are:

OFF
ERROR
WARN
INFO
DEBUG
TRACE

The Agent health and status log is enabled at INFO by default. Windows UI worker and CLR Profiler logging are disabled by default because each monitored process can generate a separate log.

Enable DEBUG or TRACE only while investigating a problem. Return the setting to its previous value after troubleshooting to avoid unnecessary disk usage.

For Registry configuration details, see GermainUX Agent Settings.

📁 Log Directory

All components write to the directory defined by the machine-wide LogPath Registry value.

Default:

%LOCALAPPDATA%\Germain Software\Germain Agent\Logs

Because %LOCALAPPDATA% is user-specific, the actual directory depends on the Windows account running each process.

Logs use rotation with:

📓 Log Files

Some Agent versions or internal diagnostic messages may refer to these components by their earlier or internal names:

🛠 Apply Logging Changes

Registry settings are read when a component starts.

After changing a log level:

No Log File Is Created

If a component is configured with a log level other than OFF, but no corresponding file appears, verify that its process identity can write to LogPath.

Logging failures are designed not to crash the component. Therefore, a missing log file can indicate that:

The elevated Agent may be able to write to the directory while the target application cannot. Check permissions using the identity of the monitored application, not only the Agent account.

🛡️ “GermainUX Agent Must Be Run as Administrator”

The Agent requires elevated privileges to detect processes starting and stopping on the computer. It checks its privileges during startup and exits if it is not elevated.

🖱️ When Starting the Agent Manually

Right-click GermainUXAgent.exe and select:

Run as administrator

🔑 When the Error Occurs After Login

The 64-bit installer creates a scheduled task that starts the Agent when a user logs in and requests the highest privileges available to that user.

If the logged-in user is a local administrator, the Agent starts elevated without displaying a UAC prompt.

If the user is not a local administrator, the scheduled task cannot provide the required elevation and the Agent exits.

Make sure the Windows account that remains logged in on the monitored computer is a local administrator.

For details, see GermainUX Agent Installation.

🚚 No Data Appears in GermainUX

Complete the following checks in order.

1️⃣ 1. Confirm That the Agent Is Running

Verify that:

If the Agent is not running, review its scheduled task and confirm that the logged-in account is a local administrator.

🌐 2. Confirm the GermainUX Server URL

Check the following Registry value:

HKEY_LOCAL_MACHINE\SOFTWARE\Germain Software\Germain Agent\URL

It must contain the correct base URL of the GermainUX server.

When using a 32-bit Registry tool on 64-bit Windows, the value may appear through the redirected view under:

HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Germain Software\Germain Agent

Confirm that:

Restart the Agent after changing the URL.

🔎 3. Check the Environment Filter

Review the Environment Registry value.

If it contains an environment name such as:

staging

the Agent accepts only monitoring rules assigned to that environment. A rule assigned to prod would not be applied.

Leave Environment empty to accept monitoring rules from every environment.

✅ 4. Confirm That Monitoring Is Enabled

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

If monitoring was paused, the Agent can continue running without collecting data.

🔄 5. Refresh the Configuration

Right-click the tray icon and select Refresh Config.

This forces the Agent to retrieve the latest rules instead of waiting for the next PollInterval.

Review germain-agent.log for errors if the refresh fails.

📋 6. Confirm That a Rule Matches the Application

Open the tray icon’s Configurations submenu.

Verify that the target application appears and that:

If the application is absent:

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

A local rule takes priority over a server-provided rule for the same executable.

🔁 7. Restart the Target Application

The Agent normally starts a new Windows UI worker and attaches the CLR Profiler when it detects a new target process.

After changing a rule:

1. Close the target application completely.

2. Confirm that its process has exited.

3. Start the application again.

4. Check whether a Windows UI worker starts.

5. Review the applicable worker or profiler log.

📡 8. Check Server and Network Connectivity

Confirm that the monitored computer can reach the configured GermainUX URL.

Check for:

Configuration-polling failures normally appear in germain-agent.log.

Data-upload failures appear in the relevant:

🗃️ 9. Check queue.outputPath

Inspect the resolved rule JSON from the Configurations submenu.

If queue.outputPath contains a file path, facts are written to that local file instead of being sent to GermainUX.

For normal server delivery, leave it empty:

"queue": {
  "outputPath": ""
}

🔒 10. Review Privacy and Exclusion Rules

If only certain values or facts are missing, inspect:

The data may be intentionally masked, anonymized, excluded, or unmatched rather than failing to upload.

🔎 A Monitoring Rule Does Not Appear

If the expected rule is missing from Configurations:

1. Select Refresh Config.

2. Review germain-agent.log for server-polling errors.

3. Verify the Agent’s Environment value.

4. Confirm that the server-side rule targets the exact executable filename.

5. For a local rule, confirm the Targets\{executableName.exe} Registry key.

6. Confirm that the JSON configuration file exists and is readable.

7. Validate the JSON syntax.

8. Restart the Agent.

For the rule schema, see Monitoring Configuration Reference.

🖱️ Windows UI Monitoring or Replay Does Not Start

If application-level information is present but Windows UI interactions or replay are missing:

1. Confirm that the rule enables the Windows UI worker.

2. For a local rule, verify:

   UiaWorkerEnabled = 1
   

3. Confirm that features.monitor.enabled is true.

4. Confirm that the required subfeature is enabled, such as:

   • userClicks

   • userSearches

   • clickMaps

   • mouseMaps

   • userFacingErrors

   • replay

5. Restart the target application.

6. Enable WorkerLogLevel at DEBUG.

7. Review the target’s germain-uia-worker-{ruleName-}{pid}.log.

8. Confirm that GermainUXRumWindows.exe remains in the same installation directory as GermainUXAgent.exe.

❓ Interactions Are Missing but Replay Works

If only specific clicks or searches are missing:

The application may expose different UI Automation information than expected.

🎞️ Replay Is Incomplete or Drifts from the UI

If replay does not accurately reflect the application:

1. Confirm that the required replay events are enabled.

2. Review thumbnail rules.

3. Review color-sampling configuration.

4. Temporarily enable the relevant debug options while working with Germain Software Support.

5. Consider selfHealEnabled only when actual replay drift has been confirmed.

Detailed UI diagnostics can create substantial log volume. Disable them after the investigation.

📦 Installer Reports a Missing Redistributable

The MSI installer requires Microsoft Visual C++ 2015–2022 Redistributable.

Install the package matching the installer architecture:

Then run the GermainUX installer again.

The MSI checks for this prerequisite but does not install it automatically.

🔧 .NET Profiler Does Not Attach

If .NET metrics, exceptions, garbage-collection facts, or CPU samples are missing, verify the following.

✅ Confirm CLR Attachment Is Enabled

For a local rule, verify:

ClrAttachEnabled = 1

In the resolved configuration, confirm that the required .NET features are enabled.

💻 Confirm the Target Is a .NET Process

Run:

AgentConsole.exe --list

This displays running processes that have loaded a CLR and identifies whether each process uses:

If the target does not appear, it may not be a .NET process or may not yet have loaded the CLR.

🔁 Confirm the Application Architecture

A profiler DLL must match the target process architecture:

The 64-bit profiler cannot attach to a 32-bit process.

Both GermainUX packages can be installed on the same computer when both architectures must be monitored.

📁 Confirm the Profiler DLL Location

The profiler DLL must remain in its installed directory with the related Agent components.

Do not move or rename it independently.

⛔ .NET Profiler Attachment Fails Without Creating a Log

Typical symptoms include:

This usually indicates that the failure occurred before the CLR Profiler could initialize its logger.

The most common cause is that the target application’s Windows identity cannot write to LogPath.

The Agent may run as an elevated administrator while the target application runs as another, less-privileged account.

To resolve the issue:

1. Identify the account running the target application.

2. Verify that it has write access to LogPath.

3. If necessary, configure LogPath to use a directory writable by every monitored account.

4. Restart the Agent.

5. Restart the target application.

6. Check whether a new profiler log appears.

Also confirm that the installed profiler architecture matches the application.

🧰 Use AgentConsole.exe

AgentConsole.exe is a standalone diagnostic utility installed with the GermainUX Agent and Code Profiler packages.

It helps verify what Windows and the CLR expose before investigating Agent-specific behavior.

📋 List Processes With a Loaded CLR

Run from an elevated Command Prompt:

AgentConsole.exe --list

The command lists:

Use this command to confirm:

ℹ️ Display Available Commands

AgentConsole.exe --help

The options can vary between Agent versions. Use --help to obtain the command list available in the installed build.

📥 Information to Collect for Germain Software Support

If the issue remains unresolved, collect:

Remove or protect confidential information before sharing diagnostic files.

📚 Related Documentation

ℹ️ Get Help

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