Monitoring¶

FastSMTP exposes Prometheus metrics at GET /metrics on the API port, in the standard text exposition format.

curl http://localhost:8000/metrics

The endpoint is served at the root, not under /api/v1, and is deliberately absent from the OpenAPI schema - Prometheus text output is not a JSON API.

Metrics¶

HTTP¶

SMTP intake¶

Webhook delivery¶

cancelled is a non-delivery, not a failure: a dashboard or alert built on status!="delivered" will count it. Deliveries cancelled at delete time, before any worker touched them, do not increment the counter at all - only those a worker had already claimed do. See Delivery statuses.

Email authentication¶

Metrics access¶

Only meaningful once an allowlist is configured. It has no source-address label: that would be unbounded cardinality, and the address appears in the log line instead.

Restricting access¶

Two settings control who may scrape. Both accept bare addresses and CIDR prefixes, in either address family.

export FASTSMTP_METRICS_ALLOWED_IPS='["10.0.0.0/8","192.0.2.5","2001:db8::/32"]'

A refused scrape gets 403 and no metric data. Malformed entries are rejected at startup rather than skipped - an allowlist that silently drops a typo is worse than none, because it looks enforced while standing open.

Refusals are logged at WARNING, but throttled: the first denial in each 60-second window is logged with its source address, and the rest are counted and reported when the window rolls over. /metrics needs no credential and is excluded from rate limiting, so logging every refusal would let any client drive unbounded log volume. fastsmtp_metrics_scrapes_denied_total is not throttled, so alert on that for the true rate.

Behind a reverse proxy¶

By default the check uses the socket peer, so behind an ingress every request appears to come from the proxy. Naming the proxy in FASTSMTP_METRICS_TRUSTED_PROXIES makes FastSMTP read the real client from X-Forwarded-For instead:

export FASTSMTP_METRICS_TRUSTED_PROXIES='["10.9.0.0/16"]'
export FASTSMTP_METRICS_ALLOWED_IPS='["10.20.0.0/16"]'

X-Forwarded-For is attacker-controlled, so it is consulted only when the peer is a listed proxy, and the chain is read from the right - discarding trusted hops and taking the first untrusted entry. The leftmost entry is whatever the original caller chose to send and is never used.

The two settings answer different questions. Trusting a proxy does not allow it to scrape; it only lets it assert who the client is. List anything there with care: a trusted proxy can claim any client address.

uvicorn fastsmtp.main:app --no-proxy-headers

Unix socket deployments¶

The allowlist needs a peer address. When the app is served over a Unix domain socket behind nginx, there is none, so every scrape is refused once FASTSMTP_METRICS_ALLOWED_IPS is set - metrics_trusted_proxies cannot help, because there is no peer to match against it.

Restrict scraping in nginx instead, and leave FASTSMTP_METRICS_ALLOWED_IPS empty for socket-served deployments.

Prometheus configuration¶

scrape_configs:
  - job_name: fastsmtp
    scrape_interval: 15s
    static_configs:
      - targets: ["fastsmtp:8000"]

Add metrics_path only if you front the service with a path prefix; the default /metrics is correct otherwise.

Queries worth having¶

# Message intake by outcome
sum by (result) (rate(fastsmtp_smtp_messages_total[5m]))

# Webhook failure ratio (excludes cancelled: those were never attempted)
sum(rate(fastsmtp_webhook_deliveries_total{status=~"failed|exhausted"}[5m]))
  / sum(rate(fastsmtp_webhook_deliveries_total{status!="cancelled"}[5m]))

# Queue backlog - rising means delivery is not keeping up with intake
fastsmtp_queue_depth{status="pending"}

# 95th percentile webhook latency
histogram_quantile(0.95, sum by (le) (
  rate(fastsmtp_webhook_delivery_duration_seconds_bucket[5m])
))

# Authentication failure rate
sum by (type) (rate(fastsmtp_auth_results_total{result="fail"}[5m]))

Alerts worth having¶

Health checks¶

Separate from metrics, for load balancers and orchestrators:

Both are unauthenticated and excluded from rate limiting. Use /ready as the readiness probe so a pod with a broken database connection is removed from service rather than handed traffic.