> ## Documentation Index
> Fetch the complete documentation index at: https://docs.knoxcall.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Real-Time Geographic Tracking

> Watch live API requests animated on an interactive world map. See request origins, destinations, status codes, and latency in real-time with audio feedback.

# Real-Time Geographic Tracking

Watch your API requests in real-time on an interactive world map with animated arcs showing traffic flow from source to destination.

## Overview

The **Real-Time Geo** feature provides live visualization of API requests:

* 🌍 **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

**Perfect for:**

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

## What You'll See

### Animated Request Arcs

Each API request draws an arc on the map:

**Arc properties:**

* **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

**Example arc:**

```text theme={"dark"}
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

On the right side, see live request feed:

**Each entry shows:**

* 🌐 **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

**Example:**

```text theme={"dark"}
🌐 London, United Kingdom → Virginia, USA
📝 GET /api/users/123
✅ 200 (23ms)
🕐 10:30:45
```

### Live Statistics

**Top bar displays:**

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

**Updates in real-time** as requests come in.

## 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)

**Toggle audio feedback:**

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

**Sound characteristics:**

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

### Step 3: Watch Live Traffic

**As requests come in:**

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

**Map controls:**

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

**Request list:**

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

## Features

### SSE (Server-Sent Events) Connection

**Real-time streaming:**

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

**Connection states:**

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

**If disconnected:**

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

### Geographic Resolution

**How locations determined:**

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

**Accuracy:**

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

### Color Coding

**Status code colors:**

```text theme={"dark"}
2xx (Success):    Green arc  🟢
3xx (Redirect):   Yellow arc 🟡
4xx (Client Error): Orange arc 🟠
5xx (Server Error): Red arc 🔴
```

**Visual scanning:**

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

### Request Persistence

**On-screen:**

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

**Refresh page** to reset counters and clear history.

## Use Cases

### Use Case 1: Live Demo

**Scenario:** Presenting KnoxCall to stakeholders

**Setup:**

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

**Impact:** Visual wow factor demonstrates proxy in action.

### Use Case 2: Geographic Load Balancing

**Scenario:** Verify multi-region setup

**What to look for:**

```text theme={"dark"}
US clients → US backend (green arcs)
EU clients → EU backend (green arcs)
Asia clients → Asia backend (green arcs)
```

**If seeing long arcs across continents:**

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

### Use Case 3: Incident Response

**Scenario:** Users in specific region reporting errors

**Investigation:**

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

**Example finding:**

```text theme={"dark"}
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

**Scenario:** Understanding global user distribution

**Observe over 1 hour:**

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

**Example insights:**

```text theme={"dark"}
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

**Coming soon:** Filter to show only specific routes

**Use case:** Monitor traffic for single route during deployment

### Latency Heatmap Overlay

**Map overlay shows:**

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

**Access:**

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

### Historical Playback

**Coming soon:** Replay past traffic

**Use case:** Analyze incidents after they occurred

## Best Practices

### 1. Use for Live Monitoring

**Ideal scenarios:**

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

### 2. Enable Audio During Background Monitoring

**When working on other tasks:**

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

**Split screen setup:**

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

**Comprehensive monitoring** - see both traffic flow and performance metrics.

### 4. Use for Client Onboarding

**Show new clients:**

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

**Builds confidence** in KnoxCall proxy.

### 5. Screenshot for Reports

**Monthly 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"

**Causes:**

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

**Fix:**

1. Check connection indicator (should be green)
2. Generate test request:
   ```bash theme={"dark"}
   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"

**Causes:**

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

**Fix:**

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

### Issue: "Locations incorrect"

**Causes:**

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

**Expected behavior:**

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

### Issue: "Audio not working"

**Causes:**

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

**Fix:**

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

## Technical Details

### Performance

**Optimization:**

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

**Browser requirements:**

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

## Privacy Considerations

**Data shown:**

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

**Recommendations:**

* 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

<CardGroup cols={2}>
  <Card title="Analytics" icon="chart-line" href="/monitoring/analytics">
    View aggregate metrics
  </Card>

  <Card title="API Logs" icon="list" href="/monitoring/api-logs">
    Detailed request logs
  </Card>

  <Card title="Alerts" icon="bell" href="/monitoring/alerts">
    Configure monitoring alerts
  </Card>

  <Card title="Routes" icon="route" href="/getting-started/first-route">
    Configure routes to track
  </Card>
</CardGroup>

***

<CardGroup cols={2}>
  <Card title="📊 Statistics" icon="chart-line">
    * **Level**: beginner
    * **Time**: 5 minutes
  </Card>

  <Card title="🏷️ Tags" icon="tags">
    `real-time`, `geographic`, `visualization`, `monitoring`, `live`
  </Card>
</CardGroup>