Analytics & Monitoring

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

Capabilities

Comprehensive Analytics

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

/**
 * View comprehensive analytics for project
 * @param hooks - Optional lifecycle hooks
 * @returns Command function
 */
function analytics(hooks?: HookConfig): CommandFunction;

CLI Usage:

# View comprehensive analytics for domain
surge analytics example.surge.sh

# Interactive domain selection
surge analytics

Analytics Data Includes:

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

Library Usage:

surge.analytics({})(process.argv.slice(2));

Traffic Analytics

View detailed traffic analytics for deployed projects.

/**
 * View traffic analytics for project
 * @param hooks - Optional lifecycle hooks
 * @returns Command function
 */
function traffic(hooks?: HookConfig): CommandFunction;

CLI Usage:

# View traffic for domain
surge traffic example.surge.sh

# Interactive domain selection
surge traffic

Traffic Metrics:

• Page Views: Total page requests
• Unique Visitors: Distinct visitor count
• Bandwidth: Data transfer volume
• Geographic Distribution: Visitor locations
• Time-based Trends: Traffic over time periods

Library Usage:

surge.traffic({})(process.argv.slice(2));

Global Load Analytics

Monitor global network load and performance metrics.

/**
 * View global network load analytics
 * @param hooks - Optional lifecycle hooks
 * @returns Command function
 */
function load(hooks?: HookConfig): CommandFunction;

CLI Usage:

# View global load metrics
surge load

Load Metrics:

• Edge Node Performance: Response times across CDN
• Server Load: CPU and memory utilization
• Network Latency: Connection speeds
• Availability: Uptime statistics
• Geographic Performance: Regional performance data

Library Usage:

surge.load({})(process.argv.slice(2));

Audience Analytics

Analyze visitor demographics and device information.

/**
 * View audience device and demographic analytics
 * @param hooks - Optional lifecycle hooks
 * @returns Command function
 */
function audience(hooks?: HookConfig): CommandFunction;

CLI Usage:

# View audience analytics for domain
surge audience example.surge.sh

# Interactive domain selection  
surge audience

Audience Metrics:

• Device Types: Mobile, desktop, tablet breakdown
• Browser Usage: Browser and version statistics
• Operating Systems: OS distribution
• Screen Resolutions: Display size analytics
• Technology Adoption: JavaScript, CSS feature usage

Library Usage:

surge.audience({})(process.argv.slice(2));

Usage Analytics

Monitor bandwidth usage and resource consumption.

/**
 * View bandwidth usage and resource analytics
 * @param hooks - Optional lifecycle hooks
 * @returns Command function
 */
function usage(hooks?: HookConfig): CommandFunction;

CLI Usage:

# View usage analytics for domain
surge usage example.surge.sh

# Interactive domain selection
surge usage

Usage Metrics:

• Bandwidth Consumption: Data transfer by time period
• Request Volume: Number of requests served
• File Type Breakdown: Usage by content type
• Cache Performance: Hit/miss ratios
• Cost Analysis: Usage-based billing information

Library Usage:

surge.usage({})(process.argv.slice(2));

System Audit

Audit edge node state and system health.

/**
 * Audit edge node state and system health
 * @param hooks - Optional lifecycle hooks
 * @returns Command function
 */
function audit(hooks?: HookConfig): CommandFunction;

CLI Usage:

# Audit system for domain
surge audit example.surge.sh

# Global system audit
surge audit

Audit Information:

• Edge Node Status: Health of CDN nodes
• File Synchronization: Consistency across nodes
• DNS Configuration: DNS record validation
• SSL Certificate Status: Certificate health
• Performance Benchmarks: Speed test results

Library Usage:

surge.audit({})(process.argv.slice(2));

Cache Management

Bust cache across all edge nodes to force content refresh.

/**
 * Bust cache on all edge nodes for immediate content refresh
 * @param hooks - Optional lifecycle hooks
 * @returns Command function
 */
function bust(hooks?: HookConfig): CommandFunction;

CLI Usage:

