network-performance-analyzer

v1.0.3

Published

6 months ago

Automated analysis tool for network performance test datasets containing DNS testing results and iperf3 performance measurements

Downloads

0High
0Medium
0Low

johnneerdael

network performance analysis iperf3 dns testing typescript

🚀 Network Performance Analyzer

A comprehensive toolkit for analyzing network performance in Netskope Private Access (NPA) environments

Specialized for testing NPA performance with CGNAT validation and multi-configuration analysis

🎯 Purpose

This toolkit is specifically designed for Netskope Private Access (NPA) performance testing. When NPA is properly configured and steered, it returns Carrier-Grade NAT (CGNAT) addresses from the 100.64.0.0/10 range as defined in RFC 6598. Our DNS validation ensures you're testing the correct NPA-steered traffic path.

✨ Key Features

| Feature | Description | Documentation | | ---------------------------------- | --------------------------------------------------------- | ------------------------------------------------------ | | 🔍 Automated Dataset Discovery | Finds and processes network performance test datasets | User Guide | | 📊 Comprehensive Analysis | Analyzes iperf3 and DNS performance across configurations | API Documentation | | ⚖️ Configuration Comparison | Compares MTU sizes, AWS logging, and other parameters | Configuration Guide | | 🚨 Anomaly Detection | Identifies performance outliers and unusual patterns | Extending Guide | | 📝 Detailed Reporting | Generates comprehensive markdown reports with insights | User Guide | | 🔌 Plugin Architecture | Extensible design for custom analysis capabilities | Custom Plugins Guide | | ⚡ Performance Optimized | Parallel processing and streaming for large datasets | Performance Guide | | 🌐 CGNAT Validation | Validates NPA traffic steering via CGNAT IP ranges | DNS Testing Guide |

🚀 Quick Start

Prerequisites

| Requirement | Version | Installation | | ---------------- | -------------- | ------------------------------------------------------------------------------- | | 📦 Node.js | 14.x or higher | Download | | 📦 npm | 6.x or higher | Included with Node.js | | � *Python 3 | 3.7 or higher | Download or system package manager | | � *pip | Latest | Included with Python 3 | | 🔧 iperf3 | Latest | Installation Guide | | 🔧 dig | Latest | Installation Guide |

Python Dependencies for Data Gatherer

The data collection tool requires these Python packages:

# Install Python dependencies for data collection
pip install pandas>=1.0.0 matplotlib>=3.0.0 numpy>=1.18.0

# Or use the requirements file
cd data-gatherer
pip install -r requirements.txt

📥 Installation Options

Option 1: Build from source (Recommended)

# Clone the repository
git clone https://github.com/your-org/network-performance-analyzer.git
cd network-performance-analyzer

# Install dependencies and build
npm install
npm run build

# Link for global usage (makes 'network-performance-analyzer' command available)
npm link

Option 2: Local development setup

# Clone and setup for development
git clone https://github.com/your-org/network-performance-analyzer.git
cd network-performance-analyzer

# Install dependencies
npm install

# Run tests
npm test

# Start development mode
npm run dev

Option 3: Direct usage without global install

# Clone the repository
git clone https://github.com/your-org/network-performance-analyzer.git
cd network-performance-analyzer

# Install dependencies and build
npm install
npm run build

# Run directly with npx
npx . ./datasets

# Or run the built CLI directly
node dist/cli.js ./datasets

⚡ Getting Started in 3 Steps

📊 Collect Data - Use our data gatherer tool:

# Navigate to data gatherer
cd data-gatherer

# Install Python dependencies
pip install -r requirements.txt

# Run performance tests (requires iperf3 servers)
python3 network_performance_tester.py --servers 192.168.1.100

📖 See Data Gatherer Guide for detailed instructions

🔍 Analyze Results - Process your datasets:

# Analyze collected data
network-performance-analyzer ./datasets

📈 Review Reports - Check generated analysis:

# View the generated report
cat network-analysis-report.md

💻 Usage

🎯 Basic Analysis

