0
# Analytics & Monitoring
1

2
Analytics and monitoring capabilities for tracking traffic, performance, and usage metrics of deployed projects on the Surge platform.
3

4
## Capabilities
5

6
### Comprehensive Analytics
7

8
View comprehensive analytics data for deployed projects including traffic, performance, and user behavior metrics.
9

10
```javascript { .api }
11
/**
12
 * View comprehensive analytics for project
13
 * @param hooks - Optional lifecycle hooks
14
 * @returns Command function
15
 */
16
function analytics(hooks?: HookConfig): CommandFunction;
17
```
18

19
**CLI Usage:**
20
```bash
21
# View comprehensive analytics for domain
22
surge analytics example.surge.sh
23

24
# Interactive domain selection
25
surge analytics
26
```
27

28
**Analytics Data Includes:**
29
- **General Metrics**: Total visits, connections, bandwidth usage
30
- **Status Codes**: HTTP response code breakdown (200, 304, 404, etc.)
31
- **Encryption**: Unencrypted vs encrypted traffic distribution
32
- **Traffic Sources**: Referrer URLs and source distribution
33
- **Device/OS/Browser**: Device type, operating system, and browser analytics
34
- **Success/Fail Paths**: Most requested successful and failed paths
35
- **Redirects**: 301/302 redirect patterns
36
- **Load Distribution**: Bandwidth usage by file/path
37
- **Time-series Data**: Analytics broken down by time periods
38

39
**Library Usage:**
40
```javascript
41
surge.analytics({})(process.argv.slice(2));
42
```
43

44
### Traffic Analytics
45

46
View detailed traffic analytics for deployed projects.
47

48
```javascript { .api }
49
/**
50
 * View traffic analytics for project
51
 * @param hooks - Optional lifecycle hooks
52
 * @returns Command function
53
 */
54
function traffic(hooks?: HookConfig): CommandFunction;
55
```
56

57
**CLI Usage:**
58
```bash
59
# View traffic for domain
60
surge traffic example.surge.sh
61

62
# Interactive domain selection
63
surge traffic
64
```
65

66
**Traffic Metrics:**
67
- **Page Views**: Total page requests
68
- **Unique Visitors**: Distinct visitor count
69
- **Bandwidth**: Data transfer volume
70
- **Geographic Distribution**: Visitor locations
71
- **Time-based Trends**: Traffic over time periods
72

73
**Library Usage:**
74
```javascript
75
surge.traffic({})(process.argv.slice(2));
76
```
77

78
### Global Load Analytics
79

80
Monitor global network load and performance metrics.
81

82
```javascript { .api }
83
/**
84
 * View global network load analytics
85
 * @param hooks - Optional lifecycle hooks
86
 * @returns Command function
87
 */
88
function load(hooks?: HookConfig): CommandFunction;
89
```
90

91
**CLI Usage:**
92
```bash
93
# View global load metrics
94
surge load
95
```
96

97
**Load Metrics:**
98
- **Edge Node Performance**: Response times across CDN
99
- **Server Load**: CPU and memory utilization
100
- **Network Latency**: Connection speeds
101
- **Availability**: Uptime statistics
102
- **Geographic Performance**: Regional performance data
103

104
**Library Usage:**
105
```javascript
106
surge.load({})(process.argv.slice(2));
107
```
108

109
### Audience Analytics
110

111
Analyze visitor demographics and device information.
112

113
```javascript { .api }
114
/**
115
 * View audience device and demographic analytics
116
 * @param hooks - Optional lifecycle hooks
117
 * @returns Command function
118
 */
119
function audience(hooks?: HookConfig): CommandFunction;
120
```
121

122
**CLI Usage:**
123
```bash
124
# View audience analytics for domain
125
surge audience example.surge.sh
126

127
# Interactive domain selection  
128
surge audience
129
```
130

131
**Audience Metrics:**
132
- **Device Types**: Mobile, desktop, tablet breakdown
133
- **Browser Usage**: Browser and version statistics
134
- **Operating Systems**: OS distribution
135
- **Screen Resolutions**: Display size analytics
136
- **Technology Adoption**: JavaScript, CSS feature usage
137

138
**Library Usage:**
139
```javascript
140
surge.audience({})(process.argv.slice(2));
141
```
142

143
### Usage Analytics
144

145
Monitor bandwidth usage and resource consumption.
146

