Skip to content
Huginn ProxyHuginn Proxy

Telemetry

There are two separate HTTP servers: one on Huginn Proxy (config file) and one on the eBPF agent (environment variables only). They are not merged: scrape both when you run the full TCP SYN stack; scrape only the proxy when eBPF is off.

Full metric names, labels, and PromQL examples live in the repo: do not duplicate them here: TELEMETRY.md.

Proxy (huginn-proxy)

Section titled “Proxy (huginn-proxy)”

Configured under [telemetry] in the config file. Static: the listener port is fixed at startup.

Key Default Description
metrics_port omitted (disabled) Port for Prometheus + health HTTP server (/metrics, /health, /ready, /live).
otel_log_level "warn" OpenTelemetry SDK internal log level (not application logs).
health_format "json" Body of /health, /ready, /live (and observability 404/500). "json" or "text". Does not affect /metrics. 
telemetry:
  metrics_port: 9090
  otel_log_level: "warn"
  health_format: json

Endpoints (proxy)

Section titled “Endpoints (proxy)”
Path Role
/health Process is running
/ready Ready to serve. 200 JSON is {"status":"serving"} (text token SERVING). 503 reports why: proxy_starting or proxy_draining (text STARTING / DRAINING). With TCP SYN fingerprinting, also capture_absent / capture_draining / capture_detached (text NOCAPTURE). Independent of backend health.
/live Liveness; stays 200 during drain
/metrics Prometheus text

health_format is json (default) or text (single token, no trailing newline). Use text when the balancer matches the body and ignores the status code.

Scrape URL: http://<host>:<metrics_port>/metrics (e.g. http://localhost:9090/metrics).

Metric families (proxy, summary)

Section titled “Metric families (proxy, summary)”

52 huginn_* metrics: connections, PROXY protocol, requests, throughput, TLS, JA4 / HTTP/2 fingerprinting, backend timings, active health checks, rate limits, IP filter, headers, mTLS, config reload, TLS cert reload (FNV-1a hashes), build info. TCP SYN lookup metrics on the proxy reflect map reads; capture counters (including the optional SYN rate limiter) are on the agent. See TELEMETRY.md.

eBPF agent (huginn-ebpf-agent)

Section titled “eBPF agent (huginn-ebpf-agent)”

Only when the TCP SYN path is enabled. Configured with environment variables, not [telemetry]:

Variable Role
HUGINN_EBPF_METRICS_ADDR Bind address for the agent HTTP server
HUGINN_EBPF_METRICS_PORT Port (often 9091)
HUGINN_EBPF_HEALTH_FORMAT Same json / text bodies as proxy health_format.

Same four paths as the proxy (/health, /ready, /live, /metrics) for Kubernetes-style probes. /ready is attached + required pins + not draining (not pins-only). Use it for kubelet only; do not AND it with the proxy as a second load-balancer monitor.

Agent-only metrics (examples): tcp_syn_captured_total, tcp_syn_insert_failures_total, tcp_syn_malformed_total, tcp_syn_rate_skipped_total, tcp_syn_rate_allowed_total, tcp_syn_rate_limit_enabled, agent_up, huginn_ebpf_agent_build_info: full list in TELEMETRY.md: eBPF Agent Metrics.

Bind address vs scrape URL: eBPF TCP setup: Agent metrics bind address.

Prometheus (two jobs when using eBPF)

Section titled “Prometheus (two jobs when using eBPF)”

Scrape the proxy and the agent on different ports (e.g. 9090 and 9091). Example:

scrape_configs:
  - job_name: huginn-proxy
    static_configs:
      - targets: ["localhost:9090"]


  - job_name: huginn-ebpf-agent
    static_configs:
      - targets: ["localhost:9091"]

Adjust hosts to your Docker/Kubernetes networking. With eBPF Compose, ports are often published on the host as in docker-compose.release-ebpf.yml.

Section titled “Related”