# Analyze datasets in current directory
network-performance-analyzer ./datasets

# Specify custom output location
network-performance-analyzer ./datasets -o ./reports/npa-analysis.md

🔧 Command Line Options

| Option | Description | Example | | --------------------------------- | ----------------------------- | --------------------------------- | | -o, --output <file> | Output file path | -o ./reports/analysis.md | | -v, --verbose | Enable detailed logging | -v | | -c, --continue-on-error | Continue on dataset failures | -c | | -t, --anomaly-thresholds <json> | Custom anomaly detection | -t '{"bandwidthVariation":0.2}' | | -p, --parallel <number> | Max parallel tasks | -p 8 | | -m, --monitor | Enable performance monitoring | -m | | -e, --environment <env> | Environment configuration | -e production | | -C, --config <file> | Configuration file path | -C ./config.json | | -P, --plugins <dirs> | Plugin directories | -P ./plugins,./custom | | -T, --template <id> | Report template | -T detailed | | -S, --sections <list> | Report sections | -S summary,recommendations |

🚀 Advanced Examples

# 🔍 Comprehensive analysis with custom settings
network-performance-analyzer ./npa-datasets \
  -o ./reports/npa-performance-$(date +%Y%m%d).md \
  -v -m \
  -t '{"bandwidthVariation":0.15,"dnsResponseTimeVariation":0.4}' \
  -e production

# 🔌 Using custom plugins for specialized analysis
network-performance-analyzer ./datasets \
  -P ./custom-plugins \
  -T npa-optimized \
  -S executive-summary,npa-validation,performance-comparison

# ⚡ High-performance analysis for large datasets
network-performance-analyzer ./large-datasets \
  -p 16 \
  -C ./configs/high-performance.json \
  --continue-on-error

📖 For more usage examples, see Troubleshooting and Examples Guide

⚙️ Configuration

The analyzer provides flexible configuration for different testing environments and requirements.

🔧 Quick Configuration

# Generate default configuration
network-performance-analyzer --init-config

# Use environment-specific settings
network-performance-analyzer ./datasets -e production -C ./npa-config.json

📋 Configuration Categories

| Category | Purpose | Documentation | | --------------------------- | ------------------------------- | ---------------------------------------------------------- | | 🔍 Analysis Settings | Control processing behavior | Configuration Reference | | 🚨 Anomaly Thresholds | Customize detection sensitivity | Configuration Reference | | 📊 Reporting Options | Control report generation | User Guide | | 🔌 Plugin Configuration | Manage custom extensions | Custom Plugins Guide | | 🌍 Environment Profiles | Environment-specific settings | Configuration Reference |

📖 For complete configuration options, see Configuration Reference

📁 Dataset Format & Structure

🗂️ Directory Structure

The analyzer expects datasets organized with specific naming patterns for NPA testing:

datasets/
├── coredns-mtu1500-aws-logs_enabled/
│   ├── parameters-results_20250717_120000.json
│   └── results_20250717_120000.json
├── coredns-mtu1420-aws-logs_disabled/
│   ├── parameters-results_20250717_130000.json
│   └── results_20250717_130000.json
└── stock-mtu8920-aws-logs_disabled/
    ├── parameters-results_20250717_140000.json
    └── results_20250717_140000.json

📋 Naming Convention

(coredns|stock)-mtu<size>-aws-logs_(enabled|disabled)

| Component | Description | Example | | ------------------------------ | ------------------ | --------------------------------------- | | coredns\|stock | DNS resolver type | coredns, stock | | mtu<size> | MTU configuration | mtu1500, mtu1420, mtu8920 | | aws-logs_(enabled\|disabled) | AWS logging status | aws-logs_enabled, aws-logs_disabled |

📊 Data Files

Parameters File (`parameters-results_*.json`)

{
  "backendServer": "192.168.1.100",
  "mtu": 1500,
  "queryLogging": "enabled",
  "timestamp": "2025-07-17T12:00:00Z"
}

Results File (`results_*.json`)

