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

# Client Tracking & Health Monitoring

> Real-time client health monitoring with network ping status, connection diagnostics, and usage analytics. Track every API client's status and performance.

# Client Tracking & Health Monitoring

Monitor the health, connectivity, and usage of every API client in real-time. KnoxCall provides comprehensive client tracking with network diagnostics, ping monitoring, and detailed usage analytics.

## What is Client Tracking?

Client tracking gives you visibility into every application, server, or service that accesses your APIs through KnoxCall:

* 📊 **Usage Analytics** - Requests, success rates, latency per client
* 🏥 **Health Monitoring** - Ping status, connectivity checks
* 🌍 **Geographic Tracking** - See where requests originate
* 📈 **Performance Metrics** - Response times and error rates
* 🔔 **Alerting** - Get notified of client issues

## Client Overview Dashboard

The client dashboard shows all your clients at a glance:

```text theme={"dark"}
╔══════════════════════════════════════════════════════════════╗
║ CLIENT STATUS OVERVIEW                                        ║
╠══════════════════════════════════════════════════════════════╣
║ Total Clients: 12                                            ║
║ 🟢 Healthy: 10    🟡 Degraded: 1    🔴 Down: 1              ║
║ Total Requests (24h): 156,489                                ║
║ Average Latency: 45ms                                        ║
╚══════════════════════════════════════════════════════════════╝

┌──────────────────────────────────────────────────────────────┐
│ CLIENT LIST                                                   │
├──────────────────────────────────────────────────────────────┤
│ 🟢 mobile-app-ios          Last seen: 2m ago    Requests: 45k│
│ 🟢 web-frontend            Last seen: 5s ago    Requests: 78k│
│ 🟡 payment-processor       Last seen: 1h ago    Requests: 234│
│ 🔴 legacy-system           Last seen: 2d ago    Requests: 0  │
│ 🟢 internal-api            Last seen: 10s ago   Requests: 12k│
│ 🟢 partner-integration     Last seen: 1m ago    Requests: 21k│
└──────────────────────────────────────────────────────────────┘
```

## Client Health Status

Each client has a health status:

### 🟢 Healthy

```text theme={"dark"}
Criteria:
- ✅ Last seen < 5 minutes ago
- ✅ Success rate > 95%
- ✅ Latency < 500ms
- ✅ No recent errors
```

### 🟡 Degraded

```text theme={"dark"}
Criteria:
- ⚠️ Success rate 80-95%
- ⚠️ Latency 500-2000ms
- ⚠️ Minor errors present
- ⚠️ Last seen 5-60 minutes ago
```

### 🔴 Down

```text theme={"dark"}
Criteria:
- ❌ Last seen > 1 hour ago
- ❌ Success rate < 80%
- ❌ Multiple consecutive errors
- ❌ Connection timeout
```

### ⚪ Unknown

```text theme={"dark"}
Criteria:
- No requests yet
- Newly created client
- Pending first connection
```

## Real-Time Ping Monitoring

KnoxCall actively monitors client health with ping checks:

### Active Ping Monitoring

For IP-based clients, KnoxCall can actively ping:

```text theme={"dark"}
Every 60 seconds:
  ├─ ICMP ping to client IP
  ├─ Measure round-trip time
  ├─ Detect connectivity issues
  └─ Update health status
```

**Enable for client:**

1. Go to **Clients** → Select client
2. Enable **Active Health Checks**
3. Configure:

```yaml theme={"dark"}
Check Interval: 60 seconds
Timeout: 5 seconds
Failure Threshold: 3 consecutive failures
Protocol: ICMP Ping
```

### Passive Monitoring

For all clients, track based on API requests:

```text theme={"dark"}
Monitor:
- Last request timestamp
- Request frequency
- Success/failure patterns
- Response time trends
```

## Client Details View

Click any client to see detailed information:

### Overview Tab

```text theme={"dark"}
╔══════════════════════════════════════════════════════════════╗
║ CLIENT: mobile-app-ios                                        ║
╠══════════════════════════════════════════════════════════════╣
║ Status: 🟢 Healthy                                           ║
║ Type: Mobile Application                                      ║
║ IP Address: 203.0.113.50                                      ║
║ Last Seen: 2 minutes ago                                      ║
║ Created: 2024-08-15                                          ║
╚══════════════════════════════════════════════════════════════╝

Request Statistics (24 hours):
├─ Total Requests: 45,234
├─ Successful: 44,987 (99.45%)
├─ Failed: 247 (0.55%)
├─ Average Latency: 42ms
└─ Peak Requests/hour: 3,456

Geographic Distribution:
├─ 🇺🇸 United States: 78%
├─ 🇨🇦 Canada: 15%
├─ 🇬🇧 United Kingdom: 5%
└─ 🇦🇺 Australia: 2%
```

