Agent Troubleshooting

GermainUX-Agent Troubleshooting

This guide helps administrators diagnose common installation, startup, configuration, connectivity, RUM Windows, Session Replay, and .NET Code Profiler issues.

For the fastest diagnosis, first confirm that GermainUX-Agent is running with administrator privileges, then verify the applied monitoring rule and GermainUX Enterprise connectivity. If the cause is not immediately visible, enable logging only for the affected component and review the corresponding log file.

Detailed logging for RUM Windows and Code Profiler is disabled by default and should be returned to OFF after troubleshooting to limit disk usage.

📄 Logs

Logging is configured independently for each component through the Windows Registry. GermainUX-Agent logging is enabled by default, while RUM Windows and Code Profiler logging must be enabled when troubleshooting.

Then retain the tables and other details below it. This complements the page introduction without unnecessarily repeating it.

Valid levels: OFF, ERROR, WARN, INFO, DEBUG, TRACE.

All logs are written under the shared LogPath registry value (default:
%LOCALAPPDATA%\\Germain Software\\Germain Agent\\Logs), as rotating files — 25 MB per
file, 10 files kept per log:

If you turn on WorkerLogLevel/CLRLogLevel to investigate an issue, turn them back off
afterward — they're deliberately opt-in so a normal deployment doesn't accumulate a
separate log file per monitored process indefinitely.

If no log file appears at all for a component, even at a non-OFF level, that
usually means the configured LogPath isn't writable by that process (see
CLR Profiler attach fails silently
below) — logging failures are designed to degrade silently rather than crash the
component, so a missing log is itself a symptom, not just an inconvenience.

🛡️ "GermainUX Agent must be run as Administrator"

The Agent checks its own elevation at startup and refuses to run if it isn't elevated —
it needs administrator rights to detect other processes starting/stopping on the machine.

🔍 No data appearing in GermainUX

Work through these in order:

1. Confirm the URL. Check HKLM\\SOFTWARE\\Germain Software\\Germain Agent\\URL (or the
   32-bit view under WOW6432Node if checking from a 32-bit tool on 64-bit Windows) is
   your correct GermainUX server URL.

2. Confirm the environment filter isn't excluding you. If Environment is set to a
   specific name (e.g. staging), rules tagged for a different environment (e.g. prod)
   won't apply on this machine. Leave it blank to accept all.

3. Confirm the Agent is actually elevated and running — check for the tray icon, and
   check germain-agent.log for a successful startup line.

4. Confirm a monitoring rule matches your target application — open the tray icon's
   Configurations submenu; if your application isn't listed at all, either no
   server-side rule targets its executable name, or (for a local rule) the
   Targets\\{exe}\\ registry subkey isn't set up correctly.

5. Check network/proxy reachability to the GermainUX URL from this machine —
   firewalls or an internal proxy blocking outbound HTTPS will show up as repeated
   warnings in germain-agent.log (config poll) or the relevant worker/profiler log
   (data upload).

6. Check queue.outputPath in the resolved rule JSON (via the Configurations
   submenu) isn't accidentally set — if it is, facts are being written to a local file
   instead of sent to GermainUX at all.

Installer blocks with a missing-redistributable message

Install the Microsoft Visual C++ 2015–2022 Redistributable matching the installer's
architecture (vc_redist.x64.exe for Setup64, vc_redist.x86.exe for Setup) from
aka.ms/vs/17/release/vc_redist.x64 / .x86, then re-run the installer. This is a pure
prerequisite check — the installer does not install the redistributable for you.

🐛 .NET Profiler attach fails with no log at all

Symptom: a monitored .NET application never produces a germain-clr-agent-{pid}.log
file, even with CLRLogLevel set to a real level, and (if AgentLogLevel is at DEBUG
or higher) germain-agent.log shows an attach failure such as "Catastrophic failure."

This almost always means something failed before the profiler's own logger could be
created — most commonly, the configured LogPath isn't writable by the target
application's process identity (which may be a different, less-privileged account than
the elevated Agent). Confirm the account the monitored application runs as has write
access to LogPath, or point LogPath at a location every monitored user account can
write to.

For a 32-bit .NET application, confirm the x86 GermainCLRAgent.dll (from the Setup x86
package — see Installation) is the one in use
for that target; the x64 build installed by Setup64 cannot attach to a 32-bit process.

💻 AgentConsole.exe

A standalone command-line tool installed alongside the Agent (AgentConsole.exe, in the
same folder as GermainAgent.exe), useful for confirming what the OS itself sees before
suspecting the Agent:

AgentConsole.exe --list

Lists every running process with a CLR loaded, and which CLR (classic .NET Framework vs.
modern .NET Core/5+) it's running. Useful to confirm a target application is actually a
.NET process, and which attach mechanism the Agent would use for it, before digging
further into an attach failure. Run AgentConsole.exe --help for the current option
list.