​

Real-Time Geographic Tracking

​

Overview

• 🌍 Interactive World Map - Leaflet-powered map with smooth animations
• ✈️ Animated Request Arcs - Visual paths from client to backend
• 🎵 Audio Feedback - Ping sound on each request (optional)
• 📍 City-Level Precision - See exact cities for requests
• 🎨 Color-Coded Status - Green (success), Red (error), Yellow (redirect)
• 📊 Live Statistics - Requests/minute, active routes

• Live demos and presentations
• Monitoring global traffic patterns
• Detecting geographic issues
• Understanding user distribution

​

What You’ll See

​

Animated Request Arcs

• Start point: Client IP location (latitude, longitude)
• End point: Backend API location
• Color:
  • 🟢 Green: Success (2xx status codes)
  • 🔴 Red: Error (4xx, 5xx status codes)
  • 🟡 Yellow: Redirect (3xx status codes)
• Animation: Arc draws from source to destination over 2 seconds
• Label: Shows method, path, latency

From: New York, USA (40.7128°N, 74.0060°W)
To: Virginia, USA (37.4316°N, 78.6569°W)
Method: POST /api/payments
Status: 200 OK (green arc)
Latency: 145ms

​

Request Details Panel

• 🌐 Source: City, Country
• 🎯 Destination: City, Country
• 📝 Request: HTTP method and path
• ✅ Status: Status code with color indicator
• ⏱️ Latency: Response time in milliseconds
• 🕐 Time: Timestamp of request

🌐 London, United Kingdom → Virginia, USA
📝 GET /api/users/123
✅ 200 (23ms)
🕐 10:30:45

​

Live Statistics

• Total Requests: Cumulative count since page load
• Requests/Minute: Current rate (rolling average)
• Active Routes: Number of routes receiving traffic

​

Using Real-Time Geo

​

Step 1: Navigate to Page

1. Click Monitoring in sidebar
2. Select Real-Time Geo
3. Map initializes and starts listening for requests

​

Step 2: Enable Audio (Optional)

1. Click Audio toggle in top-right
2. Each request plays a ping sound
3. Useful for background monitoring

• Frequency: 800Hz sine wave
• Duration: 200ms
• Volume: 30% (not too loud)

​

Step 3: Watch Live Traffic

1. Marker appears at source location
2. Arc animates from source to destination
3. Request details appear in right panel
4. Statistics update
5. Audio ping plays (if enabled)

​

Step 4: Interact with Map

• Zoom: Mouse wheel or +/- buttons
• Pan: Click and drag
• Reset View: Click home button

• Scroll: View historical requests (last 50)
• Auto-scroll: List scrolls to show newest requests

​

Features

​

SSE (Server-Sent Events) Connection

• Persistent connection to server
• Pushes new requests as they occur
• Connection indicator shows status

• 🟢 Connected: Receiving live data
• 🔴 Disconnected: Connection lost, retrying
• 🟡 Connecting: Establishing connection

• Automatic reconnection every 5 seconds
• No data loss (buffered on server)

​

Geographic Resolution

1. Client IP → GeoIP lookup → City, Country, Coordinates
2. Backend URL → DNS resolution → IP → GeoIP lookup
3. Cached for performance

• City-level for most requests
• Country-level if city unknown
• Coordinates used for precise arc drawing

​

Color Coding

2xx (Success):    Green arc  🟢
3xx (Redirect):   Yellow arc 🟡
4xx (Client Error): Orange arc 🟠
5xx (Server Error): Red arc 🔴

• All green = everything working
• Red arcs appearing = errors, investigate
• Many yellow = redirects (might be configuration issue)

​

Request Persistence

• Arcs fade after 5 seconds
• Request list keeps last 50 requests
• Statistics accumulate since page load

​

Use Cases

​

Use Case 1: Live Demo

1. Open Real-Time Geo on large monitor
2. Enable audio feedback
3. Generate some test traffic
4. Show animated arcs in real-time

​

Use Case 2: Geographic Load Balancing

US clients → US backend (green arcs)
EU clients → EU backend (green arcs)
Asia clients → Asia backend (green arcs)

• Possible routing misconfiguration
• Clients not hitting nearest backend
• Investigate environment overrides

