You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
- Prometheus metrics export (`/metrics`) and health endpoint (`/healthz`)
17
+
- Daemon mode for headless operation
18
+
- JSON output mode for scripting
42
19
- Auto-detection of FrankenPHP and Caddy processes
43
-
- Stale data and connection loss detection
44
20
- Cross-platform binaries, Homebrew tap, and Docker image
45
21
46
22
## Install
@@ -55,13 +31,13 @@ Or with Go:
55
31
go install github.com/alexandre-daubois/ember/cmd/ember@latest
56
32
```
57
33
58
-
Or with Docker (runs in daemon mode with Prometheus export on `:9191` by default):
34
+
Or with Docker:
59
35
60
36
```bash
61
37
docker run --rm --network host ghcr.io/alexandre-daubois/ember
62
38
```
63
39
64
-
## Usage
40
+
## Quick Start
65
41
66
42
Make sure Caddy is running with the admin API and metrics enabled:
67
43
@@ -78,52 +54,20 @@ Then:
78
54
ember
79
55
```
80
56
81
-
Ember connects to the Caddy admin API and auto-detects FrankenPHP if present. In Caddy-only mode, the dashboard shows per-host HTTP metrics. When FrankenPHP is detected, a second tab provides thread-level introspection.
57
+
Ember connects to the Caddy admin API and auto-detects FrankenPHP if present.
82
58
83
-
### Options
59
+
##Documentation
84
60
85
-
```
86
-
--addr string Caddy admin API address (default "http://localhost:2019")
87
-
--interval dur Polling interval (default 1s)
88
-
--slow-threshold ms Slow request threshold (default 500)
89
-
--pid int FrankenPHP PID (auto-detected if not set)
Ember reads data from the Caddy admin API. This page explains what your Caddyfile needs for Ember to work.
4
+
5
+
## Admin API
6
+
7
+
Ember connects to the Caddy admin API (default: `localhost:2019`). Make sure it's enabled:
8
+
9
+
```
10
+
{
11
+
admin localhost:2019
12
+
}
13
+
```
14
+
15
+
> **Caution:** The admin API is unauthenticated by default. Do not expose it on a public interface. See [Caddy's admin API documentation](https://caddyserver.com/docs/caddyfile/options#admin) for authentication options.
16
+
17
+
## Metrics Directive
18
+
19
+
The `metrics` directive enables Prometheus-format metrics on the admin API. Without it, Ember cannot display HTTP traffic data.
20
+
21
+
```
22
+
{
23
+
admin localhost:2019
24
+
metrics
25
+
}
26
+
```
27
+
28
+
This exposes the following Caddy metrics at the `/metrics` admin endpoint:
29
+
30
+
| Metric | Description |
31
+
|--------|-------------|
32
+
|`caddy_http_requests_total`| Total HTTP requests (with host, method, status labels) |
33
+
|`caddy_http_request_duration_seconds`| Request duration histogram (with host labels and buckets) |
34
+
|`caddy_http_requests_in_flight`| Currently in-flight requests |
35
+
|`caddy_http_response_size_bytes`| Response body size |
36
+
37
+
Ember parses these metrics to compute per-host RPS, average latency, percentiles, status code rates, and more.
38
+
39
+
## FrankenPHP Detection
40
+
41
+
Ember automatically detects FrankenPHP by sending `GET /frankenphp/threads` to the admin API. If the endpoint responds with `200 OK`, the FrankenPHP tab is enabled.
42
+
43
+
If auto-detection does not work, you can specify the process ID manually:
44
+
45
+
```bash
46
+
ember --pid 12345
47
+
```
48
+
49
+
When no `--pid` is provided, Ember scans the process list for a FrankenPHP process. If none is found, it falls back to scanning for a Caddy process for CPU/RSS monitoring.
50
+
51
+
## Remote Caddy Instances
52
+
53
+
Use the `--addr` flag to point Ember to a remote Caddy admin API:
54
+
55
+
```bash
56
+
ember --addr http://10.0.0.5:2019
57
+
```
58
+
59
+
The admin API must be reachable from wherever Ember runs.
|**4xx/s**| Client error rate (displayed in yellow) |
21
+
|**5xx/s**| Server error rate (displayed in red) |
22
+
23
+
> **Note:** If you see a host named `*`, it means Caddy metrics lack per-host labels. The `*` row aggregates all traffic. Make sure your Caddyfile routes include host matchers for per-host breakdown.
24
+
25
+
## Latency Percentiles
26
+
27
+
P50, P90, P95, and P99 are computed from Prometheus histogram buckets (`caddy_http_request_duration_seconds`). These percentiles appear per host in the traffic table and in the host detail panel.
28
+
29
+
> **Tip:** If percentile columns are empty, verify that the `metrics` directive is present in your Caddyfile global block. See [Caddy Configuration](caddy-configuration.md).
30
+
31
+
## Sorting
32
+
33
+
Press `s` to cycle the sort field forward, `S` to cycle backward. Available sort fields:
0 commit comments