Proxy metrics
The NetBird Proxy serves the Reverse Proxy feature: HTTP / TLS / TCP / UDP traffic forwarded to peers without requiring those peers to be reachable directly. Its metrics describe the inbound HTTP layer, the L4 (TCP/UDP) listeners, ACME certificate issuance, and the sync loop with Management. All metric names are prefixed with proxy_.
Endpoint
Unlike the other services, the proxy does not run a dedicated metrics server. Instead it mounts /metrics on the same HTTP server as its health probes.
| Setting | Default |
|---|---|
| Address | localhost:8080 |
| Path | /metrics |
| Flag | --health-addr |
| Env var | NB_PROXY_HEALTH_ADDRESS |
netbird-proxy --health-addr 0.0.0.0:8080
To scrape the proxy from another host, bind the health server to a routable interface (0.0.0.0:8080 or a specific address) instead of localhost.
The same endpoint serves liveness, readiness, and startup probes. If you expose it publicly, restrict access to your Prometheus scraper and your orchestrator's health-check source.
The metric tables below show the on-the-wire Prometheus names. Counter names end in _total; histograms expand to <name>_bucket / <name>_sum / <name>_count. See Naming conventions for the full transformation rules.
HTTP
Inbound HTTP/HTTPS traffic terminated by the proxy and forwarded to peers.
| Metric | Type | Description |
|---|---|---|
proxy_http_request_counter_total | Counter | Total HTTP requests handled. |
proxy_http_active_requests | Gauge | In-flight HTTP requests. |
proxy_http_request_duration_ms_milliseconds | Histogram | End-to-end request duration. |
proxy_backend_duration_ms_milliseconds | Histogram | Round-trip time to the upstream peer. |
proxy_domains_count | Gauge | Domains currently configured. |
proxy_paths_count | Gauge | Path routes currently configured. |
proxy_certificate_issue_duration_ms_milliseconds | Histogram | ACME certificate issuance duration. |
L4 (TCP/UDP)
Layer-4 passthrough services configured on the proxy.
| Metric | Type | Description |
|---|---|---|
proxy_l4_services_count | Gauge | L4 services currently configured. |
proxy_tcp_active_connections | Gauge | Active TCP/TLS connections. |
proxy_tcp_connections_total | Counter | Total TCP/TLS connections accepted. |
proxy_tcp_connection_duration_ms_milliseconds | Histogram | TCP/TLS connection duration. |
proxy_tcp_bytes_total | Counter | Bytes transferred over TCP/TLS. |
proxy_udp_active_sessions | Gauge | Active UDP relay sessions. |
proxy_udp_sessions_total | Counter | Total UDP sessions opened. |
proxy_udp_packets_total | Counter | UDP packets relayed. |
proxy_udp_bytes_total | Counter | Bytes transferred over UDP. |
Sync with Management
The proxy receives configuration (domains, paths, L4 services) from Management over a gRPC stream.
| Metric | Type | Description |
|---|---|---|
proxy_sync_snapshot_duration_ms_milliseconds | Histogram | Time to apply the initial snapshot from Management. |
proxy_sync_batch_duration_ms_milliseconds | Histogram | Time to apply a mapping batch. |
proxy_peer_add_duration_ms_milliseconds | Histogram | Time to add a peer to the embedded client (key generation + gRPC + embed). |