147
```javascript { .api }
148
/**
149
 * View bandwidth usage and resource analytics
150
 * @param hooks - Optional lifecycle hooks
151
 * @returns Command function
152
 */
153
function usage(hooks?: HookConfig): CommandFunction;
154
```
155

156
**CLI Usage:**
157
```bash
158
# View usage analytics for domain
159
surge usage example.surge.sh
160

161
# Interactive domain selection
162
surge usage
163
```
164

165
**Usage Metrics:**
166
- **Bandwidth Consumption**: Data transfer by time period
167
- **Request Volume**: Number of requests served
168
- **File Type Breakdown**: Usage by content type
169
- **Cache Performance**: Hit/miss ratios
170
- **Cost Analysis**: Usage-based billing information
171

172
**Library Usage:**
173
```javascript
174
surge.usage({})(process.argv.slice(2));
175
```
176

177
### System Audit
178

179
Audit edge node state and system health.
180

181
```javascript { .api }
182
/**
183
 * Audit edge node state and system health
184
 * @param hooks - Optional lifecycle hooks
185
 * @returns Command function
186
 */
187
function audit(hooks?: HookConfig): CommandFunction;
188
```
189

190
**CLI Usage:**
191
```bash
192
# Audit system for domain
193
surge audit example.surge.sh
194

195
# Global system audit
196
surge audit
197
```
198

199
**Audit Information:**
200
- **Edge Node Status**: Health of CDN nodes
201
- **File Synchronization**: Consistency across nodes
202
- **DNS Configuration**: DNS record validation
203
- **SSL Certificate Status**: Certificate health
204
- **Performance Benchmarks**: Speed test results
205

206
**Library Usage:**
207
```javascript
208
surge.audit({})(process.argv.slice(2));
209
```
210

211
### Cache Management
212

213
Bust cache across all edge nodes to force content refresh.
214

215
```javascript { .api }
216
/**
217
 * Bust cache on all edge nodes for immediate content refresh
218
 * @param hooks - Optional lifecycle hooks
219
 * @returns Command function
220
 */
221
function bust(hooks?: HookConfig): CommandFunction;
222
```
223

224
**CLI Usage:**
225
```bash
226
# Bust cache for domain
227
surge bust example.surge.sh
228

229
# Interactive domain selection
230
surge bust
231
```
232

233
**Cache Busting:**
234
- **Global Cache Clear**: Removes cached content from all edge nodes
235
- **Immediate Effect**: New content served immediately
236
- **File-Level Control**: Selective cache invalidation
237
- **Performance Impact**: Temporary increase in origin requests
238

239
**Library Usage:**
240
```javascript
241
surge.bust({})(process.argv.slice(2));
242
```
243

244
## Analytics Data Visualization
245

246
### Chart Display
247

248
Analytics commands display data using ASCII charts and formatted tables:
249

250
```
251
Traffic Analytics - example.surge.sh
252
=====================================
253

254
Page Views (Last 30 Days)
255
     1000 |     *
256
      800 |   * * *
257
      600 | * *   * *
258
      400 |*         *
259
      200 |           *
260
        0 +-------------
261
          1  5  10 15 20 25 30
262

263
Bandwidth Usage: 2.4 GB
264
Unique Visitors: 1,247
265
Top Countries:
266
  1. United States  45%
267
  2. United Kingdom 22%  
268
  3. Canada         15%
269
```
270

271
### Data Export
272

273
Export analytics data for external analysis:
274

275
```bash
276
# Export traffic data to JSON
277
surge traffic example.surge.sh --format json > traffic.json
278

279
# Export usage data to CSV
280
surge usage example.surge.sh --format csv > usage.csv
281
```
282

283
## Performance Monitoring
284

285
### Real-Time Metrics
286

287
Monitor key performance indicators:
288

289
- **Response Times**: Average, median, 95th percentile
290
- **Error Rates**: 4xx and 5xx error frequencies
291
- **Throughput**: Requests per second
292
- **Availability**: Uptime percentage
293
- **Geographic Performance**: Regional response times
294

295
### Historical Analysis
296

297
Track performance trends over time:
298

299
- **Daily Trends**: Performance by hour of day
300
- **Weekly Patterns**: Performance by day of week
301
- **Monthly Growth**: Long-term trend analysis
302
- **Seasonal Variations**: Holiday and event impact
303

304
### Alerting
305

306
Set up monitoring alerts:
307

