--- language: "en" --- # 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](agent-settings.md)): | Component | Registry value | Default | |---------------|------------------|--------------------| | Agent | `AgentLogLevel` | `INFO` (always on) | | UI Worker | `WorkerLogLevel` | `OFF` | | .NET Profiler | `CLRLogLevel` | `OFF` | 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: | File name | Written by | |-------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `germain-agent.log` | `GermainAgent.exe` --- one file, always the same name. | | `germain-uia-worker-{ruleName-}{pid}.log` | `GermainUIAWorker.exe` --- one file per running worker, named after the target process's PID (and rule name, if the worker was started for a named rule) so multiple monitored applications don't interleave into the same file. | | `germain-clr-agent-{pid}.log` | `GermainCLRAgent.dll` --- one file per monitored .NET process, named after its PID. | 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](https://docs.germainux.com/main/troubleshooting.md#net-profiler-attach-fails-with-no-log-at-all) 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. * If you're launching it manually, right-click `GermainAgent.exe` → **Run as** **administrator**. * If this happens right after logon via the scheduled autostart task, the account that logged on is not a local administrator. The autostart task silently elevates for local admins only --- see [Installation → Autostart](installation.md#autostart). Either make that account a local admin, or ensure a local-admin account is the one that stays logged on on this machine. ## 🔍 No data appearing in GermainUX Work through these in order: | **Check** | **Details** | |---------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **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. | | **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. | | **Confirm the Agent is actually elevated and running** | --- check for the tray icon, and check `germain-agent.log` for a successful startup line. | | **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. | | **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). | | **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](installation.md#which-installer-to-use)) 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.