### Activity Timeline

See client activity over time:

```text theme={"dark"}
24-Hour Activity:
12 AM  ████░░░░░░░░░░░░░░░░  1,234 req
 1 AM  ███░░░░░░░░░░░░░░░░░    876 req
 2 AM  ██░░░░░░░░░░░░░░░░░░    654 req
 ...
11 PM  ████████░░░░░░░░░░░░  2,345 req

Peak: 8 AM - 12 PM (business hours)
Low: 1 AM - 5 AM (night hours)
```

### Performance Metrics

Track client performance:

```text theme={"dark"}
Response Time Distribution:
< 50ms:   ████████████████████ 85%
50-100ms: ████░░░░░░░░░░░░░░░░ 10%
100-500ms:██░░░░░░░░░░░░░░░░░░  4%
> 500ms:  ░░░░░░░░░░░░░░░░░░░░  1%

Error Types:
404 Not Found:      45% (112 errors)
503 Service Unavailable: 30% (74 errors)
401 Unauthorized:   15% (37 errors)
500 Internal Error: 10% (24 errors)
```

### Routes Used

See which routes this client accesses:

```text theme={"dark"}
Route Usage:
├─ user-api............45% (20,355 req)
├─ order-api...........30% (13,570 req)
├─ product-api.........20% (9,047 req)
└─ payment-api..........5% (2,262 req)
```

### Recent Requests

View last 100 requests:

```text theme={"dark"}
[15:34:22] GET /api/users/123 → 200 OK (45ms)
[15:34:18] POST /api/orders → 201 Created (89ms)
[15:34:10] GET /api/products → 200 OK (32ms)
[15:33:55] DELETE /api/cart/456 → 204 No Content (28ms)
[15:33:42] POST /api/auth/login → 401 Unauthorized (12ms)
...
```

## Connection Diagnostics

Diagnose connectivity issues:

### Network Path Trace

See the network path to your client:

```text theme={"dark"}
Traceroute to 203.0.113.50:

 1. knoxcall-gateway (0.2ms)
 2. provider-edge (2.5ms)
 3. internet-backbone (15.3ms)
 4. client-isp (32.1ms)
 5. client-network (45.7ms)
 6. 203.0.113.50 (48.2ms)

Total hops: 6
Total latency: 48.2ms
Status: ✅ Healthy connection
```

### Ping Statistics

Real-time ping monitoring:

```text theme={"dark"}
Ping Statistics (last hour):
├─ Packets sent: 60
├─ Packets received: 60
├─ Packet loss: 0%
├─ Min RTT: 42ms
├─ Avg RTT: 48ms
├─ Max RTT: 67ms
└─ Jitter: 8ms

Status: 🟢 Excellent
```

### DNS Resolution

Check DNS configuration:

```text theme={"dark"}
DNS Lookup: mobile-app-ios.example.com
├─ Resolved IP: 203.0.113.50 ✅
├─ TTL: 300 seconds
├─ DNS Server: 8.8.8.8
└─ Resolution time: 12ms

Reverse DNS:
└─ 203.0.113.50 → mobile-app-ios.example.com ✅
```

## Usage Analytics

### Request Volume Trends

Track request patterns:

```text theme={"dark"}
7-Day Request Volume:
Mon: ████████████████░░░░ 45.2k
Tue: ████████████████████ 52.1k ← Peak
Wed: ███████████████░░░░░ 48.7k
Thu: ███████████████░░░░░ 47.3k
Fri: ████████████████░░░░ 46.8k
Sat: ████████░░░░░░░░░░░░ 28.4k
Sun: ███████░░░░░░░░░░░░░ 24.9k

Weekly Total: 293,400 requests
Average: 41,914 req/day
Trend: ↗ +12% vs last week
```

### Success Rate Over Time

Monitor reliability:

```text theme={"dark"}
Success Rate (7 days):
100% ┤                      ╭────
 99% ┤              ╭───────╯
 98% ┤      ╭───────╯
 97% ┤  ────╯
 96% ┤
 95% ┼────────────────────────────
     Mon   Tue   Wed   Thu   Fri

Current: 99.5% ✅
Target: 99% ✅
Trend: Improving
```

### Top Error Codes

Identify common issues:

```text theme={"dark"}
Error Distribution (24h):
404 Not Found............112 (45%)
  └─ Most common path: /api/users/{deleted_id}

503 Service Unavailable...74 (30%)
  └─ Peak time: 2 PM - 3 PM (backend overload)

401 Unauthorized..........37 (15%)
  └─ Cause: Expired tokens

500 Internal Error........24 (10%)
  └─ Route: payment-api
```

