English | Deutsch

A professional, open-source monitoring tool for the continuous supervision of your internet quality – with PDF reports for ISP complaints, IP tracking and a DNS benchmark.

💡 Why SignalReport?
"My internet is slow!" is not enough for an ISP. With SignalReport you deliver verifiable, quantified evidence – not just a gut feeling.

📜 Project history
SignalReport was created between January and April 2026 as the final project of the diploma course "Software Developer" at WIFI Vienna (course 18195015) and has since been actively developed further as a personal open-source project. If you want to review the exact state at the time of the diploma examination, you can find it as release V1.

---

🌟 Features

Category	Functions
Monitoring	🔁 Continuous measurement (ping/DNS/HTTP + gateways) 🧪 The HTTP check rates the line, not the website: any server response counts as reachable, only timeouts and connection errors fail (the reason is logged) ⏱️ Configurable interval (5s–1h, default 30s) ⏸️ Maintenance window (router updates) 🌐 IP tracking (detect external IP changes)
Fault localisation & reliability	🛰️ Pinpoint router vs. internet gateway vs. ISP (traceroute gateway chain) 🐳 Virtual-gateway detection in VM/Docker 📈 Availability, coverage, MTBF & MTTR (gap-aware) 📉 Aggregated connection outages, individually excludable from the rating
Service reachability	🚫 Detects whether services (Facebook, Instagram, X, YouTube, WhatsApp, …) are reachable or blocked — distinguishing DNS / TCP / SNI / block-page filtering 🕒 Separate slow schedule (default 6 h), line-gated, off by default 📅 Per-service block/outage timeline in the PDF report
Visualisation	📊 Live charts with Chart.js 📋 Per-cycle measurement table (collapsible) 🌡️ Hourly heatmap (fed from the condensed hourly values) 🖥️ Web interface (responsive) 🔔 Browser push on outages / high latency
Reports	📄 PDF export (24h / 7 days / 12 months; ranges beyond 7 days are built from the hourly values and finish in seconds even with years of data) 📈 3 charts (PING/DNS/HTTP) with target-change markers 🏆 Top 10 worst measurements (worst hours in long reports) ⚠️ Connection-outage analysis 📤 CSV export: time range filtered, all raw data as ZIP (streamed), hourly values as CSV
Security	🔐 Setup wizard (web-based, no CLI) 🔑 Challenge-response authentication (SHA-256) 👥 Admin/user roles with session management 🛡️ Password is never transmitted in plaintext
Data safety	🛟 Twin database (mirrored writes) 🩺 Self-healing: a read that hits a corrupted page falls back to the twin and schedules a rebuild; the rebuild unites both files into a fresh, compact database (automatically at the next start, or on demand with dbrebuild.bat / dbrebuild.sh) ⚡ One transaction per measurement cycle, continuous H2 background compaction 🛑 Orderly stop (signalreport.jar stop, used by the Windows service) closes both databases cleanly
Data preparation	🗜️ Hourly condensation: count, min / average / median / 95th percentile / max and jitter per hour, type and target (measurement_hourly) 🧹 Retention: unremarkable raw measurements older than 90 days (configurable, 0 = never) are removed; failed measurements, the end of each outage, excluded measurements and maintenance markers are kept forever 🕒 Heavy steps only inside a time window (default 03:00–05:00, or the maintenance window); the light hourly step runs continuously; "Run now" button with progress and status in the settings 🧵 Runs on its own database connections with short pauses, so measurements and the web UI never wait behind it
Internationalisation	🌐 9 languages: Deutsch, English, Français, Italiano, Español, Português, Türkçe, Polski, Українська 🔤 Applies to web UI, PDF reports and CSV exports 🎛️ Language choice in the setup wizard and in the settings 📂 Extensible without recompiling: drop your own language file into ./lang/
Configuration	⚙️ Dynamic measurement targets (ping/DNS/HTTP) 🌍 DNS benchmark (servers worldwide) 👤 User info (provider/customer number for reports)

