Skip to content

Monitoring

Everything you need to observe, measure, and respond to what's happening inside your Mailyte email server. From real-time dashboards to automated incident response, this section covers the full monitoring stack.

Mailyte ships with a monitoring stack built on Prometheus, Grafana, and a custom monitoring service (worker/monitoring). You get metrics, dashboards, alerts, and auto-healing out of the box — no third-party setup required.

Architecture at a Glance

graph LR
    subgraph Services
        PF[Postfix]
        DV[Dovecot]
        RS[Rspamd :11334]
        API[API gateway :8080]
        DB[(MySQL)]
        RD[(Redis)]
        WK[~20 worker services]
    end

    subgraph Monitoring Stack
        MON[Monitoring service :8085]
        PR[Prometheus :9090]
        GR[Grafana :3000]
        AM[Alertmanager :9093]
    end

    RS --> PR
    API --> PR
    WK --> PR
    DB -->|mysql-exporter :9104| PR
    RD -->|redis-exporter :9121| PR

    MON -->|SMTP/IMAP/HTTP probes| PF
    MON --> DV
    MON --> RS
    MON --> API

    PR --> GR
    PR --> AM
    AM -->|webhook| WH[Webhook receivers]

The Three Pillars

Pillar Tool What It Gives You
Metrics Prometheus Time-series data from every worker's /metrics endpoint plus the MySQL and Redis exporters
Visualization Grafana Two provisioned dashboards (mail overview, security)
Alerting Alertmanager + webhooks Alert rules for queue depth, bounce rate, resource limits, and backup freshness

Not every scrape target is deployed

monitoring/prometheus/prometheus.yml defines scrape jobs for a postfix-exporter (:9154) and a dovecot-exporter (:9166), but no such containers exist in any compose file — those two jobs show as DOWN in Prometheus, and every dashboard panel or alert built on postfix_* / dovecot_* / node_* series has no data until those exporters are added. What is live: every FastAPI worker's own /metrics, rspamd:11334, mysql-exporter, and redis-exporter. Postfix and Dovecot health is covered by the monitoring service's direct SMTP/IMAP probes instead.

In This Section

  • Overview

    The three pillars of observability and how they fit together in Mailyte.

    Overview

  • Prometheus

    Metrics collection, scrape configuration, and retention settings.

    Prometheus

  • Grafana

    The provisioned dashboards, custom panels, and visualization setup.

    Grafana

  • Alerting

    Alert rules, severity levels, and notification routing.

    Alerting

  • Health Checks

    The monitoring service on :8085 — what it checks and how to use it.

    Health Checks

  • Enterprise Metrics

    Business-level metrics — delivery stats, storage usage, and SLA numbers.

    Enterprise Metrics

Deep Dives

Page What It Covers
Service Monitoring Per-service health and status checks for Postfix, Dovecot, Rspamd, and workers
System Monitoring CPU, RAM, and disk stats collected by the monitoring service
Auto-Healing Automatic restart of failed critical services via a scoped Docker socket proxy
Webhook Notifications Push health events to any HTTP endpoint
Performance Response times, throughput, queue depths, and delivery latency
SLA Monitoring Uptime tracking and delivery SLA numbers
Troubleshooting Fixing issues with the monitoring stack itself

Quick Start

Already have Mailyte running? Verify the monitoring stack is healthy:

Bash
curl http://localhost:8085/health

Returns the monitoring service's own liveness. curl http://localhost:8085/heartbeat probes every mail service and returns the full status map.

Bash
curl http://localhost:9090/-/healthy

Open http://localhost:9090 for the Prometheus UI.

Bash
curl http://localhost:3000/api/health

Open http://localhost:3000 and log in with GRAFANA_ADMIN_USER / GRAFANA_ADMIN_PASSWORD from your .env file.

If any of these fail

Head to Troubleshooting for step-by-step diagnosis of common monitoring issues.

Key ports to remember

Service Port URL
Monitoring service 8085 http://localhost:8085/heartbeat
Prometheus 9090 http://localhost:9090
Grafana 3000 http://localhost:3000
Alertmanager 9093 http://localhost:9093

In production these are all republished on 127.0.0.1 only (docker-compose.prod.yml, since 2026-08-22) — reach them over SSH port-forwarding, not from the public internet.