From 09c754c9a6610ecbedcaa13fdef4f0a737889d52 Mon Sep 17 00:00:00 2001 From: Ivo Brett Date: Fri, 17 Oct 2025 12:33:36 +0100 Subject: [PATCH] updated traefik logs doc for the new agent architecture --- .../community-guides/traefiklogsdashboard.mdx | 344 +++++++++++------- 1 file changed, 215 insertions(+), 129 deletions(-) diff --git a/self-host/community-guides/traefiklogsdashboard.mdx b/self-host/community-guides/traefiklogsdashboard.mdx index 2c0f4e4..2eb014c 100644 --- a/self-host/community-guides/traefiklogsdashboard.mdx +++ b/self-host/community-guides/traefiklogsdashboard.mdx @@ -1,34 +1,44 @@ --- -title: "Traefik Log Dashboard" +title: "Traefik Log Dashboard (v2 – Agent Architecture)" --- This is a community guide and is not officially supported. For issues or advanced configuration, please visit the [official repository](https://github.com/hhftechnology/traefik-log-dashboard). -If you’re already using the **Pangolin stack with Traefik as your reverse proxy**, you have powerful routing in place. But raw log files and scattered metrics make it difficult to truly understand traffic patterns. +If you’re already using the **Pangolin stack with Traefik as your reverse proxy**, you already have robust routing in place. +However, raw logs can be hard to interpret β€” making it difficult to visualize request patterns, latency, and geographic origins. -The **Enhanced Traefik Log Dashboard** adds **real-time monitoring, OpenTelemetry support, and geolocation analytics**, giving you a full picture of your traffic. +The **new Traefik Log Dashboard (v2)** introduces a **lightweight agent-based architecture** with **multi-instance scalability, enhanced GeoIP analytics, and a modern Next.js frontend** for real-time insights into your Traefik traffic. -## Features +--- -* **OpenTelemetry OTLP Support**: Real-time traces from Traefik v3+ -* **Hybrid Monitoring**: Combine OTLP traces with traditional log parsing -* **Geolocation**: MaxMind GeoIP integration with automatic updates -* **Analytics**: Live request rates, response times, error tracking -* **Production Ready**: Resource limits, health checks, optimized GC/memory +## πŸš€ Highlights (New in v2) + +* **Agent-based architecture**: The Go-powered agent parses logs, exposes metrics, and supports multiple Traefik instances. +* **Multi-agent support**: Monitor multiple Traefik setups (e.g., production, staging) from one dashboard. +* **Next.js 14 frontend**: Real-time charts, filters, and system stats in a responsive UI. +* **Enhanced GeoIP**: Supports both **City** and **Country** MaxMind databases. +* **System monitoring**: Built-in CPU, memory, and disk tracking. +* **Bearer token authentication**: Secure access between dashboard and agents. +* **Backward compatible** with existing Traefik log setups. + +--- ## Prerequisites -* Docker + Docker Compose -* Traefik v3.0+ (for OTLP) or v2.x (logs only) -* A working Pangolin stack +* Docker + Docker Compose +* Traefik v2.x or v3.x (logs in JSON format) +* A working **Pangolin stack** +* (Optional) MaxMind GeoLite2 databases (City + Country) -## Step 1: Configure Traefik +--- -### For OTLP + Logs (Recommended) +## Step 1: Configure Traefik Logs -Update `./config/traefik/traefik_config.yml`: +Ensure Traefik is outputting **JSON logs** and **access logs** are written to a file. + +Update your `./config/traefik/traefik_config.yml`: ```yaml log: @@ -39,178 +49,254 @@ log: accessLog: filePath: "/var/log/traefik/access.log" format: json + fields: + defaultMode: keep + headers: + defaultMode: keep +```` -tracing: - otlp: - http: - endpoint: "http://log-dashboard-backend:4318/v1/traces" - sampleRate: 0.1 # Adjust as needed - 0.1 for 10% sampling - globalAttributes: - environment: "production" - service.version: "v3.0" - deployment.environment: "pangolin" -``` +> πŸ’‘ Tip: JSON format is required for accurate parsing by the new agent. -### For Logs Only +--- + +## Step 2: Add Dashboard and Agent Services + +Extend your existing `docker-compose.yml` with the new services. ```yaml -log: - level: INFO - filePath: "/var/log/traefik/traefik.log" - -accessLog: - filePath: "/var/log/traefik/access.log" - format: json -``` - -## Step 2: Add Dashboard Services - -Extend your existing `docker-compose.yml` with: - -```yaml - log-dashboard-backend: - image: ghcr.io/hhftechnology/traefik-log-dashboard-backend:latest - container_name: log-dashboard-backend +# Traefik Log Dashboard Agent + traefik-agent: + image: hhftechnology/traefik-log-dashboard-agent:latest restart: unless-stopped ports: - - "4317:4317" # OTLP gRPC - - "4318:4318" # OTLP HTTP + - "5000:5000" volumes: + - ./data/positions:/data - ./config/traefik/logs:/logs:ro - - ./config/maxmind:/maxmind:ro + - ./config/maxmind:/geoip:ro environment: - - PORT=3001 - - TRAEFIK_LOG_FILE=/logs/access.log - - OTLP_ENABLED=true - - OTLP_GRPC_PORT=4317 - - OTLP_HTTP_PORT=4318 - - USE_MAXMIND=true - - MAXMIND_DB_PATH=/maxmind/GeoLite2-City.mmdb - - MAXMIND_FALLBACK_ONLINE=true - - GOGC=50 - - GOMEMLIMIT=500MiB + # Log Paths + - TRAEFIK_LOG_DASHBOARD_ACCESS_PATH=/logs/access.log + - TRAEFIK_LOG_DASHBOARD_ERROR_PATH=/logs/traefik.log + + # Authentication + - TRAEFIK_LOG_DASHBOARD_AUTH_TOKEN=YOUR_API_TOKEN + + # System Monitoring + - TRAEFIK_LOG_DASHBOARD_SYSTEM_MONITORING=true + + # GeoIP Configuration + - TRAEFIK_LOG_DASHBOARD_GEOIP_ENABLED=true + - TRAEFIK_LOG_DASHBOARD_GEOIP_CITY_DB=/geoip/GeoLite2-City.mmdb + - TRAEFIK_LOG_DASHBOARD_GEOIP_COUNTRY_DB=/geoip/GeoLite2-Country.mmdb + + # Log Format + - TRAEFIK_LOG_DASHBOARD_LOG_FORMAT=json + + # Server Port + - PORT=5000 + healthcheck: + test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:5000/api/logs/status"] + interval: 30s + timeout: 10s + retries: 3 + start_period: 10s - log-dashboard-frontend: - image: ghcr.io/hhftechnology/traefik-log-dashboard-frontend:latest - container_name: log-dashboard-frontend + # Traefik Log Dashboard - Web UI + traefik-dashboard: + image: hhftechnology/traefik-log-dashboard:dev-oltp + container_name: traefik-log-dashboard restart: unless-stopped ports: - - "3000:80" + - "3000:3000" environment: - - BACKEND_SERVICE=log-dashboard-backend - - BACKEND_PORT=3001 + # Agent Configuration + - AGENT_API_URL=http://traefik-agent:5000 + - AGENT_API_TOKEN=YOUR_API_TOKEN + - NODE_ENV=production + - PORT=3000 depends_on: - - log-dashboard-backend + traefik-agent: + condition: service_healthy + healthcheck: + test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:3000"] + interval: 30s + timeout: 10s + retries: 3 + start_period: 30s ``` -## Step 3: Setup MaxMind GeoIP (Optional but Recommended) +Please replace the YOUR_API_TOKEN with a secure token of your choice. -1. Create a free MaxMind account β†’ [GeoLite2 signup](https://www.maxmind.com/en/geolite2/signup) -2. Generate a license key -3. Create directory: +> πŸ†• The new agent replaces both `log-dashboard-backend` and `log-dashboard-frontend` from the previous guide. + +--- + +## Step 3: Setup MaxMind GeoIP (City + Country) + +GeoIP is optional but highly recommended for geographic analytics and maps. + +### 1. Create a free MaxMind account + +πŸ‘‰ [GeoLite2 Signup](https://www.maxmind.com/en/geolite2/signup) +Generate a license key and export it for Docker use: ```bash +export MAXMIND_LICENSE_KEY=your_license_key_here mkdir -p ./config/maxmind -export MAXMIND_LICENSE_KEY=your_key_here ``` -4. (Optional) Add updater service: +### 2. Add the GeoIP Database Updater + +Append this to your `docker-compose.yml`: ```yaml + # Optional: MaxMind GeoIP Database Updater maxmind-updater: image: alpine:latest - container_name: maxmind-db-updater + restart: "no" volumes: - ./config/maxmind:/data environment: - - MAXMIND_LICENSE_KEY=${MAXMIND_LICENSE_KEY} + - MAXMIND_LICENSE_KEY=${MAXMIND_LICENSE_KEY:-your-license-key-here} command: > sh -c " apk add --no-cache wget tar && cd /data && - wget -O GeoLite2-City.tar.gz 'https://download.maxmind.com/app/geoip_download?edition_id=GeoLite2-City&license_key=$MAXMIND_LICENSE_KEY&suffix=tar.gz' && - tar -xzf GeoLite2-City.tar.gz --strip-components=1 '*/GeoLite2-City.mmdb' && - rm -f GeoLite2-City.tar.gz + if [ ! -f GeoLite2-City.mmdb ] || [ \"$(find . -name 'GeoLite2-City.mmdb' -mtime +7)\" ]; then + echo 'Updating GeoLite2-City database...' + wget -O GeoLite2-City.tar.gz 'https://download.maxmind.com/app/geoip_download?edition_id=GeoLite2-City&license_key=${MAXMIND_LICENSE_KEY}&suffix=tar.gz' && + tar --wildcards -xzf GeoLite2-City.tar.gz --strip-components=1 '*/GeoLite2-City.mmdb' && + rm -f GeoLite2-City.tar.gz + fi && + if [ ! -f GeoLite2-Country.mmdb ] || [ \"$(find . -name 'GeoLite2-Country.mmdb' -mtime +7)\" ]; then + echo 'Updating GeoLite2-Country database...' + wget -O GeoLite2-Country.tar.gz 'https://download.maxmind.com/app/geoip_download?edition_id=GeoLite2-Country&license_key=${MAXMIND_LICENSE_KEY}&suffix=tar.gz' && + tar --wildcards -xzf GeoLite2-Country.tar.gz --strip-components=1 '*/GeoLite2-Country.mmdb' && + rm -f GeoLite2-Country.tar.gz + fi && + echo 'GeoIP databases updated successfully.' " ``` -## Step 4: Launch Stack +--- + +## Step 4: Launch the Stack ```bash docker compose up -d docker compose ps ``` +--- + ## Step 5: Access the Dashboard -* **Frontend UI** β†’ [http://localhost:3000](http://localhost:3000) +* **Web UI** β†’ [http://localhost:3000](http://localhost:3000) +* Default data source: `traefik-agent:5000` + +You should see real-time traffic metrics, GeoIP maps, error tracking, and system performance indicators. + +--- ## Key Features -* **Real-time statistics** (requests, response times, error rates) -* **Interactive world map** (request origins via MaxMind) -* **Service insights** (performance by router/service) -* **Hybrid monitoring** (OTLP + logs together) +βœ… **Real-time analytics** for request rates, response times, and errors +βœ… **GeoIP maps** with both City and Country-level resolution +βœ… **System health** (CPU, memory, disk) +βœ… **Multi-agent support** (monitor multiple Traefik instances) +βœ… **Secure API authentication** via token +βœ… **Responsive modern UI** + +--- + +## Advanced: Multi-Agent Setup + +You can deploy multiple `traefik-agent` instances across environments and connect them all to a single dashboard. + +Example: + +```yaml + traefik-agent-prod: + image: hhftechnology/traefik-log-dashboard-agent:latest + ports: ["5000:5000"] + environment: + - TRAEFIK_LOG_DASHBOARD_AUTH_TOKEN=prod_token + - TRAEFIK_LOG_DASHBOARD_ACCESS_PATH=/logs/access.log + - TRAEFIK_LOG_DASHBOARD_GEOIP_ENABLED=true + volumes: + - /var/log/traefik/prod:/logs:ro + - ./config/maxmind:/geoip:ro + - ./data/positions-prod:/data + + traefik-agent-staging: + image: hhftechnology/traefik-log-dashboard-agent:latest + ports: ["5001:5000"] + environment: + - TRAEFIK_LOG_DASHBOARD_AUTH_TOKEN=staging_token + - TRAEFIK_LOG_DASHBOARD_ACCESS_PATH=/logs/access.log + volumes: + - /var/log/traefik/staging:/logs:ro + - ./config/maxmind:/geoip:ro + + traefik-dashboard: + image: hhftechnology/traefik-log-dashboard:latest + ports: ["3000:3000"] + environment: + - NODE_ENV=production +``` + +Then, in the **Dashboard β†’ Settings β†’ Agents**, add each agent URL and token. + +--- ## Performance Tuning -For production or high-traffic environments, you may want to adjust settings to optimize resource usage and throughput. +| Setting | Description | Recommended | +| ----------------------------------------- | -------------------------------- | ------------- | +| `TRAEFIK_LOG_DASHBOARD_SYSTEM_MONITORING` | Enables system stats | `true` | +| `TRAEFIK_LOG_DASHBOARD_LOG_FORMAT` | Log parsing format | `json` | +| `GOMEMLIMIT` | Go memory cap | `512MiB–1GiB` | +| `GOGC` | Garbage collector aggressiveness | `20–50` | +| `sampleRate` (Traefik) | Sampling rate for OTLP tracing | `0.1` (10%) | -### Reduce OTLP Sampling -Lower sampling to avoid overwhelming storage and dashboards: - -```yaml -tracing: - sampleRate: 0.1 # 10% sampling in production -```` - -### Prefer gRPC over HTTP - -For lower latency and higher throughput, enable gRPC instead of HTTP: +Example (Traefik OTLP tracing): ```yaml tracing: otlp: grpc: - endpoint: "log-dashboard-backend:4317" + endpoint: "traefik-agent:5000" insecure: true + sampleRate: 0.1 ``` -### Tune Backend Memory - -Set environment variables in `log-dashboard-backend`: - -```yaml -environment: - - GOGC=20 # More aggressive garbage collection - - GOMEMLIMIT=1GiB # Hard memory limit -``` - -### Resource Limits - -Add CPU and memory constraints to containers: - -```yaml -deploy: - resources: - limits: - cpus: "1.0" - memory: 512M - reservations: - cpus: "0.2" - memory: 128M -``` - -These adjustments help keep the dashboard responsive while minimizing resource overhead. - - -## Troubleshooting - -* **OTLP not showing** β†’ Check Traefik `tracing` config + ports `4317/4318` -* **Logs not loading** β†’ Ensure Traefik logs in JSON, volume mounted correctly -* **GeoIP errors** β†’ Verify `MAXMIND_LICENSE_KEY` and DB path -* **Maxmind download errors** β†’ Check license key validity by trying url with key directly in your browser -* **Docker logs for Traefik not showing** β†’ Use `docker exec -it traefik tail -f /var/log/traefik/traefik.log` instead of `docker logs traefik -f` to see real-time logs on the command line. - --- +## Troubleshooting + +| Issue | Cause | Fix | +| --------------------- | ------------------------ | ------------------------------------------------------------------- | +| Dashboard not loading | Container not healthy | `docker compose ps` β†’ check `health` | +| No logs appearing | Wrong log path or format | Ensure `access.log` is JSON and volume mounted | +| GeoIP missing | Missing databases | Run `maxmind-updater` or mount both `.mmdb` files | +| Auth errors | Token mismatch | Verify `AGENT_API_TOKEN` matches `TRAEFIK_LOG_DASHBOARD_AUTH_TOKEN` | +| Slow UI | Large logs | Use JSON logs + incremental read; prune logs periodically | + +--- + +## Summary + +βœ… Replaces the old `log-dashboard-backend` + `log-dashboard-frontend` with the new **agent-based architecture** +βœ… Supports **multiple Traefik instances** +βœ… Adds **GeoLite2 Country + City databases** +βœ… Integrates **real-time analytics + system monitoring** +βœ… Uses **MaxMind license key** for authentication and updates + +--- + +**Project Repository** β†’ [https://github.com/hhftechnology/traefik-log-dashboard](https://github.com/hhftechnology/traefik-log-dashboard) +**Discord Community** β†’ [Join here](https://discord.gg/HDCt9MjyMJ) + +``` +