---

🚀 Quick start

Requirements

• Java 21 or higher (download)
• (Optional) Maven to build from source

Installation & start

# 1. Download the JAR (or build with Maven: mvn clean package)
java -jar signalreport.jar

# 2. Open the browser
http://localhost:4567

# 3. Run through the setup wizard (set an admin password)

✅ Done! Measurement starts automatically – by default ping, DNS and HTTP (and the gateways, if set) are tested every 30 seconds.

---

📦 Installation as a service

For continuous operation (even without a logged-in user) SignalReport can be installed as a background service.

Windows

1. Download and unpack signalreport_windows.zip
2. Right-click install.bat → "Run as administrator"
3. The script installs the service, creates a desktop shortcut and sets up the firewall

macOS / Linux

1. Download and unpack signalreport_mac-linux.zip
2. Open a terminal and run: sudo bash install.sh
3. The service is set up as a systemd service (Linux) or launchd service (macOS)

💡 The signalreport.jar must be located in the same directory as the installation scripts.

🔄 Install or update: the script detects an existing installation and then only replaces the JAR (stop → swap → start) — your data and config.json are preserved. To update, just drop the new signalreport.jar next to the script and run it again.

Uninstallation

• Windows: right-click uninstall.bat → run as administrator
• macOS/Linux: sudo bash uninstall.sh (in the terminal)

The uninstaller asks what to keep: nothing, the configuration (config.json), the database (your collected measurements), or both.

Database rebuild (repair and compaction)

• Windows: right-click dbrebuild.bat → run as administrator
• macOS/Linux: sudo bash dbrebuild.sh (in the terminal)

Stops the service, rebuilds the database from primary and shadow into a fresh, compact file (union of both, day by day; a page that is unreadable in one file is covered by the other), moves the old files to data/quarantine/rebuild_<time>/ and starts the service again. A report is written to data/signalreport_rebuild-report_<time>.txt. SignalReport also does this on its own at the next start when a read hits a corrupted page during operation.

Data preparation (hourly values and retention)

Once an hour is over, SignalReport condenses its raw measurements into hourly values and uses them for the heatmap, for reports longer than 7 days and for the hourly CSV export. Raw measurements that are older than the retention period (default 90 days) and unremarkable (successful, following a successful one) are deleted; every failed measurement, the end of each outage, excluded measurements and maintenance markers stay forever. The heavy steps (catching up on history, deleting) only run inside the configured time window – by default 03:00–05:00, optionally the maintenance window. Everything is set in the settings card "Data preparation", which also shows the current state and offers "Run now" (5-minute cooldown). After an update from an older version the first run condenses the whole history; with months of data this takes a while and simply continues in the next window if it does not finish.

---

📸 Screenshots

Web interface	PDF report (excerpt)	DNS benchmark
Live charts, statistics, settings	Professional report for ISPs	Comparison of global DNS servers

---

⚙️ Configuration

After the first start a config.json is created. Important settings:

{
  "language": "en",
  "measurement": {
    "intervalSeconds": 30,
    "targets": {
      "ping": "8.8.8.8",
      "dns": "google.com",
      "http": "https://example.com"
    }
  },
  "maintenanceWindow": {
    "enabled": true,
    "startHour": 4,
    "startMinute": 0,
    "endHour": 4,
    "endMinute": 10
  },
  "userInfo": {
    "provider": "Oranga",
    "customerId": "08154711",
    "userName": "Matthias F."
  }
}

💡 Tip: Changes made via the web interface (tab ⚙️ Settings) are applied and persisted immediately!

🛰️ Fault localization & virtual gateways

For fault localization (your own router vs. provider), SignalReport runs a traceroute at startup to find the nearest router and the gateway to the internet. When SignalReport runs inside a VM or container, the detected "router" may be a virtual NAT device rather than your real hardware:

• The Docker default bridge (172.17.0.0/16) is skipped automatically when the real router is visible as the next hop behind it.
• VirtualBox/QEMU NAT (10.0.2.0/24) and Docker bridges inside a container are recognised as virtual → a warning appears in the ⚙️ Settings tab under Gateways.
• VMware NAT (192.168.x.2) and similar NATs in real home-network ranges cannot be told apart from a genuine router by IP, so they are deliberately not flagged automatically (to avoid false alarms).

Fix in such cases: in the ⚙️ Settings tab under Gateways, set the real router IP manually, or enable "do not ping continuously" for the internet gateway. Manually set IPs can optionally be kept across an IP change.

---

🌐 Internationalisation

SignalReport is fully multilingual – web interface, PDF reports and CSV exports. 9 languages are bundled:

🇩🇪 Deutsch · 🇬🇧 English · 🇫🇷 Français · 🇮🇹 Italiano · 🇪🇸 Español · 🇵🇹 Português · 🇹🇷 Türkçe · 🇵🇱 Polski · 🇺🇦 Українська

• Switching: in the setup wizard (before setting the password) or any time in the ⚙️ Settings tab
• Default: fresh installations adopt the system language (otherwise English); existing installations stay on German
• Add your own language (without recompiling): place a <code>.json file (e.g. nl.json) modelled on de.json into a lang/ folder next to signalreport.jar – it appears in the language dropdown automatically
• Unicode in the PDF: the DejaVu font is embedded, so Turkish, Polish and Cyrillic script (Ukrainian) are rendered correctly too

---

📊 PDF report – perfect for ISP complaints

The 12-month report contains:

• ✅ Your customer data (name, provider, customer number)
• ✅ Host information (hostname, hash, IPs)
• ✅ 3 charts with red lines at target changes
• ✅ Chronological list of the measured targets
• ✅ Top 10 worst measurements (with timestamp)
• ✅ Top 10 longest connection outages
• ✅ Total number of outages

📌 How to use the report:

1. Generate the PDF via "📄 PDF report (12 months)"
2. Save it as signalreport-providername-complaint-2026-03-25.pdf
3. Attach it to a support email with text such as:
   "Attached is the technical evidence of repeated connection problems in the period XX to YY. Please check the line to my connection."

---

🏗️ Project structure

A compact overview of the directories and classes is available in docs/ProjectStructure.md; the architecture is described in docs/Architecture.md.

signalreport/
├── src/main/java/at/mafue/signalreport/
│   ├── SignalReportApp.java              # Main class (entry point, measurement loop, orderly stop)
│   ├── StopCommand.java                  # "signalreport.jar stop": asks the running instance to shut down cleanly
│   ├── RebuildCommand.java               # "signalreport.jar rebuild-db": rebuilds the database from primary + shadow
│   ├── ServiceReachabilityScheduler.java # Slow service-reachability loop + line-gate
│   ├── DataPrepScheduler.java            # Data preparation in the background: hourly condensation, backlog + retention inside the time window
│   ├── config/                           # Slim Config + one file per area (Measurement, Gateway, ServiceReachability, DataPrep, …)
│   ├── measurement/                      # Measurer interface + Ping/Dns/Http, Measurement, DnsBenchmark
│   ├── network/                          # GatewayDiscovery (traceroute), ServiceReachabilityProbe, NetworkInfo, HostIdentifier
│   ├── storage/                          # H2MeasurementRepository (twin DB, shadow fallback), RollupService (hourly values + retention), DatabaseRebuilder + DTOs
│   ├── report/                           # ReliabilityReport, ConnectivityAssessment, ServiceReachabilityAssessment/Report, PdfReportGenerator
│   ├── web/                              # WebServer (Javalin orchestrator), SessionManager
│   │   ├── view/                         #   HtmlPageRenderer, SetupPageRenderer, LoginPageRenderer
│   │   └── api/                          #   12 route registrars (Measurement, Reliability, ServiceReachability, Settings, DataPrep, System, …)
│   ├── i18n/                             # I18n (9 languages, extensible)
│   └── notification/                     # PushNotificationService
├── src/test/java/at/mafue/signalreport/  # 29 test classes, 210 tests (mirror the packages above)
├── src/main/resources/web/               # Static assets: app.css, app.js, logos, favicons
├── src/main/resources/lang/              # Language files (de, en, fr, it, es, pt, tr, pl, uk)
├── src/main/resources/fonts/             # DejaVu fonts for the PDF (Unicode/Cyrillic)
├── docs/
│   ├── diagrams/                         # PlantUML diagrams (.puml + .png)
│   ├── latex/                            # Full LaTeX documentation
│   └── screenshots/                      # UI screenshots
├── deployment/                           # Install/update, uninstall and database-rebuild scripts (Win/Linux/macOS)
├── config.json                           # Auto-generated configuration
├── data/                                 # H2 twin database: primary + shadow (gitignored)
│   └── quarantine/                       # Corrupt DB files kept for analysis
├── pom.xml                               # Maven build configuration
└── README.md                             # This file (German version: README_de.md)

