{"id":39955850,"url":"https://github.com/k0lin/loglynx","last_synced_at":"2026-02-22T15:29:32.084Z","repository":{"id":324410781,"uuid":"1088995281","full_name":"K0lin/loglynx","owner":"K0lin","description":"LogLynx: Advanced log analytics platform for Traefik reverse proxy. Real-time monitoring, geographic insights, performance tracking, device analytics, and comprehensive REST API. Built with Go.","archived":false,"fork":false,"pushed_at":"2026-01-12T19:01:17.000Z","size":1136,"stargazers_count":69,"open_issues_count":0,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-13T00:38:17.330Z","etag":null,"topics":["access-logs","dashboard","golang","log-analytics","monitoring","real-time","rest-api","reverse-proxy","traefik"],"latest_commit_sha":null,"homepage":"https://hub.docker.com/r/k0lin/loglynx","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/K0lin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-03T18:34:36.000Z","updated_at":"2026-01-09T20:56:45.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/K0lin/loglynx","commit_stats":null,"previous_names":["k0lin/loglynx"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/K0lin/loglynx","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/K0lin%2Floglynx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/K0lin%2Floglynx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/K0lin%2Floglynx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/K0lin%2Floglynx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/K0lin","download_url":"https://codeload.github.com/K0lin/loglynx/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/K0lin%2Floglynx/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28550463,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-18T20:59:07.572Z","status":"ssl_error","status_checked_at":"2026-01-18T20:59:02.799Z","response_time":98,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["access-logs","dashboard","golang","log-analytics","monitoring","real-time","rest-api","reverse-proxy","traefik"],"created_at":"2026-01-18T21:00:27.549Z","updated_at":"2026-01-18T21:00:39.646Z","avatar_url":"https://github.com/K0lin.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# LogLynx ⚡\r\n\r\n**Advanced Log Analytics Platform for Traefik, Caddy, and Beyond**\r\n\r\nLogLynx is a high-performance (less than 50 MB of RAM), real-time log analytics platform designed to provide deep insights into your web traffic. Built with Go and optimized for reverse proxy logs (Traefik and Caddy), it offers a beautiful dark-themed dashboard and comprehensive REST API.\r\n\r\n![License](https://img.shields.io/badge/license-MIT-blue.svg)\r\n![Go Version](https://img.shields.io/badge/go-%3E%3D1.21-blue.svg)\r\n![Status](https://img.shields.io/badge/status-active-success.svg)\r\n\r\n\u003e **📚 Important Documentation**\r\n\u003e\r\n\u003e - **[Traefik Setup Guide](../../wiki/Traefik)** - Recommended Traefik configuration for optimal LogLynx performance and complete field capture (for the [pangolin quick installation](https://docs.pangolin.net/self-host/quick-install) no additional configuration is required for Traefik).\r\n\u003e - **[Caddy Setup Guide](../../wiki/Caddy)** - Caddy configuration for JSON access log format with LogLynx\r\n\u003e - **[Deduplication System](../../wiki/Deduplication-System)** - Learn how LogLynx prevents duplicate log entries and handles various scenarios (log rotation, crashes, re-imports)\r\n\r\n\u003cimg width=\"1920\" height=\"1080\" alt=\"LogLynx-Overview-Demo\" src=\"img/LogLynx-Overview-Demo.png\" /\u003e\r\n\r\n## ✨ Features\r\n\r\n- 📊 **Real-time Analytics** - Live metrics with Server-Sent Events (SSE)\r\n- 🗺️ **Geographic Insights** - Interactive maps with traffic visualization\r\n- 📈 **Timeline Analysis** - Hourly, daily, and custom time ranges\r\n- 🔍 **Deep Filtering** - Filter by service, backend, or domain\r\n- 🚀 **High Performance** - Optimized batch processing and SQLite backend\r\n- 🎨 **Beautiful UI** - Dark-themed responsive dashboard\r\n- 🔌 **REST API** - Full-featured API for integrations\r\n- 📱 **Device Analytics** - Browser, OS, and device type detection\r\n- 🌐 **GeoIP Enrichment** - Country, city, and ASN information\r\n- 🔄 **Auto-Discovery** - Automatically detects Traefik and Caddy log files\r\n- 🔌 **Multi-Parser Support** - Works with Traefik and Caddy reverse proxy logs\r\n\r\n## 🚀 Quick Start\r\n\r\n### Prerequisites\r\n\r\n- Go 1.25 or higher\r\n- Traefik or Caddy access logs (optional for initial setup)\r\n\r\n### Standalone installation\r\n\r\n```bash\r\n# Clone the repository\r\ngit clone https://github.com/k0lin/loglynx.git\r\ncd loglynx\r\n\r\n# Customize your installation (None of these parameters are mandatory, but customization for your system is recommended.)\r\ncp .env.example .env\r\n\r\n# Install dependencies\r\ngo mod tidy\r\n```\r\n#### Now there are two deployment methods:\r\nCreating the binary to be executed\r\n```bash\r\n# Build\r\ngo build -o loglynx cmd/server/main.go\r\n\r\n# Start the server\r\n./loglynx\r\n```\r\nRun the service directly without creating the binary\r\n```bash\r\n# Build and run\r\ngo run cmd/server/main.go\r\n\r\n```\r\n\r\n### Deployment with docker compose on standard pangolin installation\r\nThis should be your pangolin installation in broad terms if you used the installer from the official documentation.\r\n```\r\nyour-folder/\r\n├── config/                    # Pangolin configuration\r\n│   └── traefik/ \r\n│   │  └── logs/\r\n│   │     └── access.log       # Traefik access log\r\n│   ├── logs/       \r\n│   ├── letsencrypt/     \r\n│   ├── db/      \r\n│   ├── config.yml\r\n│   ├── GeoLite2-City.mmdb     # optional\r\n│   ├── GeoLite2-ASN.mmdb      # optional\r\n│   └── GeoLite2-Country.mmdb  # optional\r\n├── loglynx-data/                      # database for loglynx service   \r\n├── GeoLite2-Country_20251024/ # MaxMind license\r\n└──  docker-compose.yml \r\n```\r\nThis is the deployment of Docker Compose, which will also contain services such as Pangolin, Traefik, etc. The example configuration is set up using the Pangolin configuration described above.\r\n```yml\r\n#other service related to pangolin\r\n\r\nloglynx:\r\n    image: k0lin/loglynx:latest\r\n    container_name: loglynx\r\n    restart: unless-stopped\r\n    ports:\r\n      - \"8080:8080\"\r\n    volumes:\r\n      - ./loglynx-data:/data\r\n      - ./config:/app/geoip                 \r\n      - ./config/traefik/logs:/traefik/logs\r\n    environment:\r\n      - DB_PATH=/data/loglynx.db\r\n      - GEOIP_ENABLED=true  #if the geolite database are installed\r\n      - GEOIP_CITY_DB=/app/geoip/GeoLite2-City.mmdb  #only if GEOIP_ENABLED is set to true, It is not mandatory to set all three, even just one is fine (obviously it will work with limited functionality)\r\n      - GEOIP_COUNTRY_DB=/app/geoip/GeoLite2-Country.mmdb  #(only if GEOIP_ENABLED is set to true), It is not mandatory to set all three, even just one is fine (obviously it will work with limited functionality)\r\n      - GEOIP_ASN_DB=/app/geoip/GeoLite2-ASN.mmdb  #(only if GEOIP_ENABLED is set to true), It is not mandatory to set all three, even just one is fine (obviously it will work with limited functionality)\r\n      - TRAEFIK_LOG_PATH=/traefik/logs/access.log\r\n      - LOG_LEVEL=info\r\n      - SERVER_PRODUCTION=true\r\n      # There are several configurable environment variables to optimize program startup (check the wiki).\r\n```\r\n\r\nThe dashboard will be available at `http://localhost:8080`\r\n\r\n## 📊 Dashboard\r\n\r\nAccess the web interface at `http://localhost:8080` to explore:\r\n\r\n- **Overview** - Executive summary with key metrics\r\n- **Real-time Monitor** - Live traffic monitoring\r\n- **Traffic Analysis** - Patterns and trends over time\r\n- **Geographic Analytics** - Interactive world map\r\n- **Performance** - Response times and backend health\r\n- **Security \u0026 Network** - IP analysis, ASN tracking, TLS versions\r\n- **User Analytics** - Browsers, OS, device types, referrers\r\n- **Content Analytics** - Top paths and referrers\r\n- **Backend Health** - Service performance monitoring\r\n\r\n## 🔌 API Usage\r\n\r\nLogLynx provides a comprehensive REST API for programmatic access to all analytics.\r\n\r\n### API-Only Mode\r\n\r\nYou can disable the dashboard UI and run LogLynx in API-only mode by setting:\r\n\r\n```bash\r\nDASHBOARD_ENABLED=false\r\n```\r\n\r\nWhen dashboard is disabled:\r\n- All `/api/v1/*` endpoints remain fully accessible\r\n- `/health` endpoint continues to work for health checks\r\n- Dashboard routes (`/`, `/traffic`, etc.) are not exposed\r\n- Static assets are not loaded, reducing memory footprint\r\n\r\n### OpenAPI Specification\r\n\r\nFull API documentation is available in `openapi.yaml`. View it with:\r\n\r\n- [Swagger Editor](https://editor.swagger.io/) - Paste the content\r\n- [Swagger UI](https://petstore.swagger.io/) - Import the file\r\n- Generate clients: `npx @openapitools/openapi-generator-cli generate -i openapi.yaml -g python`\r\n\r\nSee the [API Wiki](../../wiki/API-Documentation) for detailed examples and use cases.\r\n\r\n## 🛠️ Configuration\r\n\r\n### Environment Variables\r\n\r\n```bash\r\n# ================================\r\n# GeoIP Configuration\r\n# ================================\r\n# Download GeoIP databases from MaxMind:\r\n# https://dev.maxmind.com/geoip/geolite2-free-geolocation-data\r\n\r\nGEOIP_ENABLED=true\r\nGEOIP_CITY_DB=geoip/GeoLite2-City.mmdb\r\nGEOIP_COUNTRY_DB=geoip/GeoLite2-Country.mmdb\r\nGEOIP_ASN_DB=geoip/GeoLite2-ASN.mmdb\r\n\r\n# ================================\r\n# Log Sources Configuration\r\n# ================================\r\n# Path to Traefik access log file\r\nTRAEFIK_LOG_PATH=traefik/logs/access.log\r\n\r\n# Path to Caddy access log file (JSON format)\r\nCADDY_LOG_PATH=caddy/logs/access.log\r\n\r\n# Auto-discovery of log files (default: true)\r\nLOG_AUTO_DISCOVER=true\r\n```\r\n\r\n\r\n### GeoIP databases\r\n\r\nSome community projects (for example, [`P3TERX/GeoLite.mmdb`](https://github.com/P3TERX/GeoLite.mmdb)) provide convenient downloads of GeoLite2 City/Country/ASN files. LogLynx does not ship GeoIP databases and is not responsible for third-party downloads.\r\n\r\nIf you use third-party downloaders, please ensure you comply with MaxMind's license and, when required, register and accept the license on the official MaxMind site: [MaxMind GeoLite2](https://dev.maxmind.com/geoip/geolite2-free-geolocation-data).\r\n\r\nTo use GeoIP with LogLynx, place the `.mmdb` files in a directory and mount that directory into the container at the paths configured by `GEOIP_CITY_DB`, `GEOIP_COUNTRY_DB` and `GEOIP_ASN_DB`.\r\n\r\n\r\n### Traefik Log Format\r\n\r\nLogLynx works best with Traefik's default access log format. Ensure Traefik is configured with:\r\n\r\n```yaml\r\naccessLog:\r\n  filePath: \"/var/log/traefik/access.log\"\r\n  format: json  # JSON format recommended\r\n```\r\n\r\n### Caddy Log Format\r\n\r\nLogLynx requires Caddy's JSON access log format. Configure Caddy with:\r\n\r\n```caddyfile\r\n{\r\n    log {\r\n        output file /var/log/caddy/access.log\r\n        format json\r\n        level INFO\r\n    }\r\n}\r\n\r\n# Or per-site configuration:\r\nexample.com {\r\n    log {\r\n        output file /var/log/caddy/access.log\r\n        format json\r\n    }\r\n    reverse_proxy localhost:8080\r\n}\r\n```\r\n\r\n**Important Notes for Caddy:**\r\n- JSON format is **required** (default CLF/common log format is not supported)\r\n- Cookie headers are stored as-is - configure redaction in Caddy if needed\r\n- LogLynx automatically extracts client IP from `client_ip`, `remote_ip`, or `X-Forwarded-For`\r\n- TLS information (version, cipher suite) is automatically converted from numeric codes\r\n\r\n## 📦 Project Structure\r\n\r\n```\r\nloglynx/\r\n├── cmd/server/          # Application entry point\r\n├── internal/\r\n│   ├── api/            # HTTP server and handlers\r\n│   ├── database/       # Database models and repositories\r\n│   ├── discovery/      # Log file auto-discovery\r\n│   ├── enrichment/     # GeoIP enrichment\r\n│   ├── ingestion/      # Log file processing\r\n│   ├── parser/         # Log format parsers (Traefik, Caddy)\r\n│   └── realtime/       # Real-time metrics\r\n├── web/\r\n│   ├── static/         # CSS, JavaScript, images\r\n│   └── templates/      # HTML templates\r\n├── openapi.yaml        # API specification\r\n└── README.md\r\n```\r\n\r\n## 🔒 Features in Detail\r\n\r\n### Resilient Startup\r\n- ✅ Starts successfully even without log files\r\n- ✅ Automatic retry with clear error messages\r\n- ✅ Graceful handling of permission errors\r\n- ✅ Runs in standby mode until logs are available\r\n\r\n### Real-time Monitoring\r\n- Live metrics updated every second\r\n- Server-Sent Events (SSE) streaming\r\n- Per-service breakdown\r\n- Active connections and error rates\r\n\r\n### Geographic Analytics\r\n- Interactive Leaflet map with clustering\r\n- Country, city, and coordinate data\r\n- ASN (Autonomous System) tracking\r\n- Dark-themed map styling\r\n\r\n### Performance Tracking\r\n- Response time percentiles (P50, P95, P99)\r\n- Backend health monitoring\r\n- Bandwidth analysis\r\n- Request rate tracking\r\n\r\n## 🤝 Contributing\r\n\r\nContributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.\r\n\r\n## 📝 License\r\n\r\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\r\n\r\n## 🙏 Acknowledgments\r\n\r\n- [Traefik](https://traefik.io/) - Modern HTTP reverse proxy\r\n- [Caddy](https://caddyserver.com/) - Fast and extensible multi-platform HTTP server\r\n- [MaxMind GeoLite2](https://dev.maxmind.com/geoip/geolite2-free-geolocation-data) - GeoIP databases\r\n- [DataTables](https://datatables.net/) - Table plugin for jQuery\r\n- [Chart.js](https://www.chartjs.org/) - JavaScript charting\r\n- [Leaflet](https://leafletjs.com/) - Interactive maps\r\n\r\n## 💬 Support\r\n\r\n- 🐛 [Report Issues](../../issues)\r\n- 💡 [Feature Requests](../../issues/new?labels=enhancement)\r\n- 📖 [Documentation Wiki](../../wiki)\r\n\r\n---\r\n\r\n\r\n**Made with ❤️ for the community**\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fk0lin%2Floglynx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fk0lin%2Floglynx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fk0lin%2Floglynx/lists"}