Log Management

SpamFoo writes structured logs to separate files by category. You can view and search logs through the admin console or read the log files directly from disk.

Log Files

Logs are stored in {data-dir}/logs/ as daily rolling text files. Each file rolls daily or when it reaches 50 MB, and the 30 most recent files are kept. On a typical server this works out to about 30 days of history.

File	Contents
classification-YYYYMMDD.txt	Email classification events (results, confidence, latency)
updates-YYYYMMDD.txt	Model downloads, version checks, client updates
personalization-YYYYMMDD.txt	User feedback processing, rule creation, KNN memory updates
system-YYYYMMDD.txt	Startup, shutdown, configuration changes, general events
errors-YYYYMMDD.txt	Warnings, errors, and fatal issues across all categories

Log Format

Each line follows the format:

2026-03-30 14:25:47.123 +00:00 [INF] Email classified as ham with 0.08 confidence

Multi-line entries (such as stack traces) continue on subsequent lines below the initial log line.

Log Levels

Level	Tag	Meaning
Debug	[DBG]	Detailed diagnostic information (only in development mode or when debug logging is enabled)
Information	[INF]	Normal operational events
Warning	[WRN]	Degraded operation or unexpected conditions that do not prevent function
Error	[ERR]	Failures that affect individual requests or operations
Fatal	[FTL]	Unrecoverable errors that cause the service to stop

Viewing Logs in the Console

The admin console at /admin includes a built-in log viewer under System > Logs. The viewer supports:

• Date and time range filtering
• Log level filtering (show only warnings and above, for example)
• Category filtering (classification, updates, personalization, system, errors)
• Full-text search within log messages

For most troubleshooting, the console log viewer is the fastest way to find what you need. Use the raw files when you need to process logs with external tools or ship them to a centralized logging system.

Debug Logs

SpamFoo supports additional debug log categories that can be enabled through the admin console under System > Logs. These produce extra log files with detailed diagnostic output for specific subsystems. Debug logs are disabled by default and have no performance impact when off.

Enable debug logging only when troubleshooting a specific issue, and disable it afterward to avoid unnecessary disk usage.

Retention

Data Type	Default Retention	Configurable
Log files (all categories)	30 days	No (fixed)
Classification records	7 days	Yes (admin console)
Minute aggregates	24 hours	Yes
Hour aggregates	7 days	Yes
Day aggregates	90 days	Yes

Adjust retention settings in the admin console under Settings > Data Retention, or see Configuration for details.

Shipping Logs to External Systems

SpamFoo writes plain text log files that can be collected by any log shipper (Filebeat, Fluentd, Promtail, etc.). Point your shipper at {data-dir}/logs/*.txt and configure it to parse the timestamp and level from each line.