## Alerts & Notifications

Set up client-specific alerts:

### Client Down Alert

```text theme={"dark"}
Alert: mobile-app-ios Offline
Condition: No requests for 15 minutes
Notification: Email, Slack, SMS
```

### High Error Rate

```text theme={"dark"}
Alert: Degraded Client Performance
Condition: Error rate > 5% for 10 minutes
Client: payment-processor
Notification: PagerDuty escalation
```

### Unusual Activity

```text theme={"dark"}
Alert: Abnormal Request Volume
Condition: Request volume 10x normal
Client: partner-integration
Action: Rate limit + notify
```

## Client Comparison

Compare multiple clients side-by-side:

```text theme={"dark"}
                  mobile-app  web-frontend  legacy-system
Request Volume    45.2k      78.3k         234
Success Rate      99.5%      98.7%         85.2%
Avg Latency       42ms       38ms          1,245ms
Last Active       2m ago     5s ago        2d ago
Status            🟢         🟢            🔴
```

## Geographic Tracking

See where requests come from:

### World Map View

```text theme={"dark"}
Client: mobile-app-ios - Geographic Distribution

    🌎 North America: 93%
    ├─ 🇺🇸 United States: 78%
    └─ 🇨🇦 Canada: 15%

    🌍 Europe: 5%
    └─ 🇬🇧 United Kingdom: 5%

    🌏 Asia Pacific: 2%
    └─ 🇦🇺 Australia: 2%
```

### City-Level Detail

```text theme={"dark"}
Top Cities:
1. New York, NY: 23,456 req (52%)
2. Los Angeles, CA: 8,934 req (20%)
3. Toronto, ON: 5,678 req (13%)
4. London, UK: 2,234 req (5%)
5. San Francisco, CA: 1,890 req (4%)
```

## Client Lifecycle Management

Track client lifecycle:

```text theme={"dark"}
Timeline:
2024-08-15: Created
2024-08-16: First request
2024-08-20: Production rollout (10k req/day)
2024-09-01: Upgrade v2.0 (20k req/day)
2024-10-15: Peak usage (52k req/day)
2024-10-29: Current (45k req/day)

Age: 76 days
Total Requests: 2.8M
Avg Daily: 37k requests
```

## Best Practices

### 1. Name Clients Descriptively

```text theme={"dark"}
✅ Good:
- mobile-app-ios-v2
- web-frontend-production
- partner-api-acme-corp

❌ Bad:
- client1
- test
- temp
```

### 2. Tag Clients by Purpose

```text theme={"dark"}
Tags:
- mobile
- production
- payment-critical
- partner-api
```

### 3. Monitor Critical Clients

Set up monitoring for business-critical clients:

```text theme={"dark"}
Critical Clients:
- payment-processor ← Alert on any issue
- order-fulfillment ← 99.9% SLA requirement
- customer-portal ← High visibility
```

### 4. Review Inactive Clients

Regularly audit inactive clients:

```text theme={"dark"}
Inactive > 30 days:
- Remove: legacy-system-old
- Archive: test-client-2023
- Keep: backup-system (standby)
```

### 5. Document Client Ownership

```text theme={"dark"}
Client: mobile-app-ios
Owner: Mobile Team
Contact: mobile-team@company.com
On-Call: +1-555-123-4567
```

## Troubleshooting

### Client shows as down but is working

**Causes:**

* Client using different IP
* Requests going through proxy
* Client ID mismatch

**Fix:**

* Check client configuration
* Verify IP whitelisting
* Review recent requests

### High latency for one client

**Diagnose:**

* Run traceroute
* Check ping statistics
* Compare with other clients
* Review backend performance

### Intermittent connectivity

**Check:**

* Network path stability
* Packet loss percentage
* Client-side issues
* ISP problems

## Next Steps

<CardGroup cols={2}>
  <Card title="Alerts" icon="bell" href="/monitoring/alerts">
    Set up client health alerts
  </Card>

  <Card title="Analytics" icon="chart-line" href="/monitoring/analytics">
    View detailed analytics
  </Card>

  <Card title="Client Permissions" icon="shield" href="/security/client-permissions">
    Configure client security
  </Card>

  <Card title="Rate Limiting" icon="gauge" href="/advanced/rate-limiting">
    Set per-client rate limits
  </Card>
</CardGroup>

***

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

  <Card title="🏷️ Tags" icon="tags">
    `monitoring`, `clients`, `health-checks`, `tracking`, `diagnostics`
  </Card>
</CardGroup>