Source: https://help.spamfoo.com/guides/monitoring
Last updated: 2026-10-27

***

# 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 text
```

Lines 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

1. Type the codes support gave you in **Debug Log Codes**, separated by commas or spaces.
2. Click **Save Changes**.
3. Reproduce the problem.
4. Go to **System > Logs**, choose the code as the category, and click **Download**. Each code writes its own file in the `logs` folder, named after the code, such as `12-20261005.txt`.
5. 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](https://help.spamfoo.com/api/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](https://help.spamfoo.com/guides/configure#performance) and [System Requirements](https://help.spamfoo.com/guides/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: 3
```

## Watch 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](https://help.spamfoo.com/guides/roles#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`.