# Bust cache for domain
surge bust example.surge.sh

# Interactive domain selection
surge bust

Cache Busting:

• Global Cache Clear: Removes cached content from all edge nodes
• Immediate Effect: New content served immediately
• File-Level Control: Selective cache invalidation
• Performance Impact: Temporary increase in origin requests

Library Usage:

surge.bust({})(process.argv.slice(2));

Analytics Data Visualization

Chart Display

Analytics commands display data using ASCII charts and formatted tables:

Traffic Analytics - example.surge.sh
=====================================

Page Views (Last 30 Days)
     1000 |     *
      800 |   * * *
      600 | * *   * *
      400 |*         *
      200 |           *
        0 +-------------
          1  5  10 15 20 25 30

Bandwidth Usage: 2.4 GB
Unique Visitors: 1,247
Top Countries:
  1. United States  45%
  2. United Kingdom 22%  
  3. Canada         15%

Data Export

Export analytics data for external analysis:

# Export traffic data to JSON
surge traffic example.surge.sh --format json > traffic.json

# Export usage data to CSV
surge usage example.surge.sh --format csv > usage.csv

Performance Monitoring

Real-Time Metrics

Monitor key performance indicators:

• Response Times: Average, median, 95th percentile
• Error Rates: 4xx and 5xx error frequencies
• Throughput: Requests per second
• Availability: Uptime percentage
• Geographic Performance: Regional response times

Historical Analysis

Track performance trends over time:

• Daily Trends: Performance by hour of day
• Weekly Patterns: Performance by day of week
• Monthly Growth: Long-term trend analysis
• Seasonal Variations: Holiday and event impact

Alerting

Set up monitoring alerts:

# Configure performance alerts
surge config example.surge.sh --alerts enabled

# Set thresholds
surge config example.surge.sh --alert-threshold response-time 500ms
surge config example.surge.sh --alert-threshold error-rate 5%

Integration with External Tools

Google Analytics

Integrate Surge analytics with Google Analytics:

<!-- Add to your HTML -->
<script async src="https://www.googletagmanager.com/gtag/js?id=GA_TRACKING_ID"></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());
  gtag('config', 'GA_TRACKING_ID');
</script>

Custom Analytics

Implement custom analytics tracking:

// Custom event tracking
function trackEvent(event, data) {
  fetch('/analytics', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ event, data, timestamp: Date.now() })
  });
}

// Page view tracking
trackEvent('page_view', { 
  page: window.location.pathname,
  referrer: document.referrer 
});

API Integration

Access analytics data programmatically:

// Fetch analytics via Surge API
const analytics = await fetch('https://surge.surge.sh/api/analytics', {
  headers: { 'Authorization': `Bearer ${surgeToken}` }
});

Privacy and Compliance

Data Privacy

Surge analytics respect user privacy:

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

Data Retention

Analytics data retention policies:

• Real-time Data: Available for 24 hours
• Daily Aggregates: Retained for 90 days
• Monthly Summaries: Retained for 2 years
• Custom Retention: Available with enterprise plans

Best Practices

Analytics Strategy

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

Performance Optimization

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

Security Monitoring

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

Troubleshooting

Analytics Not Updating

Common Causes:

• Data processing delays (up to 1 hour)
• DNS propagation issues
• CDN cache not refreshed

Resolution:

# Force cache refresh
surge bust example.surge.sh

# Verify DNS configuration
surge dns example.surge.sh

# Check system status
surge audit example.surge.sh

Inaccurate Data

Common Issues:

• Bot traffic included in metrics
• Multiple domains pointing to same content
• Local development traffic counted

Filtering Options:

# Filter bot traffic
surge traffic example.surge.sh --filter-bots

# Exclude specific IPs
surge traffic example.surge.sh --exclude-ips 192.168.1.0/24

Performance Issues

Diagnostic Commands:

# Check edge node performance
surge load --region us-east-1

# Audit specific domain
surge audit example.surge.sh --verbose

# Test from multiple locations
surge traffic example.surge.sh --geo-breakdown