Security Observability Stack (Grafana, Loki & Alloy)

RouteWarden includes a complete, cloud-native security observability stack powered by Grafana, Grafana Loki, and Grafana Alloy.

It continuously ingests, parses, indexes, and visualizes structured security events across all your RouteWarden gateways (Traefik, Caddy, NGINX, and TCP Warden) with zero manual dashboard setup.

---

Architecture Overview

Core Components

1. Grafana Alloy: Modern OpenTelemetry-based collector. Discovers Docker containers via /var/run/docker.sock and host logs, normalizes RouteWarden JSON events (loki.process), extracts indexed stream labels (verdict, status_code, gateway, method, protocol, transport), and attaches structured metadata (client_ip, path, matched_pattern, rule_id, service).
2. Grafana Loki: Scalable, high-efficiency log aggregation engine that indexes metadata and provides lightning-fast LogQL queries.
3. Grafana: Pre-provisioned with the "RouteWarden — Threat & Security Intelligence" dashboard, pre-configured Loki data source, and ready-to-use threat panels.

---

Quick Start CLI Management (rwarden dashboard)

The RouteWarden CLI embeds all Docker Compose, Alloy, and Grafana dashboard templates directly in the binary. You can launch, inspect, and stop the stack with single commands:

# 1. Start the observability stack (launches Grafana at http://localhost:3000)rwarden dashboard# 2. Start on custom ports without auto-opening the browserrwarden dashboard up --port 8080 --loki-port 3100 --no-open

---

Dashboard Documentation Subsections

Explore the specialized guides below to configure logging, customize deployment, reuse existing infrastructure, or query events:

Container Discovery & Opt-In Logging

Configure container discovery via /var/run/docker.sock, understand the pure opt-in model (routewarden.logs=true), and inspect Layer 4 UDP protocol logs and network syslog (port 1514).

Pre-Configured Dashboard & Panels

Detailed walkthrough of all built-in panels: KPI threat counters, multi-series attack timelines, top offender IPs with GeoIP flags, top probed targets, and interactive filter variables.

Standalone Docker Compose Deployment

Deploy in production without the CLI binary using standalone Docker Compose, configure GF_* environment variables, set up docker-compose.override.yml, and enable OAuth SSO (GitHub/Google).

Reusing an Existing Grafana & Loki Stack

Avoid redundant containers by importing the RouteWarden dashboard into your existing Grafana, integrating the parsing pipeline into your existing Alloy or Promtail, or running a lightweight shipper-only container.

LogQL Queries & Alerting Reference

LogQL cheat sheet for security operations (SOC), stream label specifications, high-cardinality metadata reference, and ready-to-use Grafana alert rule definitions.

---

Command Reference

Subcommand / Flag	Type	Default	Description
up	subcommand	—	Launch Grafana, Loki, and Alloy stack via Docker Compose (default)
down	subcommand	—	Stop and tear down running observability stack containers
status	subcommand	—	Display status of Grafana, Loki, and Alloy containers
export [dir]	subcommand	./observability	Export compose, Alloy, and Grafana configs to disk
--port	int	3000	Port for Grafana dashboard UI
--loki-port	int	3100	Port for Loki log engine
--dir	string	~/.routewarden/observability	Working directory storing the stack files
--no-open	bool	false	Do not automatically launch the browser upon startup