# 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 from the Rust
receiver's 1 Hz telemetry bridge:

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

Rust receive-path quality is exported separately. In particular,
`mikrosuricata_tzsp_receiver_kernel_udp_drops_total` is the Linux UDP socket
drop counter and should stay at zero during high-rate capture tests. The
dashboard includes it in **Sensor loss & decode errors**.

`/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.

## Rust TZSP data-plane health (0.11.0+)

The receiver now exports both kernel and userspace back-pressure signals. In addition to `mikrosuricata_tzsp_receiver_kernel_udp_drops_total`, watch `mikrosuricata_tzsp_receiver_queue_dropped_datagrams_total`, `mikrosuricata_tzsp_receiver_queue_depth_batches`, `mikrosuricata_tzsp_receiver_queue_capacity_batches` and `mikrosuricata_tzsp_receiver_capture_efficiency_pct`. A small RouterOS kernel socket buffer is expected; loss should be judged by the drop counters, not by buffer size alone.