---

📚 Documentation

• Full LaTeX documentation as PDF: signalreport-dokumentation.pdf Contains UML diagrams, architecture description, implementation details and the test report. (Document language: German.)
• Architecture overview: docs/Architecture.md
• Project structure: docs/ProjectStructure.md
• UML diagrams: all 7 diagrams as PNG and PlantUML in docs/diagrams/:
  • class-diagram.png – class structure
  • component-diagram.png – component overview
  • sequence-measurement.png – measurement flow
  • sequence-pdf.png – PDF export process
  • usecase-diagram.png – use cases
  • deployment-diagram.png – deployment scenarios
  • state-diagram-auth.png – authentication states

---

🔒 Security notes

• Challenge-response auth: passwords are never transmitted in plaintext – SHA-256 with single-use nonces
• Session management: 24h session timeout, secure cookie-based authentication
• Authentication: for public IPs (e.g. a NAS with port forwarding) make sure to enable it (tab 🔐 Security)
• Setup password: the admin password is set on first start – never leave default values!
• Database: all data stored locally in a crash-resistant twin database (primary + shadow). No cloud dependency, no external APIs (except ipify.org for the external IP)

---

🤝 Contributing

SignalReport is open source! You can:

• 🐛 Report bugs (issues)
• 💡 Suggest new features
• 📝 Improve the documentation
• 🌍 Contribute translations (a new lang/<code>.json modelled on de.json)

---

📜 License

MIT License – see the LICENSE file.
Free to use for private and commercial purposes – with attribution.

---

🙏 Acknowledgements

This project uses great open-source libraries and services:

Backend libraries (Maven/Java):

• Javalin – lightweight web framework
• H2 Database – embedded SQL database
• Jackson – JSON serialisation (config, API)
• OpenPDF – PDF creation
• JFreeChart – chart generation for PDF reports
• dnsjava – DNS queries for the benchmark
• SLF4J + Logback – logging
• JUnit 5 – test framework

Frontend (browser):

• Chart.js – live charts in the web interface (via CDN)
• Web Crypto API – client-side SHA-256 hashing for challenge-response auth

Fonts:

• DejaVu Fonts – embedded Unicode font for PDF reports (Latin, Latin Extended, Cyrillic)

External services:

• ipify.org – discovery of the external IP address

Build & deployment:

• Apache Maven – build system
• Apache Commons Daemon – service installation (procrun/jsvc)

Documentation & development:

• PlantUML – UML diagrams
• LaTeX – project documentation
• EmojiTerra – emoji reference
• StackOverflow – Q&A platform for software developers
• Hitchhiker’s Guide to PlantUML – nomen est omen

My thanks also go to:

• Christian Schäfer – Java course and project coaching
• Serap Kadam – support, friendship, everything around Java
• [Angelika Winder] – support in all situations of life (except with Java)

---

📮 Contact & support

For questions about the project or technical details, feel free to open an issue on GitHub.

---

🌐 SignalReport
Built with ❤️ for everyone who wants to know how stable their internet connection really is.