FLUX SPEED

// OVERVIEW

Flux Speed is a Docker-native network performance platform that enables on-demand and scheduled testing from any registered agent node. Every test result is stored in a time-series database for trending, SLA reporting, and carrier dispute evidence.

Flux Speed integrates with Flux Notify to automatically escalate incidents when performance thresholds are breached — giving your NOC team immediate visibility into network degradation.

ARCHITECTURE

// INSTALLATION

QUICK START

# Clone and start Flux Speed
git clone https://github.com/your-org/flux-speed.git
cd flux-speed

# Linux / macOS
chmod +x start.sh && ./start.sh

# Windows
start.bat

The startup script builds all containers, initializes the PostgreSQL schema, seeds demo data, and starts all services. Allow approximately 30 seconds for full initialization on first run.

DEFAULT PORTS

// TEST AGENTS

Flux Speed uses lightweight agent processes deployed at strategic points in your network. Each agent can independently execute tests, report results back to the central server, and receive scheduled job assignments.

DEPLOYING AN AGENT

# Deploy an agent on any Linux host
docker run -d \
  --name flux-speed-agent \
  --restart unless-stopped \
  -e SPEED_SERVER_URL=http://your-flux-speed-server:4040 \
  -e AGENT_NAME=BRANCH-OFFICE-01 \
  -e AGENT_LOCATION="Dallas, TX" \
  -e AGENT_TOKEN=your_registration_token \
  flux-speed-agent:latest

AGENT STATUS STATES

// RUNNING SPEEDTESTS

Speedtests measure real-world download throughput, upload throughput, latency (ping), and jitter between a test agent and a target server. Tests use iPerf3 for LAN/datacenter targets and a built-in HTTP-based engine for internet targets.

TEST PARAMETERS

UNDERSTANDING RESULTS

• Throughput — measured in Mbps or Gbps. Reflects the actual usable bandwidth between agent and target.
• Latency (ping) — round-trip time in milliseconds. Under 10ms is excellent for LAN; under 50ms is acceptable for WAN.
• Jitter — variation in latency. High jitter (>10ms) degrades VoIP, video, and real-time applications.
• Packet loss — percentage of packets dropped. Any loss above 0.1% is worth investigating.

// TRACEROUTE & MTR

Traceroute analysis reveals the hop-by-hop path between an agent and a target, showing latency and packet loss at each network hop. This is essential for diagnosing where in the network a problem exists.

# Trigger a traceroute via API
POST /api/speed/trace
{
  "agent": "HQ-CORE",
  "target": "8.8.8.8",
  "count": 30,
  "interval_ms": 100
}

// PORT PROBES

Port probes verify TCP or UDP reachability to a specific host and port combination, measuring connection time in milliseconds. Use probes to verify that critical services (databases, APIs, mail servers) are accessible from each network segment.

POST /api/speed/probe
{
  "agent": "BRANCH-01",
  "target": "db-prod-01.internal",
  "port": 5432,
  "protocol": "tcp",
  "timeout_ms": 2000
}

// DNS TIMING

DNS resolution timing tests measure how long it takes each configured resolver to respond to queries. Slow DNS is a common cause of perceived application slowness that often goes undiagnosed.

POST /api/speed/dns
{
  "agent": "HQ-CORE",
  "hostname": "api.internal.example.com",
  "resolvers": ["8.8.8.8", "1.1.1.1", "192.168.1.1"]
}

// SCHEDULED JOBS

Scheduled jobs automate recurring tests at configurable intervals. Each job specifies an agent, target, test type, interval, and optional threshold settings for alerting.

POST /api/speed/schedules
{
  "name": "HQ Uplink — Hourly",
  "agent": "HQ-CORE",
  "target": "speedtest.net",
  "test_type": "speedtest",
  "interval_seconds": 3600,
  "thresholds": {
    "download_min_mbps": 800,
    "upload_min_mbps": 400,
    "latency_max_ms": 20,
    "packet_loss_max_pct": 0.5
  },
  "alert_on_breach": true,
  "notify_contact_list": "NOC Team"
}

// THRESHOLD ALERTS

Alert rules fire when a test result breaches a configured threshold. Alerts are routed to Flux Notify, which handles escalation, multi-channel delivery, and acknowledgment tracking.

// FLUX NOTIFY INTEGRATION

When a threshold alert fires, Flux Speed automatically creates a severity-appropriate incident in Flux Notify and triggers notification delivery to the configured contact list.

# Settings → Integrations → Flux Notify
FLUX_NOTIFY_URL=http://flux-notify:4004
FLUX_NOTIFY_API_KEY=your_api_key
DEFAULT_SEVERITY=HIGH        # CRITICAL, HIGH, MEDIUM, LOW
DEFAULT_CONTACT_LIST=NOC Team

// BASELINES

Flux Speed automatically calculates performance baselines for each agent/target pair using a rolling 14-day window. Baselines represent the median performance under normal conditions and are used to detect meaningful deviations.

• Baselines are recalculated nightly using the previous 14 days of results.
• Maintenance window results are excluded from baseline calculations.
• A minimum of 50 test results is required before a baseline is considered reliable.
• Deviation alerts fire when a result is more than a configurable percentage below baseline (default: 30%).

// HISTORY & TRENDS

Every test result is stored in the PostgreSQL time-series database and is available for trend analysis across configurable time windows.

// REPORTS & EXPORT

Flux Speed generates PDF and CSV reports for any time range, agent, or target combination. Reports include summary statistics, trend charts, threshold breach events, and are suitable as carrier SLA dispute evidence.

# Request a report via API
GET /api/speed/report?agent=HQ-CORE&start=2026-01-01&end=2026-01-31&format=pdf

Reports include: average and P95 download/upload speeds, latency statistics, packet loss summary, breach event log with timestamps, and comparison against configured SLA targets.

// REST API

AUTHENTICATION

All API endpoints require authentication via Authorization: Bearer <JWT> or X-API-Token: <token>. Obtain a JWT via POST /api/auth/login.

ENDPOINTS

// RBAC & PERMISSIONS