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

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, 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.

openflux --config myconfig.yaml --stats

The periodic formatter is implemented in 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.

kill -USR1 $(pidof openflux)

This POSIX signal handler is registered in 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 within the serveHealth function and registered conditionally in 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.

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.

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.

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 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 and utils/logging.go.
• HTTP API exposes JSON metrics at /health when using the --api flag, with the handler defined in 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}