Operations: probes, metrics, logs, exit codes

Pass --ops-port 9091 (or set NGSRV_OPS_PORT) to start a tiny HTTP server next to the tunnel. Wire its endpoints into Kubernetes probes and Prometheus scraping.

# Local example: tunnel + ops on :9091
$ ngsrv http 3000 --no-tui --ops-port 9091 --log-format json &

$ curl -s localhost:9091/healthz   # → ok
$ curl -s localhost:9091/readyz    # → ready (or "not_connected" while warming up)
$ curl -s localhost:9091/metrics | head
# HELP ngsrv_up 1 when the tunnel is connected and registered, 0 otherwise.
# TYPE ngsrv_up gauge
ngsrv_up 1
# HELP ngsrv_connected 1 when the WebSocket to the tunnel server is open.
ngsrv_connected 1
ngsrv_requests_total 14
ngsrv_bytes_in_total 982142
ngsrv_uptime_seconds 612.4

The CLI emits structured logs through log/slog. JSON is the right pick whenever a log scraper is reading stdout (Loki, Datadog, Cloud Logging, ELK, Vector, etc.). The default is text for interactive shells.

# JSON logs to stderr, INFO and above
ngsrv run --log-format json --log-level info

# Human-readable text logs, only warnings / errors
ngsrv http 3000 --log-format text --log-level warn

# Suppress info chatter, keep errors
ngsrv http 3000 --quiet            # equivalent to --log-level warn

Logs always go to stderr so commands that print URLs or tokens to stdout (e.g. for shell piping) stay clean. Setting --log-format json also auto-disables the TUI; the same happens when stdout is not a terminal (CI, k8s, systemd).

For sidecar deployments, declare every tunnel in one ngsrv.yml and run the whole bundle with ngsrv run. The ops server, logger, and signal handling are shared across all tunnels.

# ngsrv.yml
tunnels:
  - name: web
    port: 3000
    subdomain: web
  - name: api
    port: 8080
    subdomain: api
    security_policies:
      - ngsrv_ips_office
  - name: grpc
    port: 9000
    subdomain: grpc

# Run them all from one process.
$ ngsrv run --config ngsrv.yml --log-format json --ops-port 9091

/readyz reports 200 only when every declared tunnel is connected and registered. If any tunnel exits, the whole process exits so the supervisor (k8s, systemd) restarts it. See the config reference for the full schema.

The CLI returns stable exit codes so CI gates, supervisors, and shell scripts can react to why the process exited rather than to a generic non-zero. These codes are part of the public surface and will not be repurposed.