Pim van Pelt
4ab3096c8b
Prometheus metrics (internal/metrics/, cmd/maglevd/) - New --metrics-addr flag (default :9091, env MAGLEV_METRICS_ADDR) serving /metrics via promhttp. - Gauge metrics scraped on demand via a custom prometheus.Collector: maglev_backend_state, maglev_backend_health, maglev_backend_enabled, maglev_frontend_pool_backend_weight. - Inline counter/histogram metrics updated per probe: maglev_probe_total (by backend, type, result, code), maglev_probe_duration_seconds (by backend, type), maglev_backend_transitions_total (by backend, from, to). - StateSource interface in metrics package breaks the import cycle with checker; checker.Checker satisfies it via GetBackendInfo. Integration tests - Run maglevd inside a containerlab node (debian:trixie-slim with build/ bind-mounted) instead of on the host. Eliminates port collisions with any host maglevd. - maglevc commands run via docker exec into the maglevd container. - Add 6 Prometheus test cases: endpoint reachable, all backends report state=up, probe counters non-zero, duration histogram populated, pool weights correct, transition counters present.
144 lines
7.3 KiB
Markdown
144 lines
7.3 KiB
Markdown
# User Guide
|
|
|
|
## maglevd
|
|
|
|
`maglevd` is the health-checker daemon. It probes backends according to the
|
|
configuration file, maintains their health state, and exposes a gRPC API for
|
|
inspection and control.
|
|
|
|
### Flags
|
|
|
|
| Flag | Environment variable | Default | Description |
|
|
|---|---|---|---|
|
|
| `--config` | `MAGLEV_CONFIG` | `/etc/vpp-maglev/maglev.yaml` | Path to the YAML configuration file. |
|
|
| `--grpc-addr` | `MAGLEV_GRPC_ADDR` | `:9090` | TCP address on which the gRPC server listens. |
|
|
| `--metrics-addr` | `MAGLEV_METRICS_ADDR` | `:9091` | TCP address for the Prometheus `/metrics` HTTP endpoint. Set to empty to disable. |
|
|
| `--log-level` | `MAGLEV_LOG_LEVEL` | `info` | Log verbosity: `debug`, `info`, `warn`, or `error`. |
|
|
| `--check` | — | — | Read and validate the config file, then exit. Exits 0 if the config is valid, 1 on YAML parse error, 2 on semantic error. |
|
|
| `--reflection` | — | `true` | Enable gRPC server reflection. Allows `grpcurl` to introspect the API without the `.proto` file. Set to `false` to disable. |
|
|
| `--version` | — | — | Print version, commit hash, and build date, then exit. |
|
|
|
|
Flags take precedence over environment variables. Both are optional; defaults
|
|
are used for anything not set.
|
|
|
|
### Signals
|
|
|
|
| Signal | Effect |
|
|
|---|---|
|
|
| `SIGHUP` | Reload the configuration file (same code path as `config reload` in `maglevc`). The file is checked before applying; if there is a parse or semantic error the reload is aborted and the error is logged (the daemon continues running with its current config). New backends are started, removed backends are stopped, backends whose health-check config is unchanged continue probing without interruption. |
|
|
| `SIGTERM` / `SIGINT` | Graceful shutdown. Active gRPC streams are closed, the server drains, then the process exits. |
|
|
|
|
### Capabilities
|
|
|
|
`maglevd` requires `CAP_NET_RAW` when any health check uses `type: icmp`.
|
|
All other check types (`tcp`, `http`) use normal TCP sockets and require no
|
|
special capabilities.
|
|
|
|
### Logging
|
|
|
|
All log output is written to stdout as JSON using Go's `log/slog`. The first
|
|
line logged after the logger is configured is a `starting` record that includes
|
|
`version`, `commit`, and `date`. Every state change emits a `backend-transition`
|
|
line at `INFO` level. Set `--log-level debug` to see individual probe attempts
|
|
and their outcomes.
|
|
|
|
---
|
|
|
|
## maglevc
|
|
|
|
`maglevc` is the interactive control-plane client. It connects to a running
|
|
`maglevd` over gRPC and either executes a single command or drops into an
|
|
interactive shell.
|
|
|
|
### Usage
|
|
|
|
```sh
|
|
maglevc [--server host:port] [--color[=bool]] [command...]
|
|
```
|
|
|
|
| Flag | Default | Description |
|
|
|---|---|---|
|
|
| `--server` | `localhost:9090` | Address of the `maglevd` gRPC server. |
|
|
| `--color` | `true` | Colorize static field labels in output (dark blue ANSI). Pass `--color=false` to disable, e.g. when piping. |
|
|
|
|
When `command` arguments are supplied the command is executed and `maglevc`
|
|
exits. When no arguments are given an interactive shell is started and the
|
|
build version is printed on entry.
|
|
|
|
### Commands
|
|
|
|
```
|
|
show version Print build version, commit hash, and build date.
|
|
|
|
show frontends [<name>] Without name: list all frontend names.
|
|
With name: show address, protocol, port, description,
|
|
and pools. Each pool lists its backends with weights
|
|
(if != 100) and marks disabled backends with [disabled].
|
|
|
|
show backends [<name>] Without name: list all backend names.
|
|
With name: show address, current state (with duration),
|
|
enabled flag, health check, and recent state transitions
|
|
with timestamps and how long ago each occurred.
|
|
|
|
show healthchecks [<name>] Without name: list all health-check names.
|
|
With name: show full health-check configuration.
|
|
|
|
set backend <name> pause Suspend health checking for a backend, freezing its state.
|
|
set backend <name> resume Resume health checking; backend re-enters unknown state
|
|
and is probed immediately.
|
|
set backend <name> disable Stop probing entirely and remove the backend from rotation.
|
|
The backend remains visible (state: removed) and can be
|
|
re-enabled without reloading configuration.
|
|
set backend <name> enable Re-enable a disabled backend. A fresh probe goroutine is
|
|
started and the backend re-enters unknown state.
|
|
|
|
set frontend <name> pool <pool> backend <name> weight <0-100>
|
|
Set the weight of a backend within a pool. Weight 0 keeps
|
|
the backend in the pool but assigns it no traffic.
|
|
Takes effect immediately without reloading configuration.
|
|
|
|
watch events Stream all events (log, backend transitions, frontend)
|
|
[num <n>] Stop after receiving n events.
|
|
[log [level <level>]] Include log events. level is debug|info|warn|error
|
|
(default: info). Omitting log/backend/frontend enables all.
|
|
[backend] Include backend transition events.
|
|
[frontend] Include frontend events (reserved for future use).
|
|
|
|
Each event is printed as compact JSON on its own line.
|
|
Press any key or Ctrl-C to stop. Examples:
|
|
|
|
watch events
|
|
watch events num 20
|
|
watch events log level debug
|
|
watch events backend num 100
|
|
watch events log level debug backend
|
|
|
|
config check Ask maglevd to read and validate its current config file.
|
|
Prints "config ok" on success, or the error (parse or
|
|
semantic) returned by the daemon.
|
|
config reload Check and reload the configuration file. Equivalent to
|
|
sending SIGHUP to maglevd. Prints "config reloaded" on
|
|
success, or the specific error (parse, semantic, or
|
|
reload) that prevented the reload.
|
|
|
|
quit / exit Leave the interactive shell.
|
|
```
|
|
|
|
### Interactive shell
|
|
|
|
The shell prompt is `maglev> `. Two completion mechanisms are available:
|
|
|
|
**Tab completion** — pressing `<Tab>` at any point completes the current token.
|
|
Fixed keywords (commands and subcommands) are completed from the command tree.
|
|
Backend, frontend, and health-check names are fetched live from the server with
|
|
a 1-second timeout. If the partial token is unambiguous the word is completed
|
|
in place; if multiple candidates exist they are listed and the prompt is
|
|
restored.
|
|
|
|
**Inline help (`?`)** — typing `?` at any point prints the available
|
|
completions for the current position, with a short description next to each
|
|
keyword. The `?` character is not added to the input line.
|
|
|
|
Commands and keywords support **prefix matching**: typing `sh ba` is equivalent
|
|
to `show backends`, and `sh ba nginx0` is equivalent to `show backends nginx0`.
|