Ember - Real-time monitoring for Caddy

Monitor your Caddy server in real time: per-host traffic, latency percentiles, status codes, and more. When FrankenPHP is detected, unlock per-thread introspection, worker management, and memory tracking. It is officially recommended by FrankenPHP.

Why Ember?

Caddy exposes rich metrics through its admin API and Prometheus endpoint, but reading raw Prometheus text or setting up a full Grafana stack just to glance at traffic is heavy. Ember gives you a zero-config, read-only terminal dashboard that connects to Caddy's admin API and works out of the box. No extra infrastructure, no YAML to write: just ember and you're monitoring.

Features

Caddy Monitoring

• Per-host traffic table with RPS, average latency, status codes, and sparklines
• Latency percentiles (P50, P90, P95, P99) and Time-to-First-Byte per host
• Sorting, filtering, and full-screen ASCII graphs (CPU, RPS, RSS)
• Config Inspector tab: browse the live Caddy JSON config as a collapsible tree
• Certificates tab: TLS certificate monitoring with expiry tracking, color-coded warnings, and likely auto-renewal indication
• Upstreams tab: reverse proxy upstream health monitoring with per-upstream status, auto-detected when reverse_proxy is configured
• Logs tab: live access and runtime log streaming in a single view, with a sidepanel tree (Runtime, Access, per-host children) and a free-text filter. Zero-config: Ember hot-registers two transient sinks in Caddy via the admin API (__ember__ for access logs, __ember_runtime__ for everything else) and receives logs over TCP with no Caddyfile changes
• Automatic Caddy restart detection

FrankenPHP Introspection

• Per-thread state, method, URI, duration, and memory tracking (method, URI, duration, memory, and request count require FrankenPHP 1.12.2+)
• Worker management with queue depth and crash monitoring
• Graphs for queue depth and busy threads
• Automatic detection and recovery when FrankenPHP starts or stops

Integration & Operations

• Prometheus metrics export (/metrics) with optional basic auth and health endpoint (/healthz)
• Self-observability: ember_* metrics (build info, per-stage scrape totals, errors, durations, last success) so you can monitor the monitor
• Daemon mode for headless operation, with error throttling and TLS certificate reload via SIGHUP
• JSON output mode for scripting, with --once for single snapshots
• Quick health check: ember status (text or --json) for a one-line Caddy summary
• Readiness gate: ember wait blocks until Caddy is up (-q for silent scripting)
• Deployment validation: ember diff before.json after.json compares snapshots
• Zero-config setup: ember init checks Caddy, enables metrics, and warns about missing host matchers
• Unix socket support for Caddy admin APIs configured with admin unix//path
• TLS and mTLS support for secured Caddy admin APIs
• Environment variable configuration (EMBER_ADDR, EMBER_EXPOSE, EMBER_LOG_LISTEN, ...) for container deployments
• NO_COLOR env var support (no-color.org)
• Lightweight: ~15 MB RSS, ~0.3 ms per poll cycle with 100 threads and 10 hosts (benchmarks)
• Cross-platform binaries (Linux, macOS, Windows), Homebrew tap, and Docker image

Install

curl -fsSL https://raw.githubusercontent.com/alexandre-daubois/ember/main/install.sh | sh

Or with Homebrew:

brew install alexandre-daubois/tap/ember

macOS: if Gatekeeper blocks the binary on first run, remove the quarantine attribute: xattr -d com.apple.quarantine $(which ember), or allow it manually in System Settings → Privacy & Security.

Or with Go:

go install github.com/alexandre-daubois/ember/cmd/ember@latest

Or with Docker (runs in daemon mode by default, see Docker docs):

docker run --rm --network host alexandredaubois/ember

The image is also mirrored on GHCR as ghcr.io/alexandre-daubois/ember.

You can also download the latest binaries from the release page. If you use this method, don't forget to check for updates regularly!

Quick Start

Make sure Caddy is running with the admin API enabled (it is by default). Then:

ember init

This checks your Caddy setup and enables metrics via the admin API if needed (no restart required). Once ready:

ember

Ember connects to the Caddy admin API and auto-detects FrankenPHP if present.

For a quick one-line health check:

ember status

How It Works

Ember polls the Caddy admin API and Prometheus metrics endpoint at a regular interval (default: 1s), computes deltas and derived metrics (RPS, percentiles, error rates), and renders them through one of several output modes: an interactive Bubble Tea TUI (default), streaming JSONL, a headless daemon with Prometheus export, or a one-shot status command.

Plugins (experimental)

Ember supports a plugin system that lets third-party developers add custom tabs for visualizing metrics from additional Caddy modules (e.g., rate limiters, WAF modules, custom middleware). Plugins are compiled into the binary using Go's blank import pattern, the same approach used by Caddy itself.

Building a custom Ember binary with plugins is simple:

import (
    "github.com/alexandre-daubois/ember"
    _ "github.com/myorg/ember-myplugin"
)

func main() { ember.Run() }

Plugins can provide multiple tabs, subscribe to core metrics, conditionally hide their tabs, and reuse Ember's Prometheus parser via the pkg/metrics package.

See the Plugin Development Guide for details on building and integrating plugins.

The plugin API is still evolving: feedback is very welcome. If something does not fit your use case or you wish an interface exposed more (or less), please open an issue and tell us what you are trying to build.

Documentation

Full documentation is available in the docs/ directory:

• Getting Started: Install and first run
• Caddy Configuration: Caddyfile requirements
• Caddy Dashboard: Per-host traffic and latency
• FrankenPHP Dashboard: Thread introspection and workers
• Logs: Live tailing of access and runtime logs, with a sidepanel to drill into a specific host
• CLI Reference: Flags, keybindings, shell completions
• JSON Output: Streaming JSONL for scripting
• Prometheus Export: Metrics, health checks, daemon mode
• Docker: Container usage
• Agent Skills: Skills for AI coding agents
• Plugins: Building custom plugins for Ember (experimental)
• Troubleshooting: Common issues and solutions

Contributing

See CONTRIBUTING.md for development setup, architecture overview, and guidelines.

License

MIT