Feature Request: Prometheus Metrics Endpoint

[cybcon]

Summary

Expose a /metrics endpoint in the Prometheus exposition format that provides real-time counters and gauges for Modbus activity — enabling seamless integration with Prometheus, Grafana, and Kubernetes-native monitoring stacks.

---

Motivation

As Modbus mock servers are increasingly used in containerized CI/CD and staging environments, observability becomes a first-class concern. Currently, there is no built-in way to monitor the mock server's activity — how many requests it has handled, which function codes are being exercised, or how frequently specific registers are being read or written. A Prometheus-compatible /metrics endpoint would close this gap with zero additional tooling, since Prometheus scraping is already ubiquitous in Kubernetes environments.

---

Proposed Endpoint

GET /metrics

The response follows the standard Prometheus text exposition format and can be scraped directly by a Prometheus instance or any compatible agent (e.g. Grafana Alloy, OpenTelemetry Collector):

# HELP modbus_requests_total Total number of Modbus requests received, by function code
# TYPE modbus_requests_total counter
modbus_requests_total{function_code="01"} 142
modbus_requests_total{function_code="03"} 978
modbus_requests_total{function_code="06"} 314
modbus_requests_total{function_code="16"} 57

# HELP modbus_register_reads_total Total number of read operations per register
# TYPE modbus_register_reads_total counter
modbus_register_reads_total{type="holding",address="42"} 320
modbus_register_reads_total{type="input",address="7"} 88

# HELP modbus_register_writes_total Total number of write operations per register
# TYPE modbus_register_writes_total counter
modbus_register_writes_total{type="holding",address="42"} 75
modbus_register_writes_total{type="coil",address="1"} 12

# HELP modbus_errors_total Total number of Modbus errors returned, by exception code
# TYPE modbus_errors_total counter
modbus_errors_total{exception_code="02"} 5

# HELP modbus_connected_clients Current number of active Modbus TCP client connections
# TYPE modbus_connected_clients gauge
modbus_connected_clients 3

# HELP modbus_server_uptime_seconds Total uptime of the mock server in seconds
# TYPE modbus_server_uptime_seconds counter
modbus_server_uptime_seconds 86432

---

Suggested Metrics

Metric	Type	Labels	Description
modbus_requests_total	Counter	function_code	Total requests received per Modbus function code
modbus_register_reads_total	Counter	type, address	Read operations per register
modbus_register_writes_total	Counter	type, address	Write operations per register
modbus_errors_total	Counter	exception_code	Modbus exception responses returned
modbus_connected_clients	Gauge	—	Number of currently active TCP connections
modbus_server_uptime_seconds	Counter	—	Total server uptime in seconds

---

Configuration

The metrics endpoint should be configurable to avoid port conflicts with the REST API (see related feature request: REST API / HTTP Interface for Runtime Register Access):

metrics:
  enabled: true
  port: 9090          # Prometheus default scrape port
  path: /metrics      # Standard Prometheus path

A Kubernetes ServiceMonitor resource for the Prometheus Operator could then be configured as follows:

apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: modbus-mock
spec:
  endpoints:
    - port: metrics
      path: /metrics
      interval: 15s
  selector:
    matchLabels:
      app: modbus-mock

---

Use Cases

• Verifying that a device-under-test exercises the expected set of Modbus function codes during an integration test run
• Detecting unexpected register access patterns in automated test pipelines
• Monitoring mock server load and connection counts in long-running staging environments
• Building Grafana dashboards for visual inspection of Modbus traffic during development
• Alerting on elevated Modbus error rates via Prometheus alerting rules

---

Expected Behavior

• The /metrics endpoint is available as soon as the server starts, on a configurable port separate from the Modbus TCP port and the REST API port
• All counters persist for the lifetime of the server process and reset on restart
• Metrics are labeled with human-readable values (e.g. function_code="03" rather than raw integers) where appropriate
• The endpoint requires no authentication by default, but an optional bearer token or basic auth mechanism should be configurable for sensitive environments
• High-frequency register access does not meaningfully impact Modbus request latency (metrics collection must be non-blocking)

---

Why This Matters

Prometheus and Grafana have become the de facto observability stack for Kubernetes workloads. A native /metrics endpoint would allow teams to integrate the mock server into their existing monitoring infrastructure with no custom instrumentation — making it dramatically easier to write assertion-driven tests, build traffic dashboards, and catch regressions in device communication behavior automatically.

[cybcon]

Implemented in v2.2.0 #57