​

Use Case 3: Incident Response

1. Open Real-Time Geo
2. Watch for red arcs from that region
3. Check destination backend
4. Verify latency values

Red arcs from UK → Virginia backend (timeout)
Issue: UK → US network path degraded
Fix: Switch UK clients to EU backend

​

Use Case 4: Traffic Pattern Analysis

• Which regions generate most traffic?
• What times are peak for each region?
• Are there unexpected traffic sources?

70% traffic from US (expected)
15% from EU (growing market)
10% from Asia (new clients)
5% from unknown IPs (investigate - possible bots)

​

Advanced Features

​

Filter by Route

​

Latency Heatmap Overlay

• Color intensity = average latency
• Identify slow regions
• Plan infrastructure improvements

1. Toggle Heatmap view
2. See color gradient (green = fast, red = slow)

​

Historical Playback

​

Best Practices

​

1. Use for Live Monitoring

• Load testing (watch traffic scale)
• Deployments (ensure no errors)
• Marketing campaigns (see traffic spikes)
• Conference demos (impressive visualization)

​

2. Enable Audio During Background Monitoring

1. Open Real-Time Geo on second monitor
2. Enable audio
3. Mute if no activity (silence = good)
4. Investigate when rapid pings (unusual activity)

​

3. Combine with Analytics Dashboard

• Left: Real-Time Geo (live visualization)
• Right: Analytics (charts and metrics)

​

4. Use for Client Onboarding

1. Their first test request
2. Arc animating across map
3. Successful green arc = integration working

​

5. Screenshot for Reports

1. Open Real-Time Geo during peak traffic
2. Screenshot showing global traffic
3. Include in monthly/quarterly reports
4. Visual representation of reach

​

Troubleshooting

​

Issue: “No requests appearing”

• No active traffic to routes
• SSE connection disconnected
• Browser blocking SSE (firewall/proxy)

1. Check connection indicator (should be green)
2. Generate test request:
   Copy

   curl -X GET "https://hash.tenant.knoxcall.com/test" \
     -H "x-knoxcall-key: YOUR_KEY" \
     -H "x-knoxcall-route: test-route"
   
3. Verify request appears on map

​

Issue: “Map not loading”

• Leaflet CSS not loaded
• JavaScript error
• Feature not available on subscription plan

1. Refresh page
2. Check browser console for errors
3. Verify subscription includes Real-Time Geo

​

Issue: “Locations incorrect”

• GeoIP database outdated
• VPN/proxy hiding real location
• IP address not in GeoIP database

• VPN users show VPN exit location (not real location)
• This is correct behavior

​

Issue: “Audio not working”

• Browser autoplay policy (requires user interaction)
• Audio muted in browser
• Audio toggle disabled

1. Click anywhere on page (activates audio context)
2. Enable audio toggle
3. Check browser audio settings

​

Technical Details

​

SSE Endpoint

GET /api/realtime/geo/stream
Authorization: Bearer <token>
X-Tenant-ID: <tenant_id>

{
  "id": "req_abc123",
  "sourceLatitude": 40.7128,
  "sourceLongitude": -74.0060,
  "sourceCity": "New York",
  "sourceCountry": "United States",
  "destLatitude": 37.4316,
  "destLongitude": -78.6569,
  "destCity": "Virginia",
  "destCountry": "United States",
  "method": "POST",
  "path": "/api/payments",
  "statusCode": 200,
  "latencyMs": 145,
  "timestamp": "2025-01-15T10:30:45Z"
}

​

Performance

• Arcs removed after 5 seconds (prevent memory leak)
• Request list limited to 50 entries
• Coordinates cached (avoid repeated GeoIP lookups)

• Modern browser with SSE support
• Canvas/SVG support for animations
• Audio API support (optional, for audio feedback)

​

Privacy Considerations

• Client city and country (not exact address)
• Backend city and country
• Request paths (may contain sensitive data)

• Don’t share screenshots if paths contain secrets
• Use for internal monitoring only
• Consider data privacy regulations (GDPR, etc.)

​

Related Features

• Analytics: View aggregate traffic metrics
• API Logs: Detailed request history
• Alerts: Set up geographic alerts (coming soon)

​

Next Steps