Monitor Logs and Health
This page shows how to read SpamFoo Client's logs, check its health, and connect it to the monitoring tools you already use.
Read Logs in the Admin Console
As a System Admin, go to System > Logs. The viewer opens on today's date.
- Search box: finds log lines that contain your text within the chosen dates.
- Date range: picks the first and last day to show.
- Category: shows one log category, or All Categories. Debug log codes you have turned on also appear here as numbers.
- Refresh loads the logs again. Load more loads the next set of lines, and Jump to bottom moves to the newest lines.
- Download saves the lines you have loaded as a text file.
For most problems, the viewer is the fastest way to find what you need. Use the files on disk when you want to send logs to another system.
In standalone mode, SpamFoo Client also writes every log line to its console output. With the Linux package, read it with journalctl -u spamfoo-client. In Docker, read it with docker logs. This lets you collect logs with the tools you already use for other services.
Find the Log Files
Log files are in the logs folder inside the SpamFoo data directory. The exact path is listed under Storage on System > Status.
| File | Category | What It Holds |
|---|---|---|
classification-YYYYMMDD.txt |
Classification | Results for each message SpamFoo checks |
updates-YYYYMMDD.txt |
Updates | Model downloads, version checks, and client updates |
personalization-YYYYMMDD.txt |
Personalization | Corrections and the rules learned from them |
system-YYYYMMDD.txt |
System | Startup, shutdown, settings changes, and everything else |
errors-YYYYMMDD.txt |
Errors | Every warning, error, and fatal error from all categories |
- A new file starts each day, or sooner when a file reaches 50 MB. A file started early gets a number at the end, such as
classification-20260330_001.txt. - Log files are deleted after the Retention Period in the Scan History card on System > Settings. The default is 7 days.
Read a Log Line
Each line starts with the date, time, and time zone, then the level in brackets:
2026-03-30 14:25:47.123 +00:00 [INF] Message textLines about one message may also show that message's log ID in brackets after the level. Longer entries, such as error details, continue on the lines below.
| Tag | Level | Meaning |
|---|---|---|
[DBG] |
Debug | Extra detail for troubleshooting |
[INF] |
Information | Normal activity |
[WRN] |
Warning | Something unexpected that didn't stop SpamFoo from working |
[ERR] |
Error | A failure that affected one message or task |
[FTL] |
Fatal | A failure that stopped the service |
Change How Much Is Logged
Use the Logging card on System > Settings, then click Save Changes.
- Log Level sets the lowest level that is written. Choose Detailed (includes Debug), Normal (the default), Warning, Error, or Fatal. The change takes effect right away. If you choose Detailed to look into a problem, set it back to Normal when you are done, because detailed logging fills the disk faster.
- Debug Log Codes are for advanced troubleshooting. Each code turns on extra logs for one part of SpamFoo. Use these only when SpamFoo support asks.
Turn On Debug Codes
- Type the codes support gave you in Debug Log Codes, separated by commas or spaces.
- Click Save Changes.
- Reproduce the problem.
- Go to System > Logs, choose the code as the category, and click Download. Each code writes its own file in the
logsfolder, named after the code, such as12-20261005.txt. - Clear Debug Log Codes and click Save Changes.
Check Health
SpamFoo Client has three health endpoints, and none of them need a sign-in. The table below says what to watch on each. See Check Health in the API Reference for every response.
Know What to Watch
| Signal | Where to Find It | Look Into It When |
|---|---|---|
| Service is running | /health/live |
It doesn't answer, or answers with anything other than 200. |
| Ready to classify | /health/ready |
It answers 503 for more than a few minutes. The reasons field says why. |
| Messages waiting | spoolQueue.waiting in /health, or Scan Queue on System Status |
It stays above zero, which means SpamFoo can't keep up with incoming mail. |
| Timeouts | spoolQueue.totalTimedOut in /health |
The number keeps going up. Those messages got no result. |
| Rejected requests | classifyIntake.totalRejected in /health |
The number goes up. |
| Scan time | Average Scan Time on Mail Health | It climbs well above what is normal for your server. |
| Caught rate | Caught Rate and Mail Trend on Mail Health | It jumps or drops suddenly. |
| Connection and license | Alerts on Mail Health, and System Status | An alert says the API is disconnected or the license has a problem. |
| Errors | errors-*.txt log files, or the Errors category in the log viewer |
New errors appear, or they appear more often. |
| Disk space | Your operating system's tools, and Storage on System Status | The drive that holds the SpamFoo data directory is getting full. |
If messages are waiting or timing out, see Tune Performance and System Requirements.
Connect External Monitoring
Set Up Uptime Checks
Point your monitoring tool, such as Uptime Kuma, Pingdom, or Datadog, at /health/ready. A check that expects a 200 response tells you SpamFoo Client is running and able to classify mail. To check only that the service is running, use /health/live.
A load balancer can use /health/ready to stop sending mail to SpamFoo Client. In standalone mode, when SpamFoo Client is asked to stop, /health/ready answers 503 with shutting_down for a few seconds before it closes.
SpamFoo Client listens only on the server itself unless you changed it. Either run the monitoring agent on the same server and check http://localhost:16253/health/ready, or let a reverse proxy pass on just the /health paths.
Use Docker Health Checks
The SpamFoo Client Docker image already includes a health check that calls /health/live, so docker ps shows whether the container is healthy. To use your own timing, or to wait until SpamFoo Client is ready, add a healthcheck to the service in Docker Compose:
healthcheck:
test: ["CMD", "curl", "-fsS", "http://localhost:16253/health/ready"]
interval: 30s
timeout: 5s
retries: 3Watch Live Metrics
The Memory, CPU, and Scan Queue tiles on System > Status update every few seconds. A green dot next to the tile name means the live feed is connected.
To read the same feed from a script, connect to /admin/api/system/metrics/live. It needs the proxy secret in the X-SpamFoo-Proxy-Auth header. See Sign In Without SmarterMail for where to find the secret. If you changed the port in standalone mode, use that port in place of 16253 in the examples on this page.
curl -N http://localhost:16253/admin/api/system/metrics/live \
-H "X-SpamFoo-Proxy-Auth: YOUR_ACCESS_SECRET"Every 5 seconds it sends a metrics event with these fields: cpuPercent, memoryMb, gcMemoryMb, queueSize, globalApiConnected, and timestamp.