Log Files
Things do not always work the way they should. When that happens, uberAgent does not keep you in the dark. Its log files show you exactly what is going on.
Agent Log
Explanation
This is the log file of uberAgent’s main component, the system service/daemon.
Location
Windows
The agent log file uberAgent.log is stored by default in the SYSTEM account’s Temp directory, which typically resolves to C:\Windows\Temp.
Note:Starting with uberAgent version 7.3 it is possible to change the path via the Windows Registry or Group Policy.
macOS
The default location for the uberAgent.log file is /Library/Logs/uberAgent.
Note:Starting with uberAgent version 6.2 this directory will be owned by root with permissions 700. As a consequence Console.app won’t be able to access the log files if it runs as a normal user. If you need to use Console.app to view uberAgent logs in this directory you can either change the permissions or start the app as root from terminal with this command: sudo /System/Applications/Utilities/Console.app/Contents/MacOS/Console.
Agent Configuration Log
Explanation
This is the log file of the system service/daemon`s configuration.
Location
Windows
The configuration log file uberAgentConfiguration.log is stored by default in the SYSTEM account’s Temp directory, which typically resolves to C:\Windows\Temp.
macOS
The default location for the uberAgentConfiguration.log file is /Library/Logs/uberAgent.
In-Session Helper Log
Explanation
This is the log file of uberAgent’s in-session helper component which is used for collecting information from within user sessions.
Location
Windows
The in-session helper log file uAInSessionHelper.log is stored by default in the SYSTEM account’s Temp directory, which typically resolves to C:\Windows\Temp.
macOS
The default location for the uAInSessionHelper.log file is ~/Library/Logs/uberAgent.
Chrome/Edge/Firefox Browser Extension In-Session Helper Log
Explanation
This is the log file of uberAgent’s in-session helper instances that are acting as communication gateways between the agent and the Chrome and Firefox browser extensions.
Location
Windows
The Chrome/Firefox extension in-session helper log file uAInSessionHelper.log is stored by default in the user account’s Temp directory, which typically resolves to C:\Users\USERNAME\AppData\Local\Temp.
macOS
The default location for the uAInSessionHelper.log file is ~/Library/Logs/uberAgent.
IE Browser Add-on Log
Explanation
This is the log file of uberAgent’s Internet Explorer add-on.
Location
The IE add-on’s log file uberAgentIEExtension.log is stored by default in the user account’s low-integrity Temp directory, which typically resolves to C:\Users\USERNAME\AppData\Local\Temp\Low.
If Enhanced Protection Mode is enabled and OS is Windows 8 (or newer), the IE add-on’s log file is stored in C:\Users\USERNAME\AppData\Local\Packages\windows_ie_ac_001\AC\Temp. For Windows 7 the log files’ location is the same as described in the previous paragraph.
Sandbox Log
Explanation
This is the log file of uberAgent’s XPC Service that wraps potentially unsafe API calls.
Location
macOS
The default location for the uberAgentSandbox.log file is /Library/Logs/uberAgent.
uAGuardian Log
Explanation
This is the log file for uberAgent’s helper process, which is started when the agent service is restarted due to a configuration change to apply the new configuration.
Location
Windows
The helper’s process log file uAGuardian.log is stored by default in the SYSTEM account’s Temp directory, which typically resolves to C:\Windows\Temp.
More Information
Configuring a custom path for log file storage
Windows
On Windows systems, you can configure a custom directory for storing uberAgent log files either through Group Policy (GPO) or by modifying the Windows Registry. To achieve this, you need to set a value for the LogPath key within the registry path HKEY_LOCAL_MACHINE\SOFTWARE\vast limits\uberAgent\LogConfig. The LogPath key should be of type REG_SZ and contain the desired directory path.
Example:
HKEY_LOCAL_MACHINE\SOFTWARE\vast limits\uberAgent\LogConfig
LogPath = C:\Logs\uberAgent\%COMPUTERNAME%
<!--NeedCopy-->
If a custom path is specified, all log files will be stored in the designated location.
Priority Order
The priority for determining the log file storage location is as follows:
- Group Policy (GPO): If configured, this takes the highest priority.
- Registry Software Path: The path specified in HKEY_LOCAL_MACHINE\SOFTWARE\vast limits\uberAgent\LogConfig.
-
Default Path: If no GPO or registry path is configured or accessible, the
Tempdirectory of the SYSTEM account is used.
Handling Not Accessible Paths
If e.g. a network path is configured for log file storage and it becomes not accessible, uberAgent will process the configured paths in order of priority. The logging will then rotate to the next accessible path.
When rotation occurs, a message will be written at the beginning of the log file indicating that the original log file was not accessible and that rotation has taken place. Note that this message may have a later timestamp than subsequent log entries, as the log queue might not have been fully processed at the time of the rotation.
This ensures that logging continues seamlessly even if the initially configured path is not accessible, maintaining the integrity of the log data.
macOS
On macOS, you can designate a custom directory for log file storage by modifying the uberAgent-meta-config.conf file.
To achieve this, assign a value to the LogFilePath key located within the [Meta:Logging] section.
Example:
[Meta:Logging]
LogFilePath = /tmp/uberAgentLogFiles
<!--NeedCopy-->
If a custom path is specified, all aforementioned log files will be stored in the designated location. The files uberAgent.log, uberAgentConfiguration.log,
uberAgentSandbox.log and uberAgentScriptHelper.log will have the hostname appended to their names. Additionally, the remaining log files will include both the hostname and a session ID in their filenames.
Example:
uberAgent_WORKSTATION1.log
uberAgentConfiguration_WORKSTATION1.log
uberAgentSandbox_WORKSTATION1.log
uberAgentScriptHelper_WORKSTATION1.log
uberAgentBrowserHelper_WORKSTATION1_123456.log
uberAgentSessionHelper_WORKSTATION1_123456.log
<!--NeedCopy-->
Enabling Debug Mode
Unless debug mode is enabled uberAgent logs only important events like errors. To enable debug mode make sure the following settings are present in the configuration:
[Miscellaneous]
debugMode = true
<!--NeedCopy-->
Activating Trace Logging
Trace logging is a very detailed log level that can be enabled to facilitate troubleshooting of specific agent components. We recommend only enabling trace logging temporarily.
To enable trace logging for an agent component, add the component’s name to the TraceLogFilterExpression regex of the ConfigFlags setting, e.g.:
ConfigFlags = TraceLogFilterExpression:REGEX
<!--NeedCopy-->
The following table lists examples for REGEX:
| TraceLogFilterExpression regex | Description |
|---|---|
| .Dns. | Logs additional information for DNS queries. |
| .POQ create new file. | Logs additional information if a new persistent output queue file was created. |
| .Event POQ/queue send. | Logs additional information if data was sent to the backend. |
| .Event POQ increase error count. | Logs additional information if illformed data was sent to the backend and the error count was increased. |
| .Event POQ remove. | Logs additional information if events were removed from the persistent output queue. |
| .Event POQ store. | Logs additional information if events were stored in the persistent output queue. |
| .Event queue store. | Logs additional information if events were stored in an in-memory queue. |
| .Event POQ read. | Logs additional information if events were read from the persistent output queue. |
| .Performance counter. | Logs additional information for mapping performance counter names (english to localized and vice versa) and determination times. |
| .Locking. | Logs additional information if internal locking mechanism for lists took too long. |
| .StartProcess. | Logs the stdout/stderr content of started scripts. |
| .SendEventMulti. | Logs additional information if a single send operation was split into multiple. |
| .Citrix. | Logs additional information for Citrix DC/ADC queries. |
| .Time-change. | Logs additional information if system time change was detected. |
| .SessionTrace. | Logs additional information if a user profile event cannot be mapped to an active session. |
| .Find. | Logs additional information if a process cannot be found in uberAgent’s internal process list. |
File Size and Log Rotation
When the size of the log file grows to 10 MB uberAgent archives it. This is done by appending the current timestamp to the filename and starting a new empty log file. uberAgent keeps the four newest archive files. When four archive files are present and a fifth file is archived the oldest archive file is deleted. This log rotation mechanism guarantees that the total log file size never exceeds 50 MB.
The number of log files to keep around can be changed via the configuration parameter LogFileCount.
Log Format
Log file entries always have the same structure, explained in the following table:
| Timestamp | Severity | Domain | Thread Owner | Thread ID | Source | Message |
|---|---|---|---|---|---|---|
| Timestamp in the machine’s time zone | Possible entries: DEBUG, INFO, WARN, ERROR | The computer’s Active Directory domain | Windows: the name of the computer account macOS: the user root | The ID of the thread that logged the message | Message source. For example LicenseCheck or ReceiverStatistics | Actual message to be logged |
Here is an example:
2018-10-04 11:19:51.076 +0100,INFO ,VASTLIMITS,PC1$,4432,ReceiverStatistics,Splunk; localhost:19500 - Events in queue: 11961, queue size: 3073.1 KB, sent: 0, added to queue: 361, rejected from queue: 0
Timestamp = 2018-10-04 11:19:51.076 +0100
Severity = INFO
Domain = VASTLIMITS
Machine = PC1
Thread ID = 4432
Source = ReceiverStatistics
Message = Splunk; localhost:19500 - Events in queue: 11961, queue size: 3073.1 KB, sent: 0, added to queue: 361, rejected from queue: 0
<!--NeedCopy-->
Notepad++ Syntax Highlighter
Even though we take great care to optimize the log for readability it is sometimes hard to find the needle in the haystack. That is why we created an uberAgent log syntax highlighter for Notepad++. It highlights the key information, making it easier to find what you are searching for.
Splunk It
As text-based log files, uberAgent’s logs are ideal candidates for processing by Splunk. We have built the uberAgent Log Collector specifically for that purpose.