Settings & Persistence¶

Settings File¶

All GUI settings are persisted to a JSON file at:

%LOCALAPPDATA%\aaLogForwarder\settings.json

For example: C:\Users\<username>\AppData\Local\aaLogForwarder\settings.json

When Settings Are Saved¶

Automatically when you click Start
Automatically when the window closes (including CLI overrides)

When Settings Are Loaded¶

On startup, if no command-line arguments are provided
CLI arguments override the saved values for that session

File Format¶

{
  "Host": "syslog.corp.local",
  "Port": 6514,
  "ForwardLogs": true,
  "AutoScroll": true,
  "UseTls": true,
  "ValidateCertificate": true,
  "PollingIntervalMs": 1000,
  "SyslogFormat": "RFC5424",
  "Protocol": "TCP",
  "Facility": 16,
  "FlattenMessages": false,
  "MessageTruncateLength": 0,
  "SendAllLogs": false
}

Property Reference¶

Property	Type	Default	Description
`Host`	string	`"localhost"`	Syslog server hostname or IP
`Port`	int	`514`	Syslog server port (1--65535)
`ForwardLogs`	bool	`true`	Send records over the network
`AutoScroll`	bool	`true`	Auto-scroll the log output
`UseTls`	bool	`false`	Enable TLS encryption
`ValidateCertificate`	bool	`true`	Validate TLS server certificate
`PollingIntervalMs`	int	`1000`	Poll interval in ms (500--60000)
`SyslogFormat`	string	`"RFC5424"`	`RFC5424`, `RFC3164`, or `KVP`
`Protocol`	string	`"TCP"`	`TCP` or `UDP`
`Facility`	int	`16`	Syslog facility code (0--23)
`FlattenMessages`	bool	`false`	Replace newlines with `\\|`
`MessageTruncateLength`	int	`0`	Max message chars (0 = unlimited)
`SendAllLogs`	bool	`false`	Send all existing logs on first poll

Error Handling¶

If the settings file is missing, corrupted, or unreadable, the forwarder silently falls back to defaults. A warning is written to the log4net log file.

You can reset all settings by deleting the JSON file and restarting the application.

log4net Logging Configuration¶

The forwarder uses log4net for its own diagnostic logging (separate from the syslog messages it forwards). The configuration file is:

log.config

This file is located alongside the executable.

Default Configuration¶

Two appenders are defined:

FileAppender (active)¶

Writes INFO through FATAL messages to aaLogForwarder.log.

Setting	Value
File	`aaLogForwarder.log`
Rolling style	Size-based
Max file size	10 MB
Backup files	5
Log levels	INFO -- FATAL
Locking	MinimalLock

Log line format:

2024-01-15 10:30:01,234 [1] [INFO] [aaLogForwarder.MainForm] - Starting polling loop

Pattern: %date [%thread] [%level] [%logger] - %message%newline

DebugFileAppender (inactive by default)¶

Writes DEBUG through FATAL messages to aaLogForwarder-debug.log with additional detail.

Setting	Value
File	`aaLogForwarder-debug.log`
Rolling style	Size-based
Max file size	10 MB
Backup files	3
Log levels	DEBUG -- FATAL
Locking	MinimalLock

Log line format:

2024-01-15 10:30:01,234 [5732] [1] [DEBUG] [aaLogReader.aaLogReader] [GetUnreadRecords] - maximumMessages - 1000

Pattern: %date [%timestamp] [%thread] [%level] [%logger] [%M] - %message%newline

Enabling Debug Logging¶

To enable the debug appender, edit log.config and uncomment the debug appender reference:

<root>
  <level value="DEBUG"/>
  <appender-ref ref="DebugFileAppender"/>
  <appender-ref ref="FileAppender"/>
</root>

Also change the root level from INFO to DEBUG.

Note

Debug logging is verbose. The aaLogReader library logs every cache file read, file open, header parse, and record read. Enable it only when troubleshooting, and disable it afterward to avoid filling the disk.

Log File Location¶

Log files are written to the working directory of the executable, typically the build output folder. If running as a scheduled task or service wrapper, ensure the working directory is writable.

Cache File¶

The aaLogReader library uses a cache file to track the last-read log record, enabling incremental reads across restarts.

Location¶

The cache file is stored in the same directory as the .aaLog files:

C:\ProgramData\ArchestrA\LogFiles\aaLogGUITester-aaLogReaderCache

The filename is constructed from the process name and a base suffix. The default pattern is:

<ProcessName><CacheFileBaseName>

For the forwarder: aaLogGUITester + -aaLogReaderCache = aaLogGUITester-aaLogReaderCache

File Content¶

The cache file contains a single JSON-serialized LogRecord representing the last record successfully read:

{
  "MessageNumber": 60381,
  "EventFileTime": 133500000000000000,
  "HostFQDN": "MYHOST.corp.local",
  ...
}

The key field is MessageNumber, which tells the reader where to resume on the next call to GetUnreadRecords().

Cache Behavior¶

Scenario	Behavior
Cache file exists	Resume from the recorded message number
Cache file missing	Start reading from the beginning of the current log file
Cache file corrupted	Fall back to reading from the beginning
Send Existing Logs checked	Ignore cache on first poll, then resume normally

Resetting the Cache¶

To re-read all logs from scratch:

Stop the forwarder
Delete the cache file from the log directory
Start the forwarder

Or simply check Send Existing Logs before clicking Start -- the first poll will ignore the cache file automatically.