Installation
The application ships as a single Windows installer (MatrixIT-PacketLossMonitor-Setup.exe). No .NET runtime is needed — it is bundled inside the installer. The entire setup takes under 2 minutes.
-
Run the installer as Administrator Double-click
MatrixIT-PacketLossMonitor-Setup.exe. Accept the Windows UAC prompt when it appears. The installer does not require an internet connection. -
Choose optional tasks The installer offers checkboxes for:
- Create a Desktop shortcut (current user or all users)
- Create a Start Menu shortcut
- Launch at Windows startup (adds a registry Run entry)
-
Installation completes Files are placed in
C:\Program Files\Matrix IT\Packet Loss Monitor\. The Windows serviceMatrixITPktMonis registered automatically. The application launches at the end. -
First-run configuration opens automatically Since no
config.jsonexists yet, the app navigates directly to Settings. See the next section.
C:\packetmonitor\ — not in Program Files. This path is writable by the Windows service (running as SYSTEM) and shared between the GUI and service.
First-Run Setup
On first launch, the app opens directly on the Settings screen. The dashboard shows an amber "Setup required" banner until all three requirements are met: SMTP credentials, at least one monitoring target, and at least one alert recipient.
Step 1 — Add Monitoring Targets
Click + Add Target for each network device you want to monitor.
| Field | Example | Notes |
|---|---|---|
| Name | Core-SW-01 | Friendly display name shown on dashboard cards |
| Host / IP | 192.168.1.10 | IP address or hostname that responds to ICMP ping |
| Description | Core switch, IDF room | Optional subtitle shown on the card |
| Latency Threshold (ms) | 10 | 5–15 ms for LAN; 50–150 ms for WAN. Overrides the global threshold for this target only. |
Step 2 — Configure SMTP Mail Server
Enter your SMTP relay credentials. The app uses port 587 with STARTTLS by default. After entering credentials, enter a test recipient address and click Send Test Email — no need to save first. A green ✓ or detailed error message appears immediately.
Step 3 — Add Alert Recipients
Add each email address that should receive alert notifications. One address per line. All recipients receive every alert email.
Step 4 — Save Settings
Click Save Settings. Monitoring starts automatically. Navigate to Dashboard to see your targets.
Dashboard Overview
The Dashboard is the primary screen. It is divided into two columns. The left column shows the live target card grid. The right column shows either the Recent Alerts feed (default) or a full Target Detail analytics panel when a card is clicked.
Health Summary Bar
A compact strip directly above the target cards shows real-time counts across all targets at a glance:
Each count updates instantly whenever any target changes status — no manual refresh needed. This is the fastest way to assess network health without reading individual cards.
Target Cards
Each monitored target is displayed as a card in the left column. Cards are automatically sorted by severity — ALERT cards float to the top, followed by WARNING, then OK. You never need to scroll to find a problem.
Click any card to open the Target Detail Panel in the right column.
Card Layout
| Area | Contents |
|---|---|
| Status icon (left) | Coloured circle matching current status. Card background also changes colour. |
| Target info (centre-left) | Name, IP/hostname, optional description, last check timestamp (HH:mm:ss) |
| Packet Loss (centre) | Current loss % in large text, colour-coded green → amber → red |
| Latency (centre-right) | Average latency with a trend arrow. Shows No resp since HH:mm when loss is 100%. |
| Status column (right) | Status badge, alert reason, alert duration, alerts sent count, UNSTABLE badge (if flapping), RECON spinner (while diagnostics run) |
Status & Alert Badges
Status Indicators
| Badge | Meaning |
|---|---|
| ● OK | Zero packet loss, latency within the per-target threshold. All is healthy. |
| ▲ WARNING | Some packet loss detected but below the configured alert threshold. Worth watching. |
| ✖ ALERT | Threshold breached. Recon diagnostics have run or are running. Alert email sent (subject to cooldown). |
| ○ UNKNOWN | Not yet checked since the application started. Clears after the first completed ping cycle. |
Alert Reason Badges
When a target is in ALERT, a second smaller badge appears immediately below the ALERT badge explaining exactly why the alert fired — so you know at a glance whether to investigate latency or packet loss first.
| Reason Badge | Cause | Where to Look First |
|---|---|---|
| HIGH LATENCY | Average latency exceeded the per-target ms threshold. Zero or low packet loss. | Path quality, bandwidth saturation, QoS issues, WAN congestion |
| PACKET LOSS | Packet loss % exceeded the threshold. Latency may be within range. | Physical layer (cable, SFP), interface errors, duplex mismatch |
| LOSS + LATENCY | Both loss and latency thresholds were simultaneously breached. | Severe congestion, major hardware failure, ISP outage |
Trend Arrows, Flapping & Alert Duration
Trend Arrows
A small arrow next to the latency value compares the average of the last 5 ping cycles against the prior 5 to show whether performance is improving or degrading:
| Arrow | Meaning | Action |
|---|---|---|
| ↑ (amber) | Latency increasing — degrading by >10% | Watch closely; may reach ALERT if trend continues |
| ↓ (green) | Latency decreasing — improving by >10% | Good sign, likely recovering from a prior event |
| → (grey) | Stable — within ±10% of prior average | Normal operation |
| (none) | Not enough data yet (fewer than 10 completed checks) | Wait for more data |
Flapping / UNSTABLE Badge
If a target changes status 3 or more times within the last 10 checks, an UNSTABLE badge appears on the card. This indicates intermittent or oscillating connectivity — often more difficult to diagnose than a clean sustained outage.
Alert Duration Timer
Once a target enters ALERT, a running timer appears on the card below the alerts count: ongoing 4 min, ongoing 2h 15m, etc. This updates every 30 seconds and resets when the target returns to OK or WARNING — useful for quickly answering "how long has this been broken?"
Target Detail Panel
Click any target card to open the full analytics panel in the right column. This is your primary investigation tool when a target is degraded. Click ← Back to return to the Recent Alerts feed.
Stats Bar
| Metric | How It's Calculated | What to Look For |
|---|---|---|
| JITTER | Max latency − Min latency across the rolling 2-hour window | High jitter (e.g. >50 ms on a LAN target) indicates unstable routing or congestion even if average looks acceptable |
| AVAILABILITY | % of checks in the window that were NOT in ALERT status | Drops below 95%? The target has been unreliable for a significant portion of the observation window |
| CHECKS | Number of completed ping cycles in the buffer (max 120) | Low number means the app recently started or the target was just added — analytics are less representative |
| THRESHOLD | The configured per-target latency limit in ms | Reference — alerts fire when avg latency exceeds this value |
Latency Trend Chart
A canvas-drawn line chart showing average latency over time across the rolling 2-hour buffer. Features:
- Blue polyline with soft fill — each data point is one completed ping cycle
- Amber dashed horizontal line at the configured per-target latency threshold
- Grid lines at 25%, 50%, 75% of the current Y-axis scale
- Labels: Older (left) / Latest (right) on the X axis; max ms value top-right
- Redraws automatically after every ping cycle — no manual refresh
Packet Loss Heat Strip
A horizontal row of up to 120 colour-coded cells — one cell per completed ping cycle — reading left (oldest) to right (newest). The colour of each cell represents loss for that individual check:
Last Diagnostic Run
Shows the output from the most recent automatic or manually triggered recon. This section only appears after at least one recon has completed. Each diagnostic tool is in a collapsible expander:
| Section | What to Look For |
|---|---|
| PORT PROBES | Green OPEN / grey CLOSED badges for ports 22, 23, 80, 443, 8080. If ICMP is dropping but ports are OPEN, the device is up but routing is degraded — not a total failure. |
| Traceroute | Look for the hop where latency spikes or asterisks (*) appear consistently. That hop or the one before it is likely the problem segment. |
| Pathping | Per-hop loss % over 50 packets. A hop showing 40% loss while downstream hops show 0% = that router is rate-limiting ICMP (normal). A hop showing 40% loss AND all downstream hops showing similar loss = that hop is genuinely dropping packets. |
| ARP Table | Look for the same IP mapped to two different MAC addresses — this indicates a duplicate IP conflict that causes intermittent loss as traffic flips between the two devices. |
| NSLookup | Confirms DNS is resolving correctly. Failure here means the monitoring machine's DNS is unhealthy — separate from the target itself. |
Force Recon Button
Click ⊙ Force Recon in the panel header to immediately run a full diagnostic sweep on this target — no threshold breach required. Useful when you want to investigate a target that's currently showing high latency but hasn't yet crossed the alert threshold, or when you want fresh diagnostics during an incident.
Compare Targets
Click ⊞ Compare Targets in the Dashboard header to open the multi-target comparison window. It opens as a separate floating window so you can continue using the main dashboard while comparing.
How to Use It
-
Select targets using the checkboxes in the left sidebar Each target is assigned a unique colour from an 8-tone palette. That colour carries through all panels — chart lines, loss strips, and table headers — so you always know which data belongs to which target.
-
Read the overlaid latency chart All selected targets are drawn on a single canvas with a shared Y-axis. If two lines spike at the same horizontal position, both targets degraded at the same time.
-
Read the stacked loss strips One heat strip per selected target, stacked vertically. Red blocks aligned across multiple strips = simultaneous degradation = likely a shared upstream problem.
-
Check the Correlation Banner The banner at the top scores simultaneous degradation between every pair of selected targets and shows the highest-scoring pair with an advisory message.
Correlation Score Guide
| Score | Interpretation | Recommended Action |
|---|---|---|
| ≥ 70% — High | Both targets degrade at the same time in most checks — very likely a shared upstream path (ISP link, core router, WAN circuit) | Investigate the common path segment: run tracert on both targets and compare where the hops diverge |
| 35–70% — Moderate | Partial overlap — may be related or coincidental | Monitor during the next degradation window. Check if the affected checks occur at the same time of day. |
| < 35% — Low | Targets fail independently — the problem is device-specific | Investigate each device separately. Physical layer checks recommended for the affected target. |
Recent Alerts Feed
The right column of the Dashboard shows the Recent Alerts feed when no target card is selected. It displays the 10 most recent alert events as compact single-line entries, newest at the top.
Alert Entry Format
PACKET LOSS google dns · 50% · 11:23
LOSS + LATENCY gateway · 15% · 18 ms · 11:24
| Element | Description |
|---|---|
| Type badge | Amber for HIGH LATENCY; red for PACKET LOSS or LOSS + LATENCY |
| Target name | Friendly display name of the affected target |
| Metric | The actual value that triggered the alert (e.g. 24 ms or 50%). Shows both values for LOSS + LATENCY. |
| Time | HH:mm timestamp of the alert event |
Click View all in History → at the bottom of the feed to navigate to the full History screen, which shows all saved events from history.csv.
History View
Navigate to History from the top menu bar to view the complete persistent event log stored in C:\packetmonitor\history.csv. Unlike the Recent Alerts feed, history persists across app restarts.
What's Recorded
Every completed ping cycle writes one row per target to history.csv:
Using the History Screen
- Per-target summary statistics: total checks, OK / WARNING / ALERT counts, average and peak loss, average and peak latency
- Sortable event table — click column headers to sort
- Filter to show all events or ALERT / WARNING events only
- The
AlertSentcolumn shows whether an email was dispatched for that particular breach (it may be False if the hourly rate limit was reached)
Settings
Navigate to Settings from the top menu. All changes take effect when you click Save Settings — the monitoring engine restarts automatically.
Monitoring Targets
| Action | Notes |
|---|---|
| + Add Target | Opens the add-target dialog. Enter name, host/IP, optional description, and per-target latency threshold. |
| Edit (per target) | Modify the target's name, description, or latency threshold without affecting history data |
| Remove (per target) | Removes the target from monitoring. Historical data for this target is retained in history.csv. |
Mail Server (SMTP)
| Field | Notes |
|---|---|
| SMTP Server | Hostname or IP of your outbound mail relay |
| Port | 587 for STARTTLS (recommended); 465 for SSL/TLS; 25 for plain SMTP |
| Use TLS | Check this for port 587 (STARTTLS). Uncheck for plain port 25. |
| Username / Password | SMTP authentication credentials. Password is masked in the UI. |
| From Address | The address that appears in the "From:" field of all alert emails |
| Alert Recipients | One email address per line. All recipients receive every alert email. |
Send Test Email
Enter a test recipient address in the Test Recipient field (does not need to be in your recipient list) and click Send Test Email. The test uses the current form values — no need to save first. A ✓ success or ✗ error with a specific message appears immediately.
Thresholds & Intervals
| Setting | Default | Notes |
|---|---|---|
| Global Packet Loss Threshold | 5% | Triggers ALERT when loss reaches or exceeds this value. Apply per-target overrides in the target editor for devices with known baseline loss. |
| Global Latency Threshold | 100 ms | Fallback for targets with no per-target latency override set |
| Ping Interval | 60 s | How often each target is checked. Shorter interval = more data but higher network overhead. |
| Packets per Check | 5 | ICMP packets per ping cycle. More packets = more accurate loss% but longer check duration. |
| Alert Cooldown | 15 min | Minimum time between repeat emails for the same target. Prevents email floods during sustained outages. |
| Max Alerts per Hour | 10 | Global email rate limit. Set to 0 for unlimited. Recommended to leave at 10 for most deployments. |
Advanced — Launch on Windows Startup
Checking this option adds a registry entry under HKCU\Software\Microsoft\Windows\CurrentVersion\Run so the application starts when the current user logs into Windows. This is independent of the Windows service — the service starts at boot regardless of who is logged in.
About Page
Navigate to About from the top menu for application information, desktop shortcut management, and the configuration folder shortcut.
Desktop Shortcut Management
The About page provides buttons to create or remove a shortcut for all users on the machine:
| Button | Action | Requires Admin? |
|---|---|---|
| Create Shortcut | Creates Matrix IT – Packet Loss Monitor.lnk in C:\Users\Public\Desktop with the custom application icon | Yes — UAC prompt appears |
| Remove | Deletes the shortcut from the public desktop | Yes — UAC prompt appears |
Open Config Folder
Click Open Folder in the Configuration card to open C:\packetmonitor\ in Windows Explorer. This is the quickest way to access config.json, history.csv, and monitor.log for review or backup.
Windows Service
The application registers a Windows service named MatrixITPktMon during installation. The service runs the monitoring engine in headless (no window) mode — sending alert emails without any user being logged in, surviving reboots automatically.
Service Details
| Property | Value |
|---|---|
| Service Name | MatrixITPktMon |
| Display Name | Matrix IT Packet Loss Monitor |
| Startup Type | Automatic (starts on boot, no login required) |
| Log On As | Local System |
| Executable | C:\Program Files\Matrix IT\Packet Loss Monitor\PacketlossMonitor.exe --headless |
| Config File | C:\packetmonitor\config.json (shared with GUI) |
Service Status Indicator
The top-right corner of the application shows the current service state at all times:
Managing the Service
The service can be managed from Windows Services (services.msc) or the command line:
System Tray
When the main window is closed, the application minimises to the Windows system tray rather than exiting. Monitoring continues uninterrupted in the background.
Tray Icon Context Menu
| Menu Item | Action |
|---|---|
| Open Monitor | Brings the main window to focus and navigates to the Dashboard. Restores the window if it was minimised or hidden. |
| Exit | Stops monitoring and exits the application completely. The Windows service continues running if it was installed. |
Balloon Notifications
When a threshold is breached, a balloon notification pops from the tray icon showing the target name and current status. Clicking the balloon opens the main window on the Dashboard.
Single-Instance Behaviour
The application enforces a single running instance. If you click the desktop shortcut while the app is already running in the tray, the existing window is brought to focus rather than opening a second window. This prevents duplicate alert emails and conflicting monitoring loops.
Alert Emails
When a threshold breach passes both the per-target cooldown check and the global hourly rate limit, an HTML email is sent to all configured recipients via your SMTP relay.
Email Subject Format
Email Contents
| Section | Contents |
|---|---|
| Alert Summary | Target name, IP, description, timestamp, alert reason (HIGH LATENCY / PACKET LOSS / LOSS + LATENCY), loss %, avg/min/max latency, packets sent/received, configured thresholds |
| TCP Port Probes | OPEN / CLOSED status for ports 22, 23, 80, 443, 8080 |
| Traceroute | Full tracert -d output |
| PathPing | pathping -n per-hop loss analysis |
| ARP Table | Full arp -a output |
| DNS Lookup | nslookup result |
Alert Flood Protection
| Control | Default | Scope | Effect |
|---|---|---|---|
| Cooldown | 15 min | Per target | Minimum time between repeat alert emails for the same target. Resets when the target returns to OK. |
| Max alerts/hour | 10 | Global | Maximum total emails per hour across all targets. 0 = unlimited. |
Automated Diagnostics
Recon runs automatically when a target enters ALERT and the last recon for that target is stale (older than the cooldown period). It can also be triggered manually using Force Recon in the Target Detail Panel or ⟳ Force Recon All on the dashboard.
While recon is running, a blue RECON... spinner appears on the target's card. Recon runs on a background thread — monitoring and the UI continue working normally.
Diagnostic Tools Reference
| Tool | Command | Purpose | Duration |
|---|---|---|---|
| Traceroute | tracert -d -w 3000 | Maps every hop to the target. Identifies which segment introduced the latency or loss. | 10–30 sec |
| PathPing | pathping -n -q 50 | Per-hop packet loss % over 50 probes. Identifies which specific router is dropping packets. | 2–6 min |
| ARP Table | arp -a | Dumps the local ARP table. Detects duplicate IP conflicts (same IP, two MACs). | <1 sec |
| DNS Lookup | nslookup | Verifies DNS resolution for the target hostname is healthy at the time of the alert. | <5 sec |
| TCP Port Probes | Socket connect: 22, 23, 80, 443, 8080 | Tests L4 connectivity vs L3 ICMP loss — distinguishes "device up but routing broken" from "device down" | <15 sec |
Threshold Reference
Choosing the right latency thresholds prevents both false positives (too many alerts for acceptable latency) and missed events (thresholds set too high). Use the table below as a starting guide.
| Target Type | Recommended Latency Threshold | Notes |
|---|---|---|
| Local LAN device (switch, AP, printer) | 5–15 ms | Sub-millisecond response is normal on Gigabit LAN. 15 ms+ on a LAN device usually indicates a problem. |
| Site-to-site MPLS / private WAN | 20–50 ms | Depends on circuit distance and quality. Baseline with normal traffic first. |
| ISP gateway / public internet target | 50–150 ms | Higher variance is normal. Set threshold 50–100% above your typical baseline average. |
| Cloud service (e.g. 8.8.8.8, 1.1.1.1) | 80–150 ms | Use as a secondary check to distinguish local WAN problems from global internet issues. |
Packet Loss Threshold
The default global packet loss threshold is 5%. On a 5-packet check, this means 1 out of 5 packets lost triggers WARNING; 5% rounded means any loss triggers it (since 1/5 = 20% — lower the threshold to catch even single-packet loss). Recommended values:
- 0% — Zero tolerance (any lost packet triggers alert). For critical infrastructure.
- 5% — Default. Good balance for most deployments.
- 10–20% — Only alert on significant sustained loss. For noisy links where some baseline loss is expected.
Configuration File
All settings are stored in C:\packetmonitor\config.json. This file is managed entirely through the Settings screen — manual editing is not required but the format is shown here for reference and backup purposes.
Troubleshooting
"Setup required" banner stays visible after configuring
Check that all three conditions are met: at least one monitoring target, SMTP host field filled in, and at least one alert recipient. All three must be present. Click Save Settings after completing them.
All targets show UNKNOWN and never update
ICMP ping is blocked. Open Command Prompt and run ping 192.168.1.x to the target manually. If it times out, check Windows Defender Firewall outbound rules and any network ACL between the monitoring machine and the targets.
Target shows ALERT with 0% packet loss
Expected behaviour — this is a HIGH LATENCY alert. Average latency exceeded the per-target ms threshold even though no packets were lost. If the latency is acceptable for that link, increase the per-target threshold in Settings → Edit Target.
Test email fails with "SMTP Server host is empty"
Fill in the SMTP Server field in Settings. The test email uses current form values without requiring Save — but the host field must contain something to attempt a connection.
Test email fails with a connection or authentication error
Verify: (1) outbound TCP on the configured port (587 by default) is not blocked by Windows Firewall or a perimeter device; (2) the username and password are correct; (3) the SMTP host is reachable from this machine. Run telnet smtp.yourdomain.com 587 from Command Prompt to test basic connectivity.
Alert emails are not arriving during an incident
Check C:\packetmonitor\monitor.log for suppression messages. Either the per-target cooldown is active (target was already alerted within the last 15 minutes) or the hourly rate limit was reached. Use ⟳ Force Recon All to bypass cooldowns. To view the log, go to About → Open Folder.
Target Detail Panel shows "No diagnostic data yet"
Recon has not run for this target yet — it only runs automatically when the target breaches its threshold. Click ⊙ Force Recon to trigger diagnostics immediately regardless of status.
Clicking the desktop shortcut opens a second window
This should not happen with the current version. The single-instance guard uses a named mutex and the exact window title. If you have multiple versions installed, remove older ones via Add/Remove Programs and reinstall the latest version.
Latency chart is empty
The chart requires at least 2 data points to draw. Wait for 2 completed ping cycles (2 × your configured interval — 2 minutes at the default 60-second setting). After that the chart populates and continues updating.
UNSTABLE badge appears but the device seems fine
The UNSTABLE badge appears when a target changes status 3+ times in the last 10 checks. Even if it looks OK right now, this means it was oscillating recently. Click the card and review the packet loss heat strip — scattered amber/red blocks interspersed with green confirm intermittent instability. This often precedes a full outage.
Service shows "Not Installed" after the installer ran
Try running the installer again as Administrator. The service registration requires elevated privileges. You can also verify in services.msc — look for "Matrix IT Packet Loss Monitor". If not listed, re-run the installer.