{
  "iperfTests": [
    {
      "server": "192.168.1.100",
      "scenario": "TCP Bandwidth (Parallel 4)",
      "success": true,
      "bandwidthMbps": 945.2,
      "retransmits": 12,
      "duration": 15.1
    }
  ],
  "dnsResults": [
    {
      "domain": "example.npa.com",
      "dnsServer": "8.8.8.8",
      "success": true,
      "responseTimeMs": 23.4,
      "resolvedIps": ["100.64.1.10"]
    }
  ]
}

📖 For complete data format specifications, see Data Gatherer Guide

🔌 Extending the Analyzer

The Network Performance Analyzer supports custom plugins for specialized NPA analysis requirements.

🚀 Quick Plugin Development

// Create custom NPA analysis plugin
import { AnalyzerPlugin } from "network-performance-analyzer";

export class NPALatencyPlugin extends AnalyzerPlugin {
  analyze(datasets: Dataset[]): AnalysisResult {
    // Custom NPA-specific latency analysis
    return this.analyzeNPALatencyPatterns(datasets);
  }
}

📚 Plugin Resources

| Resource | Description | Link | | ------------------------- | ------------------------------ | ---------------------------------------------------- | | 🏗️ Plugin Development | Complete plugin creation guide | Custom Plugins Guide | | 🔧 API Reference | Plugin API documentation | API Documentation | | 🎯 Extension Examples | Real-world plugin examples | Extending Guide |

🛠️ Troubleshooting

🚨 Quick Fixes

| Issue | Quick Solution | Documentation | | ------------------------------ | ------------------------------ | ---------------------------------------------------------- | | 📂 No datasets found | Check directory naming pattern | Data Format Guide | | 🔍 Parsing errors | Validate JSON format | Troubleshooting Guide | | 💾 Memory issues | Enable streaming parser | Configuration Reference | | 🌐 CGNAT validation fails | Verify NPA steering | DNS Testing Guide | | 🔧 iperf3 connection fails | Check server setup | Data Gatherer Guide |

🔍 Common Error Solutions

# Fix dataset discovery issues
ls -la datasets/  # Check directory structure
network-performance-analyzer datasets/ -v  # Enable verbose logging

# Resolve memory issues
network-performance-analyzer datasets/ -p 2 -C low-memory-config.json

# Debug CGNAT validation
python3 -c "
import ipaddress
ip = '100.64.1.10'  # Your resolved IP
cgn = ipaddress.ip_network('100.64.0.0/10')
print(f'IP {ip} in CGNAT range: {ipaddress.ip_address(ip) in cgn}')
"

📖 For comprehensive troubleshooting, see Troubleshooting and Examples Guide

📚 Complete Documentation

🎯 Core Guides

📖 User Guide - Complete usage instructions and examples
🔧 API Documentation - Detailed API reference and integration guide
⚙️ Configuration Reference - All configuration options and examples

🚀 Data Collection

📊 Data Gatherer Guide - Complete data collection toolkit
🌐 DNS Testing Guide - DNS performance and CGNAT validation
🏃 iperf3 Test Scenarios - All 18 test scenarios explained

🔧 Advanced Topics

🔌 Custom Plugins Guide - Plugin development and examples
🚀 Extending the Analyzer - Advanced customization
🛠️ Troubleshooting Examples - Solutions and usage examples

🤝 Contributing

We welcome contributions to improve NPA performance testing capabilities!

🚀 Quick Contribution

# Fork and clone the repository
git clone https://github.com/your-username/network-performance-analyzer.git
cd network-performance-analyzer

# Create feature branch
git checkout -b feature/npa-enhancement

# Make changes and test
npm test
npm run lint

# Submit pull request
git push origin feature/npa-enhancement

📋 Contribution Areas

🔍 NPA-specific analysis algorithms
🌐 CGNAT validation improvements
📊 New visualization types
🔌 Plugin examples and templates
📚 Documentation improvements

📄 License

MIT License - see LICENSE file for details.

Built for Netskope Private Access Performance Testing

Ensuring optimal NPA performance through comprehensive network analysis