Alerting

SpamFoo provides a health endpoint for monitoring. Use these to integrate with your existing monitoring infrastructure and catch problems early.

Health Endpoint

The /health endpoint returns SpamFoo's current status and queue state. Use this for load balancer health checks, container orchestration probes, or external monitoring tools. 

GET http://localhost:16253/health
{
    "status": "healthy",
    "shuttingDown": false,
    "activeRequests": 2,
    "modelReloading": false,
    "spoolQueue": {
        "active": 1,
        "waiting": 1,
        "maxConcurrency": 2,
        "totalProcessed": 48210,
        "totalTimedOut": 3
    },
    "backgroundQueue": {
        "active": 0,
        "waiting": 0,
        "maxConcurrency": 1,
        "totalProcessed": 1205,
        "totalTimedOut": 0
    }
}

The endpoint returns 200 OK when the service is running. During a graceful shutdown (for example, during a model reload), the status changes to shutting_down.

What to Monitor

These are the most important signals to track for a healthy SpamFoo deployment:

Metric Source Alert When
Service availability /health Endpoint unreachable or returns non-200
Queue depth /health (spoolQueue.waiting) Consistently above 0, indicating SpamFoo cannot keep up with incoming volume
Queue timeouts /health (spoolQueue.totalTimedOut) Count is increasing, meaning emails are being delivered without classification
Classification latency Admin console (Performance page) P95 latency trending well above your normal baseline
Spam rate Admin console (Overview page) Sudden spike or drop compared to baseline
Error log volume {data-dir}/logs/errors-*.txt New errors appearing or error rate increasing
Disk usage OS-level monitoring SpamFoo data directory approaching capacity

Integrating with External Monitoring

Uptime Checks

Point your monitoring tool (Uptime Kuma, Pingdom, Datadog, etc.) at the health endpoint. A simple HTTP check that expects a 200 response is sufficient for basic availability monitoring.

If SpamFoo is only listening on localhost, you have two options:

  • Run the monitoring agent on the same server and check http://localhost:16253/health directly
  • Expose the health endpoint through a reverse proxy (you can restrict access to just the /health path)

Prometheus / Grafana

SpamFoo does not expose a Prometheus metrics endpoint natively. To collect metrics for Prometheus:

  • Use a script or exporter that polls /health and the admin API endpoints (/admin/api/system/status, /admin/api/overview/kpis) and exposes them in Prometheus format
  • Alternatively, use the log files with a log-based metrics pipeline (Promtail + Loki)

Docker / Kubernetes

Use the health endpoint as a liveness and readiness probe: 

# Docker Compose
healthcheck:
    test: ["CMD", "curl", "-f", "http://localhost:16253/health"]
    interval: 30s
    timeout: 5s
    retries: 3
# Kubernetes
livenessProbe:
    httpGet:
        path: /health
        port: 16253
    initialDelaySeconds: 15
    periodSeconds: 30
readinessProbe:
    httpGet:
        path: /health
        port: 16253
    initialDelaySeconds: 5
    periodSeconds: 10

Live Metrics

The admin console shows real-time CPU and memory usage on the System > Status page. If you need to consume live metrics programmatically, the SSE endpoint is available at /admin/api/system/metrics/live and emits events with CPU percentage, memory usage, queue size, and Global API connectivity status.

Next Steps