Agent Troubleshooting

📄 Logs

Logging is opt-in and off by default for the two per-target components — turning it on
is the first step for almost any investigation. Log levels are set independently per
component in the registry (see Agent Settings):

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.