add basic metrics for Prometheus (#345)

This PR adds basic metrics, exposed with Prometheus.
go-ncm accepts one cmd line argument now: --prometheusport=8080

if specified, prometheus metrics will be available at http://0.0.0.0:prometheusport/metrics
if not specified, the prometheus endpoint will not be started and not be available.
Metrics
device_count
Type: Gauge
Description: Tracks the number of iOS devices currently connected to the system. A gauge is a metric that represents a single numerical value that can arbitrarily go up and down.
Usage: Helps in monitoring the fluctuation in the number of connected iOS devices over time.
network_receive_bytes
Type: CounterVec
Description: A counter metric that represents the cumulative bytes received on the virtual TAP device. It is labeled by device and serial to provide granular tracking across different devices.
Labels:
device: network interface name
serial: The serial number of the iOS device.
Usage: Useful for analyzing the volume of incoming network traffic on a per-device basis.
network_send_bytes
Type: CounterVec
Description: A counter metric for tracking the total bytes sent to the virtual TAP device. Similar to network_receive_bytes, it uses device and serial labels for detailed monitoring.
Labels:
device: network interface name
serial: The serial number of the iOS device.
Usage: Allows for the assessment of outgoing network traffic per device, aiding in network performance evaluation.
usb_send_bytes
Type: CounterVec
Description: Represents the total bytes sent through the USB endpoint to connected devices. This metric is labeled by serial to differentiate between devices.
Labels:
serial: The serial number of the iOS device.
Usage: Facilitates tracking of data sent to devices over USB, which is crucial for understanding USB throughput and identifying potential bottlenecks.
usb_receive_bytes
Type: CounterVec
Description: Counts the bytes received from iOS devices over the USB endpoint. It is labeled with serial, allowing for device-specific traffic analysis.
Labels:
serial: The serial number of the iOS device.
Usage: Essential for monitoring the amount of data received from devices over USB, offering insights into USB data receipt efficiency and potential issues.

---------

Co-authored-by: Daniel Paulus <daniel.paulus@mesmerhq.com>

Author: danielpaulus

Makefile

@@ -36,7 +36,7 @@ build:
 
 # Run the Go program with sudo
 run: build
-	@sudo ./$(NCM_BINARY_NAME)
+	@sudo ./$(NCM_BINARY_NAME) --prometheusport=8080
 
 # Build and run
 up: build run

cmd/cdc-ncm/main.go

@@ -1,6 +1,7 @@
 package main
 
 import (
+	"flag"
 	ncm "go-ios-cdcncm"
 	"log/slog"
 	"os"
@@ -23,10 +24,23 @@ func checkLinux() {
 	}
 }
 
+// accepts one cmd line argument: --prometheusport=8080
+// if specified, prometheus metrics will be available at http://0.0.0.0:prometheusport/metrics
+// if not specified, the prometheus endpoint will not be started and not be available.
 func main() {
 	checkLinux()
 	checkUsbMux()
 	checkRoot()
+	// Define a string flag with a default value and a short description.
+	// This will read the command-line argument for --prometheusport.
+	prometheusPort := flag.Int("prometheusport", -1, "The port for Prometheus metrics")
+	// Parse the flags from the command-line arguments.
+	flag.Parse()
+	if *prometheusPort != -1 {
+		go ncm.StartPrometheus(*prometheusPort)
+	} else {
+		slog.Info("prometheus metrics not configured. start with '--prometheusport=8080' to expose prometheus metrics.")
+	}
 	c := make(chan os.Signal, 1)
 	signal.Notify(c, os.Interrupt)
 	err := ncm.Start(c)

ncm/go.mod

@@ -3,13 +3,25 @@ module go-ios-cdcncm
 go 1.21
 
 require (
+	github.com/Masterminds/semver v1.5.0
+	github.com/google/gousb v1.1.2
+	github.com/prometheus/client_golang v1.18.0
+	github.com/songgao/packets v0.0.0-20160404182456-549a10cd4091
+	github.com/songgao/water v0.0.0-20200317203138-2b4b6d7c09d8
+	github.com/stretchr/testify v1.8.4
+)
+
+require (
+	github.com/beorn7/perks v1.0.1 // indirect
+	github.com/cespare/xxhash/v2 v2.2.0 // indirect
 	github.com/davecgh/go-spew v1.1.1 // indirect
-	github.com/google/gousb v1.1.2 // indirect
+	github.com/kr/text v0.2.0 // indirect
+	github.com/matttproud/golang_protobuf_extensions/v2 v2.0.0 // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
-	github.com/songgao/packets v0.0.0-20160404182456-549a10cd4091 // indirect
-	github.com/songgao/water v0.0.0-20200317203138-2b4b6d7c09d8 // indirect
-	github.com/stretchr/objx v0.5.0 // indirect
-	github.com/stretchr/testify v1.8.4 // indirect
+	github.com/prometheus/client_model v0.5.0 // indirect
+	github.com/prometheus/common v0.45.0 // indirect
+	github.com/prometheus/procfs v0.12.0 // indirect
 	golang.org/x/sys v0.15.0 // indirect
+	google.golang.org/protobuf v1.31.0 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 )

ncm/go.sum

@@ -1,25 +1,50 @@
-github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/Masterminds/semver v1.5.0 h1:H65muMkzWKEuNDnfl9d70GUjFniHKHRbFPGBuZ3QEww=
+github.com/Masterminds/semver v1.5.0/go.mod h1:MB6lktGJrhw8PrUyiEoblNEGEQ+RzHPF078ddwwvV3Y=
+github.com/beorn7/perks v1.0.1 h1:VlbKKnNfV8bJzeqoa4cOKqO6bYr3WgKZxO8Z16+hsOM=
+github.com/beorn7/perks v1.0.1/go.mod h1:G2ZrVWU2WbWT9wwq4/hrbKbnv/1ERSJQ0ibhJ6rlkpw=
+github.com/cespare/xxhash/v2 v2.2.0 h1:DC2CZ1Ep5Y4k3ZQ899DldepgrayRUGE6BBZ/cd9Cj44=
+github.com/cespare/xxhash/v2 v2.2.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
+github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/golang/protobuf v1.5.0/go.mod h1:FsONVRAS9T7sI+LIUmWTfcYkHO4aIWwzhcaSAoJOfIk=
+github.com/google/go-cmp v0.5.5/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
+github.com/google/go-cmp v0.5.9 h1:O2Tfq5qg4qc4AmwVlvv0oLiVAGB7enBSJ2x2DqQFi38=
+github.com/google/go-cmp v0.5.9/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
 github.com/google/gousb v1.1.2 h1:1BwarNB3inFTFhPgUEfah4hwOPuDz/49I0uX8XNginU=
 github.com/google/gousb v1.1.2/go.mod h1:GGWUkK0gAXDzxhwrzetW592aOmkkqSGcj5KLEgmCVUg=
+github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
+github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
+github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
+github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
+github.com/matttproud/golang_protobuf_extensions/v2 v2.0.0 h1:jWpvCLoY8Z/e3VKvlsiIGKtc+UG6U5vzxaoagmhXfyg=
+github.com/matttproud/golang_protobuf_extensions/v2 v2.0.0/go.mod h1:QUyp042oQthUoa9bqDv0ER0wrtXnBruoNd7aNjkbP+k=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/prometheus/client_golang v1.18.0 h1:HzFfmkOzH5Q8L8G+kSJKUx5dtG87sewO+FoDDqP5Tbk=
+github.com/prometheus/client_golang v1.18.0/go.mod h1:T+GXkCk5wSJyOqMIzVgvvjFDlkOQntgjkJWKrN5txjA=
+github.com/prometheus/client_model v0.5.0 h1:VQw1hfvPvk3Uv6Qf29VrPF32JB6rtbgI6cYPYQjL0Qw=
+github.com/prometheus/client_model v0.5.0/go.mod h1:dTiFglRmd66nLR9Pv9f0mZi7B7fk5Pm3gvsjB5tr+kI=
+github.com/prometheus/common v0.45.0 h1:2BGz0eBc2hdMDLnO/8n0jeB3oPrt2D08CekT0lneoxM=
+github.com/prometheus/common v0.45.0/go.mod h1:YJmSTw9BoKxJplESWWxlbyttQR4uaEcGyv9MZjVOJsY=
+github.com/prometheus/procfs v0.12.0 h1:jluTpSng7V9hY0O2R9DzzJHYb2xULk9VTR1V1R/k6Bo=
+github.com/prometheus/procfs v0.12.0/go.mod h1:pcuDEFsWDnvcgNzo4EEweacyhjeA9Zk3cnaOZAZEfOo=
+github.com/rogpeppe/go-internal v1.10.0 h1:TMyTOH3F/DB16zRVcYyreMH6GnZZrwQVAoYjRBZyWFQ=
+github.com/rogpeppe/go-internal v1.10.0/go.mod h1:UQnix2H7Ngw/k4C5ijL5+65zddjncjaFoBhdsK/akog=
 github.com/songgao/packets v0.0.0-20160404182456-549a10cd4091 h1:1zN6ImoqhSJhN8hGXFaJlSC8msLmIbX8bFqOfWLKw0w=
 github.com/songgao/packets v0.0.0-20160404182456-549a10cd4091/go.mod h1:N20Z5Y8oye9a7HmytmZ+tr8Q2vlP0tAHP13kTHzwvQY=
 github.com/songgao/water v0.0.0-20200317203138-2b4b6d7c09d8 h1:TG/diQgUe0pntT/2D9tmUCz4VNwm9MfrtPr0SU2qSX8=
 github.com/songgao/water v0.0.0-20200317203138-2b4b6d7c09d8/go.mod h1:P5HUIBuIWKbyjl083/loAegFkfbFNx5i2qEP4CNbm7E=
-github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
-github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=
-github.com/stretchr/objx v0.5.0 h1:1zr/of2m5FGMsad5YfcqgdqdWrIhu+EBEJRhR1U7z/c=
-github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=
-github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
-github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
 github.com/stretchr/testify v1.8.4 h1:CcVxjf3Q8PM0mHUKJCdn+eZZtm5yQwehR5yeSVQQcUk=
 github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
 golang.org/x/sys v0.15.0 h1:h48lPFYpsTvQJZF4EKyI4aLHaev3CxivZmv7yZig9pc=
 golang.org/x/sys v0.15.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
+golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
+google.golang.org/protobuf v1.26.0-rc.1/go.mod h1:jlhhOSvTdKEhbULTjvd4ARK9grFBp09yW+WbY/TyQbw=
+google.golang.org/protobuf v1.31.0 h1:g0LDEJHgrBl9N9r17Ru3sqWhkIx2NB67okBHPwC7hs8=
+google.golang.org/protobuf v1.31.0/go.mod h1:HV8QOd/L58Z+nl8r43ehVNZIU/HEI6OcFqwMG9pJV4I=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
-gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

ncm/metrics.go

@@ -0,0 +1,51 @@
+package ncm
+
+import (
+	"fmt"
+	"log/slog"
+	"net/http"
+
+	"github.com/prometheus/client_golang/prometheus"
+	"github.com/prometheus/client_golang/prometheus/promhttp"
+)
+
+var (
+	deviceCount = prometheus.NewGauge(prometheus.GaugeOpts{
+		Name: "device_count",
+		Help: "How many iOS devices are connected",
+	})
+	networkReceiveBytes = prometheus.NewCounterVec(prometheus.CounterOpts{
+		Name: "network_receive_bytes",
+		Help: "Counter metric for received bytes on the virtual TAP device",
+	}, []string{"device", "serial"})
+	networkSendBytes = prometheus.NewCounterVec(prometheus.CounterOpts{
+		Name: "network_send_bytes",
+		Help: "Counter metric for bytes sent to the virtual TAP device",
+	}, []string{"device", "serial"})
+	usbSendBytes = prometheus.NewCounterVec(prometheus.CounterOpts{
+		Name: "usb_send_bytes",
+		Help: "Counter metric for send bytes on the usb endpoint",
+	}, []string{"serial"})
+	usbReceiveBytes = prometheus.NewCounterVec(prometheus.CounterOpts{
+		Name: "usb_receive_bytes",
+		Help: "Counter metric for received bytes on the USB endpoint",
+	}, []string{"serial"})
+)
+
+func StartPrometheus(port int) {
+	prometheus.MustRegister(deviceCount)
+	prometheus.MustRegister(networkReceiveBytes)
+	prometheus.MustRegister(networkSendBytes)
+	prometheus.MustRegister(usbSendBytes)
+	prometheus.MustRegister(usbReceiveBytes)
+
+	// Expose metrics endpoint
+	http.Handle("/metrics", promhttp.Handler())
+
+	// Start HTTP server
+	slog.Info("prometheus metrics up", "port", port, "endpoint", "/metrics")
+	err := http.ListenAndServe(fmt.Sprintf(":%d", port), nil)
+	if err != nil {
+		slog.Error("failed starting metrics endpoint", "err", err)
+	}
+}

ncm/ncm.go

@@ -58,16 +58,18 @@ type NcmWrapper struct {
 	targetWriter io.Writer
 	buf          *bytes.Buffer
 	sequenceNum  uint16
+	serial       string
 }
 
 const headerSignature = 0x484D434E
 
-func NewWrapper(targetReader io.Reader, targetWriter io.Writer) *NcmWrapper {
+func NewWrapper(targetReader io.Reader, targetWriter io.Writer, serial string) *NcmWrapper {
 	return &NcmWrapper{
 		targetReader: targetReader,
 		targetWriter: targetWriter,
 		buf:          bytes.NewBuffer(nil),
 		sequenceNum:  0,
+		serial:       serial,
 	}
 }
 
@@ -136,7 +138,7 @@ func (r *NcmWrapper) ReadDatagrams() ([]ethernet.Frame, error) {
 	if err != nil {
 		return result, fmt.Errorf("ReadDatagrams: reading block failed bytes read:%d err: %w", b, err)
 	}
-
+	usbReceiveBytes.WithLabelValues(r.serial).Add(float64(h.BlockLen))
 	offset := h.NdpIndex
 	var dh datagramPointerHeader
 	err = binary.Read(bytes.NewReader(ncmTransferBlock[offset:]), binary.LittleEndian, &dh)
@@ -221,6 +223,7 @@ func (r *NcmWrapper) Write(p []byte) (n int, err error) {
 	}
 	buf.Write(p)
 	block = buf.Bytes()
+	usbSendBytes.WithLabelValues(r.serial).Add(float64(len(block)))
 	n, err = r.targetWriter.Write(block)
 	if err != nil {
 		return n, fmt.Errorf("write: writing ncm packet to usb failed %w", err)

ncm/usb.go

@@ -49,6 +49,7 @@ func printStatus() {
 		connectedDevices = append(connectedDevices, key.(string))
 		return true
 	})
+	deviceCount.Set(float64(len(connectedDevices)))
 	slices.Sort[[]string](connectedDevices)
 	slog.Debug("connected devices", "devices", connectedDevices)
 }
@@ -268,7 +269,7 @@ func createConfig(serial string) (*water.Interface, error) {
 // for some reason. This happens if the device is disconnected or if the virtual network interface is removed.
 // Closing interfaces is the responsibility of the caller.
 func ncmIOCopy(w io.Writer, r io.Reader, ifce *water.Interface, serial string) error {
-	wr := NewWrapper(r, w)
+	wr := NewWrapper(r, w, serial)
 	ctx, cancel := context.WithCancel(context.Background())
 	wg := sync.WaitGroup{}
 	wg.Add(2)
@@ -288,6 +289,7 @@ func ncmIOCopy(w io.Writer, r io.Reader, ifce *water.Interface, serial string) e
 					cancel()
 					continue
 				}
+				networkReceiveBytes.WithLabelValues(ifce.Name(), serial).Add(float64(n))
 				frame = frame[:n]
 				_, err = wr.Write(frame)
 				if err != nil {
@@ -318,6 +320,7 @@ func ncmIOCopy(w io.Writer, r io.Reader, ifce *water.Interface, serial string) e
 						slog.Error("failed sending frame to virtual device", "err", err)
 						cancel()
 					}
+					networkSendBytes.WithLabelValues(ifce.Name(), serial).Add(float64(len(frame)))
 				}
 			}
 		}