# How to View OpenFlux Tunnel Health Statistics: CLI and API Methods

> View OpenFlux tunnel health statistics via CLI using --stats or SIGUSR1, or access real-time JSON data with the --api flag for comprehensive monitoring.

- Repository: [p1neappleXpress/OpenFlux](https://github.com/p1neappleXpress/OpenFlux)
- Tags: how-to-guide
- Published: 2026-09-13

---

**You can view OpenFlux tunnel health statistics using the `--stats` flag for real-time console output, the `SIGUSR1` signal for on-demand reports, or the `--api` flag to expose a JSON endpoint at `/health`.**

OpenFlux creates a virtual network tunnel that continuously exchanges packets with remote servers while maintaining internal counters for diagnostics. Monitoring these **OpenFlux tunnel health statistics** is essential for diagnosing connectivity issues, measuring throughput, and verifying encryption overhead. This guide covers the two primary methods for accessing these metrics based on the actual implementation in the `p1neappleXpress/OpenFlux` repository.

## CLI-Based Statistics Monitoring

The `openflux` binary provides built-in command-line tools for real-time health monitoring without external dependencies. The implementation resides primarily in **[`tunnel/tunnel.go`](https://github.com/p1neappleXpress/OpenFlux/blob/main/tunnel/tunnel.go)**, where the `Tunnel` struct maintains counters including `txBytes`, `rxBytes`, `rxPackets`, `txPackets`, and `latencySamples`.

### Continuous Monitoring with --stats

Start OpenFlux with the `--stats` flag to enable a background goroutine that prints a formatted health table to stdout every 10 seconds. This display includes total packets transmitted and received, current bandwidth usage in bytes per second, average round-trip time in milliseconds, reconnect attempt counts, and encryption or compression overhead percentages.

```bash
openflux --config myconfig.yaml --stats

```

The periodic formatter is implemented in **[`utils/logging.go`](https://github.com/p1neappleXpress/OpenFlux/blob/main/utils/logging.go)**, which consumes the counter values updated by the tunnel's packet handlers.

### On-Demand Statistics with SIGUSR1

For situations where you need immediate visibility without restarting the process, send the `SIGUSR1` signal to a running OpenFlux instance. This triggers an instantaneous stats dump to stdout using the same formatting logic as the continuous monitor.

```bash
kill -USR1 $(pidof openflux)

```

This POSIX signal handler is registered in **[`main.go`](https://github.com/p1neappleXpress/OpenFlux/blob/main/main.go)** alongside the standard flag parsing logic, allowing operators to inspect **OpenFlux tunnel health statistics** at any time during the tunnel's lifecycle.

## HTTP JSON Health Endpoint

When automation or integration with monitoring systems is required, OpenFlux exposes a REST API that returns structured JSON data. The endpoint handler is defined in **[`transport/encrypted.go`](https://github.com/p1neappleXpress/OpenFlux/blob/main/transport/encrypted.go)** within the `serveHealth` function and registered conditionally in **[`main.go`](https://github.com/p1neappleXpress/OpenFlux/blob/main/main.go)** when the `--api` flag is present.

### Configuring the API Server

Enable the HTTP interface by starting the tunnel with the `--api` flag. By default, the server listens on `127.0.0.1:8080`, though you can override this via the `API_ADDR` environment variable.

```bash
export API_ADDR="127.0.0.1:9090"
openflux --config myconfig.yaml --api

```

### Querying Health Data

Send a GET request to the `/health` endpoint to retrieve a JSON object containing the same counters as the CLI output, plus a boolean `healthy` flag. This flag is set to `false` if the tunnel has been idle or experiencing consecutive timeouts.

```bash
curl http://127.0.0.1:8080/health | jq .

```

The JSON response includes `tx_bytes`, `rx_bytes`, `tx_packets`, `rx_packets`, `avg_rtt_ms`, and the `healthy` status boolean, making it compatible with Prometheus, Grafana, or custom monitoring scripts.

## Programmatic Access to Tunnel Metrics

For custom tooling written in Go, you can import the `tunnel` package and access statistics directly through the `Tunnel` struct's getter methods. This approach bypasses the CLI and HTTP layers for embedded applications.

```go
import (
    "fmt"
    "github.com/p1neappleXpress/OpenFlux/tunnel"
)

func showStats(t *tunnel.Tunnel) {
    fmt.Printf("TX bytes: %d  RX bytes: %d\n", t.TxBytes(), t.RxBytes())
    fmt.Printf("TX pkts: %d   RX pkts: %d\n", t.TxPackets(), t.RxPackets())
    fmt.Printf("Avg RTT: %.2f ms  Healthy: %v\n",
        t.AverageLatencyMs(), t.IsHealthy())
}

```

This method accesses the raw counters maintained in **[`tunnel/tunnel.go`](https://github.com/p1neappleXpress/OpenFlux/blob/main/tunnel/tunnel.go)** without the formatting overhead of the logging utilities.

## Summary

- **CLI monitoring** uses the `--stats` flag for continuous 10-second updates or `SIGUSR1` for immediate dumps, implemented in [`tunnel/tunnel.go`](https://github.com/p1neappleXpress/OpenFlux/blob/main/tunnel/tunnel.go) and [`utils/logging.go`](https://github.com/p1neappleXpress/OpenFlux/blob/main/utils/logging.go).
- **HTTP API** exposes JSON metrics at `/health` when using the `--api` flag, with the handler defined in [`transport/encrypted.go`](https://github.com/p1neappleXpress/OpenFlux/blob/main/transport/encrypted.go) and configurable via the `API_ADDR` environment variable.
- **Core counters** include transmitted/received bytes and packets, round-trip latency samples, reconnection counts, and health status booleans.
- **Go integration** allows direct access to the `Tunnel` struct methods for building custom monitoring tools.

## Frequently Asked Questions

### What metrics are included in OpenFlux tunnel health statistics?

The statistics include total packets transmitted and received, bandwidth usage in bytes per second, average round-trip time in milliseconds, reconnection attempt counts, dropped connection tallies, and encryption or compression overhead percentages. The JSON endpoint also provides a boolean `healthy` flag that indicates whether the tunnel is experiencing timeouts or idle periods.

### How do I enable the HTTP health endpoint?

Start the OpenFlux binary with the `--api` command-line flag. This registers the health handler in [`main.go`](https://github.com/p1neappleXpress/OpenFlux/blob/main/main.go) and starts an HTTP server listening on `127.0.0.1:8080` by default. You can customize the bind address by setting the `API_ADDR` environment variable before launching the process.

### Can I consume OpenFlux statistics from Go code?

Yes. Import the `github.com/p1neappleXpress/OpenFlux/tunnel` package and call getter methods on the `Tunnel` struct instance, such as `TxBytes()`, `RxPackets()`, and `AverageLatencyMs()`. This allows you to build custom dashboards or monitoring agents that access **OpenFlux tunnel health statistics** directly without parsing CLI output or HTTP responses.

### What port does the OpenFlux health API use by default?

The default port is `8080` bound to localhost (`127.0.0.1:8080`). This is defined in the API server initialization logic in [`main.go`](https://github.com/p1neappleXpress/OpenFlux/blob/main/main.go) and can be overridden by specifying a different address in the `API_ADDR` environment variable, such as `0.0.0.0:9090` for external access or a unix socket path.