poc3

grafana/README.md

@@ -0,0 +1,75 @@
+# MikroSuricata Grafana dashboard
+
+`mikrosuricata-prometheus.json` is an importable Grafana dashboard for the
+Prometheus metrics exposed by MikroSuricata at `/metrics`.
+
+The exporter is intentionally scrape-only and lightweight: it serializes
+already available in-memory counters and the last Suricata EVE stats snapshot.
+A scrape does not query SQLite, Redis, RouterOS, the Suricata control socket,
+or analytics endpoints.
+
+The dashboard also uses monotonic TZSP traffic counters exported directly from
+the in-memory flow tracker:
+
+```text
+mikrosuricata_traffic_bytes_total{direction="total|inbound|outbound|internal|external"}
+mikrosuricata_traffic_packets_total{direction="total|inbound|outbound|internal|external"}
+```
+
+Grafana calculates bandwidth with PromQL `rate()` and converts bytes/s to
+bits/s. The top of the dashboard therefore shows current total, inbound and
+outbound throughput, packet rate, capture drops, a large throughput chart and
+traffic volume by direction for the selected time range.
+
+`/metrics` is protected by an IP/CIDR ACL configured through environment variables.
+The default allows loopback only:
+
+```dotenv
+METRICS_ALLOWED_IPS=127.0.0.1/32,::1/128
+METRICS_BASIC_AUTH_USERNAME=
+METRICS_BASIC_AUTH_PASSWORD=
+```
+
+For a remote Prometheus, set `METRICS_ALLOWED_IPS` to its source IP or subnet.
+Multiple entries are comma-separated. Leaving both Basic Auth values empty enables
+IP-only mode. Setting both enables IP + Basic Auth. Setting only one credential is
+invalid and prevents the web server from starting. An empty `METRICS_ALLOWED_IPS`
+denies all scrapes. The ACL uses the actual TCP peer address and does not trust
+`X-Forwarded-For`.
+
+Example IP-only Prometheus scrape configuration:
+
+```yaml
+scrape_configs:
+  - job_name: mikrosuricata
+    scrape_interval: 30s
+    metrics_path: /metrics
+    static_configs:
+      - targets: ["mikrosuricata:8080"]
+```
+
+Example IP + Basic Auth configuration in the application:
+
+```dotenv
+METRICS_ALLOWED_IPS=10.20.30.40/32
+METRICS_BASIC_AUTH_USERNAME=prometheus
+METRICS_BASIC_AUTH_PASSWORD=change-this-secret
+```
+
+and in Prometheus:
+
+```yaml
+scrape_configs:
+  - job_name: mikrosuricata
+    scrape_interval: 30s
+    metrics_path: /metrics
+    basic_auth:
+      username: prometheus
+      password: change-this-secret
+    static_configs:
+      - targets: ["mikrosuricata:8080"]
+```
+
+Import `mikrosuricata-prometheus.json` in Grafana and select the Prometheus
+datasource from the dashboard variable. Rate, percentage and ratio panels are
+calculated in PromQL, not by MikroSuricata.