Diagnostic Tools

SpamFoo provides several tools for investigating classification issues and verifying that the service is running correctly.

Health Check

The quickest way to verify SpamFoo is running: 

curl http://localhost:16253/health

A healthy response looks like: 

{
    "status": "healthy",
    "activeRequests": 0,
    "spoolQueue": { "active": 0, "waiting": 0, "maxConcurrency": 2 },
    "backgroundQueue": { "active": 0, "waiting": 0, "maxConcurrency": 1 }
}

If this times out or returns an error, SpamFoo is not running. Check the error logs and the common startup issues.

Diagnostic Classification

To understand why SpamFoo classified an email a certain way, use the diagnostic endpoint. Send the raw .eml content to /classify/diagnostic-stream. This returns the full decision trace including per-model scores, signal extraction results, and timing. 

curl -X POST http://localhost:16253/classify/diagnostic-stream \
    -H "Content-Type: message/rfc822" \
    --data-binary @/path/to/message.eml

The response includes:

  • Email metadata (message ID, from address, subject)
  • Final classification result and confidence
  • Individual model scores (text model, metadata model, blender)
  • Tab classification probabilities
  • Whether any personalization rules or overrides were applied
  • Processing time for each stage

Use this when investigating why a specific email was misclassified. The per-model breakdown shows which model contributed most to the decision.

Admin Console

The admin console at http://localhost:16253/admin provides visual tools for diagnosis:

  • Messages page: Search for specific emails by sender, domain, IP, or mailbox. Each result shows the full scoring breakdown and pipeline journey.
  • Log viewer: Search logs by date, level, and text. Filter to the errors category to find recent failures.
  • System status: Live CPU and memory usage, model versions, and queue state.
  • Anomalies page: Automatically detected unusual patterns that may indicate problems.

Log Analysis

When diagnosing a problem, start with the error log: 

# Recent errors (Linux)
tail -100 {data-dir}/logs/errors-$(date +%Y%m%d).txt

# Search for a specific domain or IP
grep "example.com" {data-dir}/logs/classification-$(date +%Y%m%d).txt

See Log Management for the full list of log files and their contents.

Enable Debug Logging

For deeper investigation, enable debug logging through the admin console under System > Logs. Debug codes activate detailed logging for specific subsystems. This produces additional log files with verbose output that can help identify the root cause of subtle issues.

Disable debug logging when you are done, as it increases disk usage.

Database Inspection

SpamFoo stores classification records and configuration in a SQLite database at {data-dir}/admin.db. You can inspect it directly if needed: 

sqlite3 {data-dir}/admin.db ".tables"
sqlite3 {data-dir}/admin.db "SELECT * FROM app_settings;"
Caution: Do not modify the database while SpamFoo is running. SQLite does not handle concurrent writes from multiple processes well. Use the admin console or API to change settings.

Testing a Single Message

To test a specific message, send it to the running service with curl. Use the diagnostic endpoint to see the full decision trace, or the regular endpoint to see only the result: 

curl -X POST http://localhost:16253/classify/diagnostic-stream \
    -H "Content-Type: message/rfc822" \
    --data-binary @/path/to/message.eml

This does not affect the running service or its stored data. See Command Line for more ways to classify messages from a script or the command line.