Observability

Observability

Everything under Observe in the sidebar, plus the Caddy-side logging and metrics CaddyUI can switch on for you.

• The ingest listener
• Visitor analytics
• Retention and storage
• Live Traffic
• Server Logs
• Certificate lifecycle
• File access logs
• Prometheus metrics
• CrowdSec
• Health checks
• Activity log

The ingest listener

CaddyUI listens on CADDYUI_INGEST_LISTEN (default :9019) for Caddy's structured JSON logs over TCP. It installs additive named log streams in each managed Caddy that send three things: access logs (visitor analytics and Live Traffic), TLS events (certificate lifecycle) and, on demand, runtime logs (Server Logs). Caddy's normal container, journal and file outputs are unchanged.

Every managed node must be able to reach that host and port. On the repository Docker network that is caddyui:9019; a node on another host cannot resolve that name and gets its own Log ingest target on its Caddy Fleet entry (v2.37.0). The Caddy Fleet list shows where each node ships its logs and warns about targets it cannot resolve; the Analytics page says the same for a node in scope that has no traffic. Do not publish the ingest port to the internet. Set the variable empty to disable all three streams.

Caddy's log writer uses soft-start failover with a dial timeout, so Caddy boots and serves even while CaddyUI is offline.

Visitor analytics

Opt in under Settings → Analytics. The Analytics page shows requests, visitors and bandwidth today, top hosts, a 24-hour sparkline, status-code mix and unique visitors, filtered by server for fleets. Every event is stamped with the Caddy node that handled it, so load-balanced nodes sharing a hostname remain distinguishable. Per-host drill-downs (/analytics/{host}) and CSV export are available, and the proxy-host list shows request counters. Dashboard cards reflect only the selected server, including traffic to wildcard SAN hostnames. Exclude your own addresses with Exclude IPs.

Retention and storage

Raw events are kept for Keep raw events for N days (default 30, 0 forever). A background prune runs an hour after start-up and hourly after that, deleting in small batches with pauses so the UI stays responsive even on a large backlog; progress is logged every million rows. Per-day totals per host are kept in a separate rollup, so long-range charts survive a short retention.

The Storage panel shows the database file size, free space inside the file, oldest and newest event, the last prune and the last reclaim. Prune now runs the prune immediately. Reclaim space runs SQLite's VACUUM in the background, the only thing that actually shrinks the file after rows are deleted; it is refused when the data volume lacks room for a full copy of the database. On MariaDB the panel points at OPTIMIZE TABLE. Both actions appear in the Activity log.

If you upgraded from a version before v2.43.0 with analytics on, expect the first prune to remove a large backlog: the prune loop had never actually been started before that release.

Live Traffic

Observe → Live Traffic streams access-log rows as they arrive, every two seconds, with server, host, method, path, status, size, duration and client IP, dated in your configured timezone. Clear hides everything seen so far for this browser and server filter and the stream resumes after it; nothing in the database is touched.

Server Logs

Observe → Server Logs streams a managed node's structured runtime logs (not access logs) at a chosen level with text filters, for administrators. Enabling it adds a temporary log stream to that node; full capture is memory-only, leaves Caddy's own outputs unchanged and disables itself after 15 minutes. Use it to watch ACME orders, upstream dial errors or config reloads without shelling into the node.

Certificate lifecycle

Structured TLS events from each node are projected into per-node states (obtaining, renewing, retry scheduled, issued, revoked, issuance error) with Caddy's latest message. They appear on the Certificates page, on managed certificate forms and in live server probes instead of an unconditional green badge. Only the compact latest state is persisted.

File access logs

Settings → Integrations → Caddy file access logs writes native JSON or console access logs to a file inside selected Caddy containers (the repository compose persists /var/log/caddy), scoped to the generated HTTP, HTTPS or both servers, with rotation by size, retained files and days. Enabling file logs never removes the analytics stream and vice versa.

Prometheus metrics

Settings → Integrations → Prometheus metrics selects the servers CaddyUI should manage and enables Caddy's base HTTP metrics, optional per-host labels, and optional observation of catch-all hosts (Caddy 2.11+, validated on the target, can create unbounded cardinality on public listeners). The card shows each server's scrape target, http://<admin-url>/metrics. Point Prometheus at it over the same private network CaddyUI uses; do not expose the admin endpoint to make /metrics reachable. Metrics on unselected servers, Caddyfile global options and OTLP fields set elsewhere are left untouched. See Caddy's metrics guide for metric names.

CrowdSec

Settings → Integrations → CrowdSec configures the crowdsec Caddy app and injects the HTTP bouncer before every protected proxy, redirect, advanced and plain-HTTP route on the selected servers. Options: LAPI URL and bouncer key (masked once saved), streaming mode, decision refresh interval, hard-fail when the LAPI is unavailable (off by default), exact-host and path-pattern exclusions, module validation before saving and Test connection. Set Trusted proxies and Client IP headers under Settings → Security so decisions apply to the real client behind Cloudflare or a load balancer. Requires a Caddy built with github.com/hslatman/caddy-crowdsec-bouncer/http, which Dockerfile.caddy includes.

Health checks

Per proxy host: upstream health via Caddy's admin API (Docker-internal names work), app health (does the upstream respond), public status checks (Automatic / Custom / Off) and expectations after every sync. Details and the health-history page are on Proxy Hosts. Upstream health changes can notify by email, webhook or ntfy.

Activity log

Observe → Activity records every create, edit, delete, sync, rollback, export, AI tool call and login-relevant event with actor, timestamp, server and resource, with CSV export. Retention is Settings → General → Activity log retention.