308
```bash
309
# Configure performance alerts
310
surge config example.surge.sh --alerts enabled
311

312
# Set thresholds
313
surge config example.surge.sh --alert-threshold response-time 500ms
314
surge config example.surge.sh --alert-threshold error-rate 5%
315
```
316

317
## Integration with External Tools
318

319
### Google Analytics
320

321
Integrate Surge analytics with Google Analytics:
322

323
```html
324
<!-- Add to your HTML -->
325
<script async src="https://www.googletagmanager.com/gtag/js?id=GA_TRACKING_ID"></script>
326
<script>
327
  window.dataLayer = window.dataLayer || [];
328
  function gtag(){dataLayer.push(arguments);}
329
  gtag('js', new Date());
330
  gtag('config', 'GA_TRACKING_ID');
331
</script>
332
```
333

334
### Custom Analytics
335

336
Implement custom analytics tracking:
337

338
```javascript
339
// Custom event tracking
340
function trackEvent(event, data) {
341
  fetch('/analytics', {
342
    method: 'POST',
343
    headers: { 'Content-Type': 'application/json' },
344
    body: JSON.stringify({ event, data, timestamp: Date.now() })
345
  });
346
}
347

348
// Page view tracking
349
trackEvent('page_view', { 
350
  page: window.location.pathname,
351
  referrer: document.referrer 
352
});
353
```
354

355
### API Integration
356

357
Access analytics data programmatically:
358

359
```javascript
360
// Fetch analytics via Surge API
361
const analytics = await fetch('https://surge.surge.sh/api/analytics', {
362
  headers: { 'Authorization': `Bearer ${surgeToken}` }
363
});
364
```
365

366
## Privacy and Compliance
367

368
### Data Privacy
369

370
Surge analytics respect user privacy:
371

372
- **No Personal Data**: No personally identifiable information collected
373
- **Aggregated Data**: All metrics are aggregated and anonymized
374
- **GDPR Compliant**: Follows European data protection regulations
375
- **Cookie-Free**: Analytics work without tracking cookies
376

377
### Data Retention
378

379
Analytics data retention policies:
380

381
- **Real-time Data**: Available for 24 hours
382
- **Daily Aggregates**: Retained for 90 days
383
- **Monthly Summaries**: Retained for 2 years
384
- **Custom Retention**: Available with enterprise plans
385

386
## Best Practices
387

388
### Analytics Strategy
389

390
1. **Regular Monitoring**: Check analytics weekly for trends
391
2. **Performance Baselines**: Establish normal performance ranges
392
3. **Alert Configuration**: Set up alerts for critical metrics
393
4. **Data Correlation**: Compare analytics with business metrics
394

395
### Performance Optimization
396

397
1. **Cache Strategy**: Monitor cache hit rates and optimize
398
2. **Content Optimization**: Use analytics to identify heavy resources
399
3. **Geographic Optimization**: Deploy content closer to users
400
4. **Mobile Optimization**: Focus on mobile performance metrics
401

402
### Security Monitoring
403

404
1. **Traffic Patterns**: Monitor for unusual traffic spikes
405
2. **Error Rates**: Watch for increased 4xx/5xx errors
406
3. **Geographic Anomalies**: Identify suspicious traffic sources
407
4. **Performance Degradation**: Detect potential DDoS attacks
408

409
## Troubleshooting
410

411
### Analytics Not Updating
412

413
**Common Causes:**
414
- Data processing delays (up to 1 hour)
415
- DNS propagation issues
416
- CDN cache not refreshed
417

418
**Resolution:**
419
```bash
420
# Force cache refresh
421
surge bust example.surge.sh
422

423
# Verify DNS configuration
424
surge dns example.surge.sh
425

426
# Check system status
427
surge audit example.surge.sh
428
```
429

430
### Inaccurate Data
431

432
**Common Issues:**
433
- Bot traffic included in metrics
434
- Multiple domains pointing to same content
435
- Local development traffic counted
436

437
**Filtering Options:**
438
```bash
439
# Filter bot traffic
440
surge traffic example.surge.sh --filter-bots
441

442
# Exclude specific IPs
443
surge traffic example.surge.sh --exclude-ips 192.168.1.0/24
444
```
445

446
### Performance Issues
447

448
**Diagnostic Commands:**
449
```bash
450
# Check edge node performance
451
surge load --region us-east-1
452

453
# Audit specific domain
454
surge audit example.surge.sh --verbose
455

456
# Test from multiple locations
457
surge traffic example.surge.sh --geo-breakdown
458
```